dbgov-cli 0.1.2 → 0.1.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 +101 -101
  2. package/package.json +35 -34
package/README.md CHANGED
@@ -1,109 +1,109 @@
1
- # dbgov-cli
2
-
3
- [English](README.md) | [中文](README_zh.md)
4
-
5
- Governed MySQL 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.
6
-
7
- ## Overview
8
-
9
- `dbgov` is built around a governance spine: connect to MySQL, classify risk, require explicit authorization for writes, execute through backend interfaces, and write structured audit events. It is MySQL-only today; PostgreSQL is planned but not enabled unless capabilities report it.
10
-
11
- ## Install
12
-
13
- ```bash
14
- npm install -g dbgov-cli
15
- # or
16
- go install github.com/JiangHe12/dbgov-cli@latest
17
- ```
18
-
19
- Release binaries are available from GitHub Releases. npm installs download the matching platform binary.
20
-
21
- ## Quickstart
22
-
23
- ```bash
24
- DBGOV_PASSWORD='<password>' dbgov ctx set local --engine mysql --host 127.0.0.1 --port 3306 --database app --username appuser -o json
25
- dbgov ctx use local -o json
26
- dbgov query --sql "SELECT 1" -o json
27
- dbgov explain --sql "SELECT * FROM users WHERE id = 1" -o json
28
- dbgov schema list -o json
29
- ```
30
-
31
- Use `-o json` for automation and AI agents.
32
-
33
- ## Governance Model
34
-
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` |
41
-
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.
43
-
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 explain`, `schema plan`, or `--dry-run`, never model guesses.
45
-
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.
47
-
48
- ## Usage
49
-
50
- ```bash
51
- dbgov version -o json
52
- dbgov capabilities -o json
53
- dbgov doctor config -o json
54
- dbgov ctx list -o json
55
- dbgov ctx export local > local.ctx.yaml
56
- dbgov ctx import -f local.ctx.yaml --rename local-copy -o json
57
- dbgov query --sql "SELECT * FROM users" -o json
58
- dbgov explain --sql "SELECT * FROM users WHERE active = 1" -o json
59
- dbgov schema dump --dir ./schema -o json
60
- dbgov schema plan -f desired.sql -o json
61
- dbgov schema apply -f desired.sql --dry-run -o json
62
- dbgov data exec --sql "UPDATE users SET active=0 WHERE id=1" --dry-run -o json
63
- dbgov export --dir ./schema -o json
64
- dbgov import ./schema --dry-run -o json
65
- dbgov reconcile ./schema --dry-run -o json
66
- dbgov rollback list -o json
67
- dbgov audit query --since 24h -o json
68
- ```
69
-
70
- ## Configuration and Contexts
71
-
1
+ # dbgov-cli
2
+
3
+ [English](README.md) | [中文](README_zh.md)
4
+
5
+ Governed MySQL 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.
6
+
7
+ ## Overview
8
+
9
+ `dbgov` is built around a governance spine: connect to MySQL, classify risk, require explicit authorization for writes, execute through backend interfaces, and write structured audit events. It is MySQL-only today; PostgreSQL is planned but not enabled unless capabilities report it.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npm install -g dbgov-cli
15
+ # or
16
+ go install github.com/JiangHe12/dbgov-cli@latest
17
+ ```
18
+
19
+ Release binaries are available from GitHub Releases. npm installs download the matching platform binary.
20
+
21
+ ## Quickstart
22
+
23
+ ```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
29
+ ```
30
+
31
+ Use `-o json` for automation and AI agents.
32
+
33
+ ## Governance Model
34
+
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` |
41
+
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.
43
+
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.
45
+
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.
47
+
48
+ ## Usage
49
+
50
+ ```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
68
+ ```
69
+
70
+ ## Configuration and Contexts
71
+
72
72
  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:
73
73
 
74
74
  ```bash
75
- dbgov ctx export prod > prod.ctx.yaml
76
- dbgov ctx import -f prod.ctx.yaml --rename prod-copy -o json
77
- dbgov ctx migrate-credentials --to encrypted-file -o json
78
- dbgov ctx role set prod --target-operator alice --role writer -o json
75
+ dbgov-cli ctx export prod > prod.ctx.yaml
76
+ dbgov-cli ctx import -f prod.ctx.yaml --rename prod-copy -o json
77
+ dbgov-cli ctx migrate-credentials --to encrypted-file -o json
78
+ dbgov-cli ctx role set prod --target-operator alice --role writer -o json
79
79
  ```
80
80
 
81
81
  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.
82
82
 
83
83
  Set `DBGOV_OPERATOR` in CI to make audit and RBAC identity stable.
84
-
85
- ## Rollback and Snapshots
86
-
87
- Schema mutations capture a pre-change DDL snapshot before execution. `rollback --to <snapshot>` restores structure only; MySQL data dropped by table or column deletion is not recovered. dbgov prints this warning during rollback planning and execution.
88
-
89
- ## Build from Source
90
-
91
- ```bash
92
- go build ./...
93
- go test -count=1 ./...
94
- gofmt -l main.go cmd internal
95
- golangci-lint run --timeout=5m
96
- ```
97
-
98
- MySQL integration tests are opt-in with `DBGOV_TEST_MYSQL_DSN`.
99
-
100
- ## AI Skill
101
-
102
- ```bash
103
- dbgov install claude --skills
104
- dbgov install codex --skills
105
- ```
106
-
107
- ## Contributing, Security, License
108
-
109
- See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE).
84
+
85
+ ## Rollback and Snapshots
86
+
87
+ Schema mutations capture a pre-change DDL snapshot before execution. `rollback --to <snapshot>` restores structure only; MySQL data dropped by table or column deletion is not recovered. dbgov prints this warning during rollback planning and execution.
88
+
89
+ ## Build from Source
90
+
91
+ ```bash
92
+ go build ./...
93
+ go test -count=1 ./...
94
+ gofmt -l main.go cmd internal
95
+ golangci-lint run --timeout=5m
96
+ ```
97
+
98
+ MySQL integration tests are opt-in with `DBGOV_TEST_MYSQL_DSN`.
99
+
100
+ ## AI Skill
101
+
102
+ ```bash
103
+ dbgov-cli install claude --skills
104
+ dbgov-cli install codex --skills
105
+ ```
106
+
107
+ ## Contributing, Security, License
108
+
109
+ See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,34 +1,35 @@
1
- {
2
- "name": "dbgov-cli",
3
- "version": "0.1.2",
4
- "description": "Governed MySQL operations CLI for AI agents",
5
- "bin": {
6
- "dbgov": "bin/dbgov-cli.js"
7
- },
8
- "files": [
9
- "bin/",
10
- "scripts/install.js",
11
- "README.md",
12
- "LICENSE"
13
- ],
14
- "scripts": {
15
- "postinstall": "node scripts/install.js"
16
- },
17
- "keywords": [
18
- "database",
19
- "mysql",
20
- "cli",
21
- "ai",
22
- "governance"
23
- ],
24
- "author": "JiangHe12",
25
- "license": "MIT",
26
- "repository": {
27
- "type": "git",
28
- "url": "git+https://github.com/JiangHe12/dbgov-cli.git"
29
- },
30
- "homepage": "https://github.com/JiangHe12/dbgov-cli",
31
- "engines": {
32
- "node": ">=14"
33
- }
34
- }
1
+ {
2
+ "name": "dbgov-cli",
3
+ "version": "0.1.4",
4
+ "description": "Governed MySQL operations CLI for AI agents",
5
+ "bin": {
6
+ "dbgov": "bin/dbgov-cli.js",
7
+ "dbgov-cli": "bin/dbgov-cli.js"
8
+ },
9
+ "files": [
10
+ "bin/",
11
+ "scripts/install.js",
12
+ "README.md",
13
+ "LICENSE"
14
+ ],
15
+ "scripts": {
16
+ "postinstall": "node scripts/install.js"
17
+ },
18
+ "keywords": [
19
+ "database",
20
+ "mysql",
21
+ "cli",
22
+ "ai",
23
+ "governance"
24
+ ],
25
+ "author": "JiangHe12",
26
+ "license": "MIT",
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/JiangHe12/dbgov-cli.git"
30
+ },
31
+ "homepage": "https://github.com/JiangHe12/dbgov-cli",
32
+ "engines": {
33
+ "node": ">=14"
34
+ }
35
+ }