dbgov-cli 0.2.2 → 0.2.4

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 (2) hide show
  1. package/README.md +219 -64
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,111 +1,266 @@
1
+ <div align="center">
2
+
1
3
  # dbgov-cli
2
4
 
3
- [English](README.md) | [中文](README_zh.md)
5
+ **Governed MySQL & PostgreSQL operations for humans _and_ AI agents.**
6
+
7
+ Run queries, change schemas, and execute DML behind guardrails — every change is measured by `EXPLAIN`, previewed, snapshotted for rollback, and audited, so neither you nor an AI assistant can accidentally nuke a production database.
8
+
9
+ [![npm version](https://img.shields.io/npm/v/dbgov-cli.svg)](https://www.npmjs.com/package/dbgov-cli)
10
+ [![CI](https://github.com/JiangHe12/dbgov-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/JiangHe12/dbgov-cli/actions/workflows/ci.yml)
11
+ [![license](https://img.shields.io/npm/l/dbgov-cli.svg)](LICENSE)
12
+ [![signed](https://img.shields.io/badge/release-cosign%20%2B%20npm%20provenance-blue.svg)](#-trust--verification)
13
+
14
+ [English](README.md) · [简体中文](README_zh.md)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## 🧭 What is this? (read me first)
4
21
 
5
- Governed MySQL and PostgreSQL operations CLI for AI agents and operators. It provides read queries, schema planning and apply, governed DML, GitOps import/reconcile/rollback, audit, RBAC, and local credential management.
22
+ Touching a production database is one of the scariest things in ops: a missing `WHERE` clause, a careless `DROP COLUMN`, or a schema migration gone wrong can lose data in seconds — usually with no preview, no backup, and no record of what happened. Handing that power to a script or an AI agent is even scarier.
6
23
 
7
- ## Overview
24
+ **dbgov-cli wraps every database operation in guardrails.** Think of it as a careful DBA sitting between you and the database:
8
25
 
9
- `dbgov` is built around a governance spine: connect to MySQL or PostgreSQL, classify risk, require explicit authorization for writes, execute through backend interfaces, and write structured audit events.
26
+ - 📏 **Measures impact before acting** — `explain`, `schema plan`, and `--dry-run` tell you *exactly* how many rows or which columns a change will hit. dbgov never guesses; if it can't measure, it refuses.
27
+ - 🛡️ **Scales the friction to the danger** — a one-row update just needs a confirmation; a no-`WHERE` `DELETE` or a `DROP COLUMN` needs a change ticket *and* an explicit "yes, allow destruction" flag.
28
+ - 📸 **Snapshots schema before every mutation** — so you can roll structure back if something's wrong.
29
+ - 👥 **Honors roles** — readers can't write, writers can't do destructive ops, only admins can.
30
+ - 📜 **Audits everything** — every action (including denied ones) lands in a tamper-evident log.
31
+ - 🤖 **Is safe to hand to an AI agent** — it can read and preview freely, but **cannot** invent the human approvals that destructive changes require.
10
32
 
11
- ## Install
33
+ Works with **MySQL** and **PostgreSQL**.
34
+
35
+ ---
36
+
37
+ ## ✨ Features
38
+
39
+ | | |
40
+ |---|---|
41
+ | 🗄️ **Two engines** | **MySQL** and **PostgreSQL**, at full parity. `dbgov capabilities` reports what the current build supports. |
42
+ | 🔎 **Read & explain** | `query` (read-only SQL, rejects writes) and `explain` (real execution plan + estimated rows). |
43
+ | 🧱 **Declarative schema** | `schema list / describe / dump / diff / plan / apply` — diff your DB against a desired `.sql` and apply the delta. |
44
+ | ✏️ **Governed DML** | `data exec` runs `UPDATE`/`DELETE`/`INSERT` with `EXPLAIN`-measured blast radius and risk-scaled authorization. |
45
+ | 🔄 **GitOps for schema** | `export` → `import` → `reconcile` (with drift detection + optional `--prune`) → `rollback` from snapshots. |
46
+ | 🚦 **R0–R3 governance** | every operation is risk-classified; protected contexts escalate one tier; AI callers can never self-authorize. |
47
+ | 👥 **RBAC** | per-context `reader` / `writer` / `admin` roles cap the maximum risk a write path can reach. |
48
+ | 📸 **Snapshots & rollback** | automatic pre-change schema snapshot; structure-level restore with explicit data-loss warnings. |
49
+ | 📜 **Tamper-evident audit** | every operation appended to a hash-verifiable log; `audit verify` detects tampering. |
50
+ | 🔏 **Trusted supply chain** | **cosign-signed** binaries, npm **provenance**, and a **SHA-256**-verified installer. |
51
+
52
+ ---
53
+
54
+ ## 📦 Install
12
55
 
13
56
  ```bash
14
57
  npm install -g dbgov-cli
15
- # or
16
- go install github.com/JiangHe12/dbgov-cli@latest
17
58
  ```
18
59
 
19
- Release binaries are available from GitHub Releases. npm installs download the matching platform binary.
60
+ This installs a tiny launcher; on first run it downloads the right pre-built binary for your OS/arch from the signed [GitHub Release](https://github.com/JiangHe12/dbgov-cli/releases) and **verifies its SHA-256** before use. Requires Node.js ≥ 14 for the installer (the CLI itself is a self-contained Go binary).
61
+
62
+ <details>
63
+ <summary>Other ways to install</summary>
64
+
65
+ - **Direct download** — grab the binary from the [Releases page](https://github.com/JiangHe12/dbgov-cli/releases), verify it against the cosign-signed `checksums.txt`, put it on your `PATH`, and rename it to `dbgov`.
66
+ - **From source** — `go install github.com/JiangHe12/dbgov-cli@latest` (Go 1.22+).
67
+
68
+ ```bash
69
+ dbgov version
70
+ dbgov doctor config -o json # static + read-only diagnostics
71
+ ```
72
+
73
+ </details>
74
+
75
+ ---
20
76
 
21
- ## Quickstart
77
+ ## 🚀 Quick start (60 seconds)
22
78
 
23
79
  ```bash
24
- DBGOV_PASSWORD='<password>' dbgov-cli ctx set local --engine mysql --host 127.0.0.1 --port 3306 --database app --username appuser -o json
25
- dbgov-cli ctx use local -o json
26
- dbgov-cli query --sql "SELECT 1" -o json
27
- dbgov-cli explain --sql "SELECT * FROM users WHERE id = 1" -o json
28
- dbgov-cli schema list -o json
80
+ # 1. Point dbgov at your database (stored as a reusable "context"; password via env)
81
+ DBGOV_PASSWORD='***' dbgov ctx set prod --engine mysql \
82
+ --host 127.0.0.1 --port 3306 --database app --username appuser --env prod --protected
83
+ dbgov ctx use prod
84
+
85
+ # 2. Read — read-only SQL is free (R0) and rejects writes
86
+ dbgov query --sql "SELECT id, name FROM users LIMIT 10" -o json
87
+
88
+ # 3. Measure before you change — see the plan & estimated rows
89
+ dbgov explain --sql "UPDATE users SET active = 0 WHERE last_seen < '2025-01-01'" -o json
90
+
91
+ # 4. Preview a DML change (nothing runs yet)
92
+ dbgov data exec --sql "UPDATE users SET active = 0 WHERE id = 42" --dry-run -o json
93
+
94
+ # 5. Apply it — a small, scoped write (R1) just needs your confirmation
95
+ dbgov data exec --sql "UPDATE users SET active = 0 WHERE id = 42" --yes -o json
96
+
97
+ # 6. See what happened
98
+ dbgov audit query --since 1h -o json
29
99
  ```
30
100
 
31
- Use `-o json` for automation and AI agents.
101
+ > 💡 **Tip:** create production contexts with `--protected`. dbgov then raises every operation one risk tier in that context automatically.
102
+
103
+ ---
104
+
105
+ ## 🔐 The governance model (the important part)
32
106
 
33
- ## Governance Model
107
+ Every command is sorted into a **risk tier**. The more dangerous it is, the more explicit human sign-off it needs:
34
108
 
35
- | Risk | Meaning | Authorization |
36
- |---|---|---|
37
- | R0 | read-only operations and local inspection | no approval required, still audited |
38
- | R1 | incremental writes such as add column, small WHERE DML, incremental import | `--yes` or interactive confirmation |
39
- | R2 | large-impact WHERE DML or protected-context R1 | non-empty `--ticket` plus `--yes` |
40
- | R3 | destructive schema, no-WHERE UPDATE/DELETE, prune, destructive rollback | `--ticket`, required `--allow-*`, and `--yes` |
109
+ | Tier | What it covers | What you must provide |
110
+ |:---:|---|---|
111
+ | **R0** | Reads & inspection (`query`, `explain`, `schema list/describe/dump/diff/plan`, `audit`, `doctor`) | Nothing — but it's still audited |
112
+ | **R1** | Small, safe writes (add a column, `data exec` with `WHERE` and small estimated impact) | `--yes` (or interactive confirmation) |
113
+ | **R2** | Elevated writes (`data exec` whose `EXPLAIN` rows exceed the threshold; any R1 in a protected context) | `--yes` **and** a non-empty `--ticket` |
114
+ | **R3** | Destructive operations (drop/modify column, no-`WHERE` `UPDATE`/`DELETE`, prune, destructive rollback) | The above **plus** the precise `--allow-*` flag |
41
115
 
42
- Allow flags are precise: schema drop/modify uses `--allow-destructive`, no-WHERE DML uses `--allow-no-where`, table prune uses `--allow-production-prune`. Rollback has an R2 floor and may require one or both destructive/prune allow flags. If a context defines `ticketPattern`, tickets must match it; by default no pattern is enforced.
116
+ **R3 allow flags** — destruction is never implicit:
43
117
 
44
- RBAC applies to writes: `reader` is R0, `writer` is up to R2, and `admin` is up to R3. AI agents and automation must not auto-fill `--ticket`, `--allow-*`, or high-risk `--yes`. Impact must come from `dbgov-cli explain`, `schema plan`, or `--dry-run`, never model guesses.
118
+ | Operation | Required flag |
119
+ |---|---|
120
+ | `schema apply` / `import` dropping or modifying a column | `--allow-destructive` |
121
+ | `data exec` with a no-`WHERE` `UPDATE`/`DELETE` | `--allow-no-where` |
122
+ | `reconcile --prune` dropping tables | `--allow-production-prune` |
123
+ | `rollback --to` that drops columns / tables | `--allow-destructive` / `--allow-production-prune` |
45
124
 
46
- All operations, including denied and failed attempts, append to `~/.dbgov/audit.log`. Use `audit query`, `audit verify`, and `audit prune` to inspect, validate, and clean rotated logs.
125
+ **RBAC** (when roles are configured on a context): `reader` → max R0, `writer` → max R2, `admin` → max R3.
47
126
 
48
- ## Usage
127
+ Three rules keep this safe — especially for automation:
128
+
129
+ 1. **Impact comes from the database, not a guess.** Use `explain` / `schema plan` / `--dry-run`. dbgov fails closed rather than estimating.
130
+ 2. **Mutations are snapshotted first.** Rollback restores *structure* only — dropped row data is never recovered (dbgov warns you loudly).
131
+ 3. **🤖 AI agents must never invent `--ticket`, `--allow-*`, or a high-risk `--yes`.** Those are *human* authorization inputs. An agent should surface "this needs approval X" and stop.
132
+
133
+ ---
134
+
135
+ ## 📚 Command reference
136
+
137
+ `dbgov <command> [flags]`. Add `-o json` for machine-readable output, `--help` on any command for its full flags, and `dbgov capabilities -o json` for the supported engines/features.
138
+
139
+ <details open>
140
+ <summary><b>Read & explain</b></summary>
49
141
 
50
142
  ```bash
51
- dbgov-cli version -o json
52
- dbgov-cli capabilities -o json
53
- dbgov-cli doctor config -o json
54
- dbgov-cli ctx list -o json
55
- dbgov-cli ctx export local > local.ctx.yaml
56
- dbgov-cli ctx import -f local.ctx.yaml --rename local-copy -o json
57
- dbgov-cli query --sql "SELECT * FROM users" -o json
58
- dbgov-cli explain --sql "SELECT * FROM users WHERE active = 1" -o json
59
- dbgov-cli schema dump --dir ./schema -o json
60
- dbgov-cli schema plan -f desired.sql -o json
61
- dbgov-cli schema apply -f desired.sql --dry-run -o json
62
- dbgov-cli data exec --sql "UPDATE users SET active=0 WHERE id=1" --dry-run -o json
63
- dbgov-cli export --dir ./schema -o json
64
- dbgov-cli import ./schema --dry-run -o json
65
- dbgov-cli reconcile ./schema --dry-run -o json
66
- dbgov-cli rollback list -o json
67
- dbgov-cli audit query --since 24h -o json
143
+ dbgov query --sql "SELECT ..." -o json # read-only; rejects writes (R0)
144
+ dbgov explain --sql "SELECT ..." -o json # execution plan + estimated rows (R0)
68
145
  ```
146
+ </details>
69
147
 
70
- Schema management normalizes auto-increment columns as a boolean `autoIncrement` model across MySQL and PostgreSQL. It preserves create, introspect, diff, apply, snapshot, and rollback behavior, but intentionally does not preserve PostgreSQL `serial` vs identity, `ALWAYS` vs `BY DEFAULT`, or sequence start/increment options.
148
+ <details>
149
+ <summary><b>Schema</b> — inspect, diff & apply DDL</summary>
71
150
 
72
- ## Configuration and Contexts
151
+ ```bash
152
+ dbgov schema list -o json # R0
153
+ dbgov schema describe <table> -o json # R0
154
+ dbgov schema dump --dir ./schema -o json # R0
155
+ dbgov schema diff -f desired.sql -o json # R0
156
+ dbgov schema plan -f desired.sql -o json # R0 — treat plan risk as authoritative
157
+ dbgov schema apply -f desired.sql --dry-run -o json
158
+ dbgov schema apply -f desired.sql --yes -o json # R1 (incremental)
159
+ dbgov schema apply -f desired.sql --ticket DB-123 --allow-destructive --yes -o json # R3 (destructive)
160
+ ```
73
161
 
74
- Contexts live under `~/.dbgov`. Use `ctx set`, `ctx use`, `ctx current`, and `ctx list` to manage them. Credentials may be literal during setup, read from `DBGOV_PASSWORD`, or migrated to secure backends:
162
+ > Auto-increment columns are modeled as a normalized boolean across both engines; create / diff / apply / snapshot / rollback are preserved, but PostgreSQL `serial`-vs-identity, `ALWAYS`-vs-`BY DEFAULT`, and sequence start/increment options are intentionally **not** preserved.
163
+ </details>
164
+
165
+ <details>
166
+ <summary><b>Governed DML</b> — <code>data exec</code></summary>
75
167
 
76
168
  ```bash
77
- dbgov-cli ctx export prod > prod.ctx.yaml
78
- dbgov-cli ctx import -f prod.ctx.yaml --rename prod-copy -o json
79
- dbgov-cli ctx migrate-credentials --to encrypted-file -o json
80
- dbgov-cli ctx role set prod --target-operator alice --role writer -o json
169
+ dbgov data exec --sql "UPDATE ... WHERE ..." --dry-run -o json # preview impact + required authz
170
+ dbgov data exec --sql "UPDATE ... WHERE id = 42" --yes -o json # R1 small impact
171
+ dbgov data exec --sql "UPDATE ... WHERE <wide>" --ticket DB-123 --yes -o json # R2 large impact
172
+ dbgov data exec --sql "DELETE FROM sessions" --ticket DB-123 --allow-no-where --yes -o json # R3
173
+ dbgov data exec -f change.sql --dry-run -o json # read DML from a file
81
174
  ```
175
+ </details>
176
+
177
+ <details>
178
+ <summary><b>GitOps schema</b> — export · import · reconcile · rollback</summary>
82
179
 
83
- Portable context export redacts passwords by default. `--include-credentials` is only allowed for `plain-yaml` or empty credential backends; secure backend credentials must be shared out of band.
180
+ ```bash
181
+ dbgov export --dir ./schema -o json # dump current schema to files
182
+ dbgov import ./schema --dry-run -o json
183
+ dbgov import ./schema --yes -o json # R1 / R3 if destructive
184
+ dbgov reconcile ./schema --dry-run -o json # detect drift
185
+ dbgov reconcile ./schema --yes -o json
186
+ dbgov reconcile ./schema --prune --ticket DB-123 --allow-production-prune --yes -o json # R3 prune
187
+ dbgov rollback list -o json # list pre-change snapshots
188
+ dbgov rollback --to <snapshot-id> --dry-run -o json
189
+ dbgov rollback --to <snapshot-id> --ticket DB-123 --yes -o json # structure only; data not recovered
190
+ ```
191
+ </details>
84
192
 
85
- Set `DBGOV_OPERATOR` in CI to make audit and RBAC identity stable.
193
+ <details>
194
+ <summary><b>Contexts, roles, audit & diagnostics</b></summary>
86
195
 
87
- ## Rollback and Snapshots
196
+ ```bash
197
+ # Contexts (MySQL or PostgreSQL)
198
+ dbgov ctx set <name> --engine mysql|postgres --host <h> --port <p> --database <db> --username <u> [--protected]
199
+ dbgov ctx use|list|current|delete
200
+ dbgov ctx export <name> [--include-credentials] -o json
201
+ dbgov ctx import -f ctx.yaml [--rename <new>] [--force] -o json
202
+ dbgov ctx migrate-credentials --to encrypted-file|keychain [--context <name>] -o json
203
+
204
+ # RBAC (write paths only): reader → R0, writer → R2, admin → R3
205
+ dbgov ctx role set <context> --target-operator alice --role writer -o json
206
+ dbgov ctx role list <context> -o json
207
+
208
+ # Audit (tamper-evident; rotated logs only for prune)
209
+ dbgov audit query [--since 24h] [--risk R2] [--limit 50] -o json
210
+ dbgov audit verify -o json
211
+ dbgov audit prune (--before <30d|YYYY-MM-DD> | --keep-last <n>) [--confirm] -o json
212
+
213
+ # Diagnostics & ecosystem
214
+ dbgov doctor config|network|auth -o json
215
+ dbgov capabilities -o json
216
+ dbgov completion bash|zsh|fish|powershell
217
+ dbgov install <agent> --skills # install the dbgov AI skill (claude, codex, …)
218
+ dbgov version
219
+ ```
88
220
 
89
- Schema mutations capture a pre-change DDL snapshot before execution. `rollback --to <snapshot>` restores structure only; MySQL and PostgreSQL data dropped by table or column deletion is not recovered. dbgov prints this warning during rollback planning and execution.
221
+ > `audit prune` only deletes **rotated** logs (never the active `audit.log`), defaults to a dry-run, and needs `--confirm` to remove files. Set `DBGOV_OPERATOR` in CI to keep audit/RBAC identity stable.
222
+ </details>
90
223
 
91
- ## Build from Source
224
+ ---
225
+
226
+ ## 🤖 For AI agents
227
+
228
+ - Run `dbgov capabilities -o json` first — it's the authoritative source for supported engines and features.
229
+ - Use `-o json` everywhere; every command returns a stable, versioned envelope.
230
+ - Get blast radius from `explain` / `schema plan` / `--dry-run`, **never** from your own reasoning.
231
+ - **Never self-fill `--ticket`, `--allow-*`, or a high-risk `--yes`.** Surface the required human approval and stop.
232
+
233
+ ```bash
234
+ dbgov install claude --skills # also: codex, opencode, copilot, cursor, windsurf, aider, cc-switch
235
+ ```
236
+
237
+ ---
238
+
239
+ ## 🔏 Trust & verification
240
+
241
+ - **Signed binaries** — every release artifact is signed with [cosign](https://github.com/sigstore/cosign) (keyless / OIDC); a signed `checksums.txt` covers all platforms.
242
+ - **npm provenance** — published from CI via OpenID Connect with [provenance attestations](https://docs.npmjs.com/generating-provenance-statements) tying the package to this repo and workflow.
243
+ - **Verified installs** — the npm postinstall checks the binary's SHA-256 against the signed `checksums.txt` before installing.
244
+ - **Tamper-evident audit** — `dbgov audit verify` re-walks the log and reports any gap or modification.
245
+
246
+ ---
247
+
248
+ ## 🏗️ Build from source & contribute
92
249
 
93
250
  ```bash
251
+ git clone https://github.com/JiangHe12/dbgov-cli && cd dbgov-cli
94
252
  go build ./...
95
253
  go test -count=1 ./...
96
- gofmt -l main.go cmd internal
254
+ gofmt -l main.go cmd internal # must print nothing
97
255
  golangci-lint run --timeout=5m
98
256
  ```
99
257
 
100
- MySQL and PostgreSQL integration tests are opt-in with `DBGOV_TEST_MYSQL_DSN` and `DBGOV_TEST_POSTGRES_DSN`.
258
+ MySQL / PostgreSQL integration tests are opt-in via `DBGOV_TEST_MYSQL_DSN` and `DBGOV_TEST_POSTGRES_DSN`. See [CONTRIBUTING.md](CONTRIBUTING.md) and the security policy in [SECURITY.md](SECURITY.md).
101
259
 
102
- ## AI Skill
260
+ dbgov-cli is built on the shared [`opskit-core`](https://github.com/JiangHe12/opskit-core) governance engine and is part of the **opskit** family of governed CLIs for AI agents — alongside [`cfgov-cli`](https://www.npmjs.com/package/cfgov-cli) (config & Sentinel rules) and `srvgov-cli` (remote servers).
103
261
 
104
- ```bash
105
- dbgov-cli install claude --skills
106
- dbgov-cli install codex --skills
107
- ```
262
+ ---
108
263
 
109
- ## Contributing, Security, License
264
+ ## 📄 License
110
265
 
111
- See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE).
266
+ [MIT](LICENSE) © JiangHe12
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dbgov-cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.4",
4
4
  "description": "Governed MySQL and PostgreSQL operations CLI for AI agents",
5
5
  "bin": {
6
6
  "dbgov": "bin/dbgov-cli.js",