dbctx 1.4.2 → 1.4.6

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 +137 -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,143 @@
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@latest 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
+ `pnpx dbctx@latest` and `bunx dbctx@latest` work too.
26
+
27
+ ## Connection
28
+
29
+ ### Connection String
30
+
31
+ ```sh
32
+ npx dbctx@latest postgres://user:password@host:5432/dbname
33
+ ```
34
+
35
+ ### Environment Variables
36
+
37
+ dbctx reads standard PostgreSQL environment variables:
38
+
39
+ ```sh
40
+ export DATABASE_URL=postgres://user:password@host:5432/dbname
41
+ npx dbctx@latest
42
+ ```
43
+
44
+ Or use individual variables:
45
+
46
+ ```sh
47
+ export PGHOST=localhost
48
+ export PGPORT=5432
49
+ export PGDATABASE=mydb
50
+ export PGUSER=postgres
51
+ export PGPASSWORD=secret
52
+ npx dbctx@latest
53
+ ```
54
+
55
+ ### CLI Flags
56
+
57
+ ```
58
+ -h, --hostname <host> Database hostname (env: PGHOST, default: localhost)
59
+ -p, --port <port> Database port (env: PGPORT, default: 5432)
60
+ -d, --database <name> Database name (env: PGDATABASE, default: postgres)
61
+ -U, --username <user> Database username (env: PGUSER, default: postgres)
62
+ ```
63
+
64
+ If no password is provided, dbctx prompts interactively in the terminal.
65
+
66
+ ## SSH Tunneling
4
67
 
5
- ## Usage
68
+ Connect through a bastion or jump server:
6
69
 
70
+ ```sh
71
+ npx dbctx@latest --ssh user@bastion.example.com postgres://localhost:5432/mydb
7
72
  ```
8
- npx dbctx [connection_string]
73
+
74
+ 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.
75
+
76
+ ### SSH Options
77
+
78
+ ```
79
+ --ssh <target> SSH tunnel target (user@host[:port])
80
+ --ssh-host <host> SSH tunnel host
81
+ --ssh-port <port> SSH tunnel port (default: 22)
82
+ --ssh-username <user> SSH tunnel username (default: $USER)
83
+ -i, --ssh-key <path> Path to SSH private key (default: ~/.ssh/id_rsa)
9
84
  ```
85
+
86
+ Encrypted SSH keys are supported — dbctx prompts for the passphrase when needed.
87
+
88
+ ## SSL / TLS
89
+
90
+ ```
91
+ --sslmode <mode> disable | allow | prefer | require | verify-ca | verify-full
92
+ (env: PGSSLMODE, default: prefer)
93
+ --sslcert <path> Path to client certificate (env: PGSSLCERT)
94
+ --sslkey <path> Path to client private key (env: PGSSLKEY)
95
+ --sslrootcert <path> Path to root CA certificate (env: PGSSLROOTCERT)
96
+ ```
97
+
98
+ Tilde paths (`~/.ssl/cert.pem`) are expanded automatically.
99
+
100
+ ## What Gets Introspected
101
+
102
+ dbctx reads the `public` schema and collects:
103
+
104
+ - **Relations** — tables, views, materialized views, partitioned tables
105
+ - **Columns** — name, type, nullability, defaults, generated expressions, comments
106
+ - **Indexes** — primary keys, unique, partial, exclusion, with definitions
107
+ - **Foreign Keys** — referenced table, columns, ON UPDATE / ON DELETE actions
108
+ - **Enums** — all values and comments
109
+ - **Statistics** — estimated row counts and distinct values per column (via `ANALYZE`)
110
+ - **Database metadata** — PostgreSQL version, system identifier, database comments
111
+
112
+ All of this is assembled into a single `DB.md` file.
113
+
114
+ ## Environment Variables Reference
115
+
116
+ | Variable | Description |
117
+ |-----------------|--------------------------------------------------|
118
+ | `DATABASE_URL` | PostgreSQL connection string |
119
+ | `PGHOST` | Database hostname |
120
+ | `PGPORT` | Database port |
121
+ | `PGDATABASE` | Database name |
122
+ | `PGUSER` | Database username |
123
+ | `PGPASSWORD` | Database password |
124
+ | `PGSSLMODE` | SSL mode |
125
+ | `PGSSLCERT` | Path to client certificate |
126
+ | `PGSSLKEY` | Path to client private key |
127
+ | `PGSSLROOTCERT` | Path to root CA certificate |
128
+ | `DO_NOT_TRACK` | Set to `1` or `true` to disable telemetry |
129
+ | `DBCTX_DEV` | Enable debug logging |
130
+
131
+ ## Telemetry
132
+
133
+ dbctx collects anonymous usage telemetry (OS, shell, which flags were used) to improve the tool. No database content or credentials are ever sent.
134
+
135
+ Opt out:
136
+
137
+ ```sh
138
+ export DO_NOT_TRACK=1
139
+ ```
140
+
141
+ ## License
142
+
143
+ [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.6",
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
  },