Managing Remote Database Schemas with Kolumn CLI: A Practical Guide for Data Engineers
Schema drift is one of the quietest killers in a data engineering stack. A column gets renamed in production. A new NOT NULL constraint lands without a migration. A warehouse table diverges from its source. You find out when the pipeline breaks at 2am.
Kolumn CLI was built to close that gap — giving data engineers stateful visibility into remote database schemas without SSH tunnels, manual queries, or tribal knowledge baked into undocumented runbooks.
This guide walks through the core use cases: connecting to remote databases, inspecting schema state, detecting drift, and integrating schema management into your team's workflow.
What Is Kolumn CLI?
Kolumn CLI is a command-line tool from SchemaBounce that makes remote database schema management stateful and observable. Where traditional tools give you a point-in-time snapshot, Kolumn tracks schema state over time — so you can answer questions like:
- What changed in this table since last week?
- Which environments are out of sync?
- Which schema change broke the downstream dbt model?
It's designed for data engineers who manage schemas across multiple environments (dev, staging, prod) and multiple systems (Postgres, warehouses, SaaS connectors).
Why Stateful Schema Management Matters
Most teams manage schemas reactively. A migration runs, and if nothing breaks, the change is considered "done." The problem is that schema state lives in multiple places simultaneously:
- The source database (Postgres, MySQL, etc.)
- The data warehouse (Snowflake, BigQuery, Redshift)
- The ETL pipeline expectations
- The downstream tools consuming that data (dbt models, BI dashboards, AI agents)
When any one of these diverges, your data contracts break silently. Stateful schema management means you have a single source of truth for what schema state should be, and a tool that can detect when reality diverges from it.
Getting Started with Kolumn CLI
Installation
Install Kolumn CLI via your package manager or download directly from the SchemaBounce distribution:
# macOS / Linux
curl -sSL https://install.schemabounce.com/kolumn | bash
# Verify installation
kolumn --version
Connecting to a Remote Database
Kolumn uses a connection profile system. You register a database once and reference it by alias:
# Register a remote Postgres instance
kolumn connect add \
--alias prod-postgres \
--type postgres \
--host db.yourcompany.com \
--port 5432 \
--database analytics \
--user kolumn_reader
# List registered connections
kolumn connect list
Credentials are stored in your local keychain or a secrets manager — Kolumn never writes plaintext credentials to disk.
Inspecting Remote Schema State
Once connected, you can pull and inspect schema metadata:
# List all schemas in a database
kolumn schema list --connection prod-postgres
# Inspect a specific table
kolumn schema inspect prod-postgres.public.orders
# Output example:
# Table: public.orders
# Columns:
# id BIGINT NOT NULL PRIMARY KEY
# customer_id BIGINT NOT NULL
# status VARCHAR(50) NOT NULL
# total_amount NUMERIC(10,2) NULL
# created_at TIMESTAMP NOT NULL DEFAULT now()
# updated_at TIMESTAMP NULL
The inspect command returns the current schema state from the live database. Kolumn stores a snapshot of this state locally so you can compare it against future states or other environments.
Detecting Schema Drift
This is where Kolumn earns its keep. Once you've captured a baseline snapshot, you can diff any two states:
# Save a snapshot
kolumn snapshot save prod-postgres --label "pre-migration-2026-05-01"
# Run your migration, then diff
kolumn snapshot diff \
--from "pre-migration-2026-05-01" \
--to current \
--connection prod-postgres
# Example diff output:
# ADDED public.orders.cancelled_at TIMESTAMP NULL
# ALTERED public.orders.status VARCHAR(50) -> VARCHAR(100)
# DROPPED public.orders.legacy_flag BOOLEAN
You can also diff across environments to catch the "it works in staging" problem before it reaches production:
kolumn snapshot diff \
--from staging-postgres.public.orders \
--to prod-postgres.public.orders
Integrating Kolumn into Your CI/CD Pipeline
Schema drift doesn't get caught by unit tests. Add Kolumn to your deployment pipeline to make it a hard gate:
# .github/workflows/deploy.yml (excerpt)
- name: Check schema drift before deployment
run: |
kolumn snapshot diff \
--from baseline \
--to current \
--connection prod-postgres \
--exit-on-change
env:
KOLUMN_TOKEN: ${{ secrets.KOLUMN_TOKEN }}
The --exit-on-change flag causes the CLI to return a non-zero exit code if any schema change is detected — blocking the deployment until the diff is reviewed.
For teams using dbt, Kolumn can export schema state in a format compatible with dbt source definitions:
# Export schema as dbt source YAML
kolumn schema export prod-postgres.public \
--format dbt-sources \
--output ./models/sources.yml
Remote Schema Visibility for AI Agents
SchemaBounce's broader platform connects databases to AI agents — and Kolumn is the schema layer that makes that safe. When an AI agent reads from or writes back to a database, it needs to know the current schema — not a stale version cached at deploy time.
Kolumn exposes a programmatic API that AI agents can query at runtime:
# Get schema as JSON (useful for programmatic consumption)
kolumn schema inspect prod-postgres.public.customers --format json
This means your AI workflows always operate against live schema metadata — preventing type mismatches, missing column errors, and the class of bugs that happen when agent code was written against last month's schema.
Schema Governance for Multi-Environment Teams
For teams managing more than two environments, Kolumn supports a registry model — a central record of approved schema states:
# Promote a schema state to the registry
kolumn registry push \
--connection prod-postgres \
--label "approved-2026-Q2" \
--message "Post Q2 migration, reviewed by data platform team"
# Any environment can validate against the registry
kolumn registry validate \
--connection staging-postgres \
--against "approved-2026-Q2"
This creates an audit trail: who approved a schema state, when, and which environments are compliant.
Key Takeaways
- Schema drift is silent — Kolumn makes it observable by maintaining stateful snapshots across environments and time.
- Connection profiles make multi-environment management first-class, not an afterthought.
- CI/CD integration turns schema drift detection into a deployment gate, not a post-incident retrospective.
- AI agent compatibility ensures your automated workflows always see current schema metadata.
- Registry governance gives data platform teams a paper trail for schema approvals.
If you're managing schemas across more than one environment today, Kolumn CLI is worth adding to your standard toolchain.
SchemaBounce builds ETL infrastructure that connects databases, warehouses, and SaaS tools to AI agents. Learn more →