dbctx 1.4.2 → 1.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +181 -3
  3. package/package.json +18 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 AirState
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,9 +1,187 @@
1
+ ```
2
+ ▛▀▖▛▀▖▞▀▖▀▛▘▌ ▌
3
+ ▌ ▌▙▄▘▌ ▌ ▝▞
4
+ ▌ ▌▌ ▌▌ ▖ ▌ ▞▝▖
5
+ ▀▀ ▀▀ ▝▀ ▘ ▘ ▘
6
+ ```
7
+
1
8
  # dbctx
2
9
 
3
- > AI Enriched Database Context for Humans & Coding Agents
10
+ [![npm version](https://img.shields.io/npm/v/dbctx)](https://www.npmjs.com/package/dbctx)
11
+ [![license](https://img.shields.io/npm/l/dbctx)](./LICENSE)
12
+
13
+ **AI-enriched database context for humans and coding agents.**
14
+
15
+ 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.
16
+
17
+ ## Quick Start
18
+
19
+ ```sh
20
+ npx dbctx postgres://user:password@localhost:5432/mydb
21
+ ```
22
+
23
+ That's it. dbctx connects, introspects, and writes a `DB.md` to your working directory.
24
+
25
+ ### Example Output
26
+
27
+ Running against a database produces a `DB.md` like this:
28
+
29
+ ```md
30
+ # mydb
31
+
32
+ PostgreSQL 16.2 — system identifier `7312456789012345678`
33
+
34
+ ## Tables
35
+
36
+ ### users
37
+
38
+ | Column | Type | Nullable | Default |
39
+ |--------------|--------------------------|----------|----------------------|
40
+ | id | uuid | NO | gen_random_uuid() |
41
+ | email | character varying(255) | NO | |
42
+ | display_name | text | YES | |
43
+ | created_at | timestamp with time zone | NO | now() |
44
+
45
+ **Indexes**
46
+ - `users_pkey` PRIMARY KEY (id)
47
+ - `users_email_key` UNIQUE (email)
48
+
49
+ ### orders
50
+
51
+ | Column | Type | Nullable | Default |
52
+ |---------|--------------------------|----------|-------------------|
53
+ | id | uuid | NO | gen_random_uuid() |
54
+ | user_id | uuid | NO | |
55
+ | status | order_status | NO | 'pending' |
56
+ | total | numeric(10,2) | NO | |
57
+
58
+ **Indexes**
59
+ - `orders_pkey` PRIMARY KEY (id)
60
+ - `orders_user_id_idx` (user_id)
61
+
62
+ **References**
63
+ - `orders_user_id_fkey` (user_id) → users (id) ON DELETE CASCADE
64
+
65
+ ## Enums
66
+
67
+ ### order_status
68
+ `pending`, `confirmed`, `shipped`, `delivered`, `cancelled`
69
+ ```
70
+
71
+ ## Connection
72
+
73
+ ### Connection String
74
+
75
+ ```sh
76
+ npx dbctx postgres://user:password@host:5432/dbname
77
+ ```
78
+
79
+ ### Environment Variables
80
+
81
+ dbctx reads standard PostgreSQL environment variables:
82
+
83
+ ```sh
84
+ export DATABASE_URL=postgres://user:password@host:5432/dbname
85
+ npx dbctx
86
+ ```
87
+
88
+ Or use individual variables:
89
+
90
+ ```sh
91
+ export PGHOST=localhost
92
+ export PGPORT=5432
93
+ export PGDATABASE=mydb
94
+ export PGUSER=postgres
95
+ export PGPASSWORD=secret
96
+ npx dbctx
97
+ ```
98
+
99
+ ### CLI Flags
100
+
101
+ ```
102
+ -h, --hostname <host> Database hostname (env: PGHOST, default: localhost)
103
+ -p, --port <port> Database port (env: PGPORT, default: 5432)
104
+ -d, --database <name> Database name (env: PGDATABASE, default: postgres)
105
+ -U, --username <user> Database username (env: PGUSER, default: postgres)
106
+ ```
107
+
108
+ If no password is provided, dbctx prompts interactively in the terminal.
109
+
110
+ ## SSH Tunneling
111
+
112
+ Connect through a bastion or jump server:
113
+
114
+ ```sh
115
+ npx dbctx --ssh user@bastion.example.com postgres://localhost:5432/mydb
116
+ ```
117
+
118
+ 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.
119
+
120
+ ### SSH Options
121
+
122
+ ```
123
+ --ssh <target> SSH tunnel target (user@host[:port])
124
+ --ssh-host <host> SSH tunnel host
125
+ --ssh-port <port> SSH tunnel port (default: 22)
126
+ --ssh-username <user> SSH tunnel username (default: $USER)
127
+ -i, --ssh-key <path> Path to SSH private key (default: ~/.ssh/id_rsa)
128
+ ```
129
+
130
+ Encrypted SSH keys are supported — dbctx prompts for the passphrase when needed.
4
131
 
5
- ## Usage
132
+ ## SSL / TLS
6
133
 
7
134
  ```
8
- npx dbctx [connection_string]
135
+ --sslmode <mode> disable | allow | prefer | require | verify-ca | verify-full
136
+ (env: PGSSLMODE, default: prefer)
137
+ --sslcert <path> Path to client certificate (env: PGSSLCERT)
138
+ --sslkey <path> Path to client private key (env: PGSSLKEY)
139
+ --sslrootcert <path> Path to root CA certificate (env: PGSSLROOTCERT)
140
+ ```
141
+
142
+ Tilde paths (`~/.ssl/cert.pem`) are expanded automatically.
143
+
144
+ ## What Gets Introspected
145
+
146
+ dbctx reads the `public` schema and collects:
147
+
148
+ - **Relations** — tables, views, materialized views, partitioned tables
149
+ - **Columns** — name, type, nullability, defaults, generated expressions, comments
150
+ - **Indexes** — primary keys, unique, partial, exclusion, with definitions
151
+ - **Foreign Keys** — referenced table, columns, ON UPDATE / ON DELETE actions
152
+ - **Enums** — all values and comments
153
+ - **Statistics** — estimated row counts and distinct values per column (via `ANALYZE`)
154
+ - **Database metadata** — PostgreSQL version, system identifier, database comments
155
+
156
+ All of this is assembled into a single `DB.md` file.
157
+
158
+ ## Environment Variables Reference
159
+
160
+ | Variable | Description |
161
+ |-----------------|--------------------------------------------------|
162
+ | `DATABASE_URL` | PostgreSQL connection string |
163
+ | `PGHOST` | Database hostname |
164
+ | `PGPORT` | Database port |
165
+ | `PGDATABASE` | Database name |
166
+ | `PGUSER` | Database username |
167
+ | `PGPASSWORD` | Database password |
168
+ | `PGSSLMODE` | SSL mode |
169
+ | `PGSSLCERT` | Path to client certificate |
170
+ | `PGSSLKEY` | Path to client private key |
171
+ | `PGSSLROOTCERT` | Path to root CA certificate |
172
+ | `DO_NOT_TRACK` | Set to `1` or `true` to disable telemetry |
173
+ | `DBCTX_DEV` | Enable debug logging |
174
+
175
+ ## Telemetry
176
+
177
+ dbctx collects anonymous usage telemetry (OS, shell, which flags were used) to improve the tool. No database content or credentials are ever sent.
178
+
179
+ Opt out:
180
+
181
+ ```sh
182
+ export DO_NOT_TRACK=1
9
183
  ```
184
+
185
+ ## License
186
+
187
+ [MIT](./LICENSE)
package/package.json CHANGED
@@ -1,19 +1,33 @@
1
1
  {
2
2
  "name": "dbctx",
3
- "version": "1.4.2",
4
- "description": "dbctx CLI",
3
+ "version": "1.4.5",
4
+ "description": "AI-enriched database context for humans and coding agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.mjs",
7
7
  "bin": {
8
8
  "dbctx": "./dist/index.mjs"
9
9
  },
10
- "keywords": [],
10
+ "keywords": [
11
+ "postgresql",
12
+ "database",
13
+ "schema",
14
+ "introspection",
15
+ "cli",
16
+ "ai",
17
+ "context",
18
+ "documentation"
19
+ ],
11
20
  "author": {
12
21
  "name": "AirState",
13
22
  "email": "hello@airstate.dev",
14
23
  "url": "https://airstate.dev"
15
24
  },
16
- "license": "UNLICENSED",
25
+ "homepage": "https://dbctx.io",
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "https://github.com/dbctx/dbctx"
29
+ },
30
+ "license": "MIT",
17
31
  "imports": {
18
32
  "#client/*": "./dist/*"
19
33
  },