▛▀▖▛▀▖▞▀▖▀▛▘▌ ▌
▌ ▌▙▄▘▌   ▌ ▝▞
▌ ▌▌ ▌▌ ▖ ▌ ▞▝▖
▀▀ ▀▀ ▝▀  ▘ ▘ ▘

dbctx

AI-enriched database context for humans and coding agents.

dbctx connects to your PostgreSQL database, introspects the entire schema, and generates a DB.md file containing every table, view, column, index, foreign key, and enum — enriched with comments and statistics. The result is a single Markdown file that gives you (or your AI coding agent) complete database context without ever touching production data.

Quick Start

npx dbctx@latest postgres://user:password@localhost:5432/mydb

That's it. dbctx connects, introspects, and writes a DB.md to your working directory.

pnpx dbctx@latest and bunx dbctx@latest work too.

Connection

Connection String

npx dbctx@latest postgres://user:password@host:5432/dbname

Environment Variables

dbctx reads standard PostgreSQL environment variables:

export DATABASE_URL=postgres://user:password@host:5432/dbname
npx dbctx@latest

Or use individual variables:

export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=mydb
export PGUSER=postgres
export PGPASSWORD=secret
npx dbctx@latest

CLI Flags

-h, --hostname <host>     Database hostname (env: PGHOST, default: localhost)
-p, --port <port>         Database port (env: PGPORT, default: 5432)
-d, --database <name>     Database name (env: PGDATABASE, default: postgres)
-U, --username <user>     Database username (env: PGUSER, default: postgres)

If no password is provided, dbctx prompts interactively in the terminal.

SSH Tunneling

Connect through a bastion or jump server:

npx dbctx@latest --ssh [email protected] postgres://localhost:5432/mydb

dbctx opens an SSH tunnel and forwards the database connection through it. Your ~/.ssh/config is automatically parsed for host aliases, key paths, and ports.

SSH Options

--ssh <target>            SSH tunnel target (user@host[:port])
--ssh-host <host>         SSH tunnel host
--ssh-port <port>         SSH tunnel port (default: 22)
--ssh-username <user>     SSH tunnel username (default: $USER)
-i, --ssh-key <path>      Path to SSH private key (default: ~/.ssh/id_rsa)

Encrypted SSH keys are supported — dbctx prompts for the passphrase when needed.

SSL / TLS

--sslmode <mode>          disable | allow | prefer | require | verify-ca | verify-full
                          (env: PGSSLMODE, default: prefer)
--sslcert <path>          Path to client certificate (env: PGSSLCERT)
--sslkey <path>           Path to client private key (env: PGSSLKEY)
--sslrootcert <path>      Path to root CA certificate (env: PGSSLROOTCERT)

Tilde paths (~/.ssl/cert.pem) are expanded automatically.

What Gets Introspected

dbctx reads the public schema and collects:

• Relations — tables, views, materialized views, partitioned tables
• Columns — name, type, nullability, defaults, generated expressions, comments
• Indexes — primary keys, unique, partial, exclusion, with definitions
• Foreign Keys — referenced table, columns, ON UPDATE / ON DELETE actions
• Enums — all values and comments
• Statistics — estimated row counts and distinct values per column (via ANALYZE)
• Database metadata — PostgreSQL version, system identifier, database comments

All of this is assembled into a single DB.md file.

Environment Variables Reference

| Variable | Description | |-----------------|--------------------------------------------------| | DATABASE_URL | PostgreSQL connection string | | PGHOST | Database hostname | | PGPORT | Database port | | PGDATABASE | Database name | | PGUSER | Database username | | PGPASSWORD | Database password | | PGSSLMODE | SSL mode | | PGSSLCERT | Path to client certificate | | PGSSLKEY | Path to client private key | | PGSSLROOTCERT | Path to root CA certificate | | DO_NOT_TRACK | Set to 1 or true to disable telemetry | | DBCTX_DEV | Enable debug logging |

Telemetry

dbctx collects anonymous usage telemetry (OS, shell, which flags were used) to improve the tool. No database content or credentials are ever sent.

Opt out:

export DO_NOT_TRACK=1

License

MIT