@carllee1983/dbcli 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-04-21
+
+### Added
+
+- **Layered Schema Cache (Wave 1)**: Integrated file-based persistence for database schemas.
+  - New `SchemaWriter` for saving schema snapshots to `.dbcli/schemas/`.
+  - Layered schema loading (Hot/Cold) integrated into `configModule`.
+  - Per-connection isolation: Each connection now has its own schema directory (`.dbcli/schemas/<connection>/`).
+- **Improved Migration UX**: Added proactive hints during schema migration to ensure data consistency.
+- **Documentation Update**: Added per-connection schema isolation details to `SKILL.md` for AI agents.
+  - Clarified schema storage layout in `.dbcli/schemas/`.
+  - Added usage examples for `--use <connection>` with schema commands.
+
+## [1.4.1] - 2026-04-21
+
 ## [1.3.0] - 2026-04-02
 
 ### Added

package/README.dev.md

@@ -17,6 +17,14 @@ Before running `npm publish`:
    bun test --run unit/
    ```
 
+   For live database integration tests, use an explicit config path if needed:
+   ```bash
+   LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts
+   ```
+
+   If no live config is available, `tests/integration/live-db.test.ts` skips
+   instead of falling back to the default PostgreSQL configuration.
+
 3. **Update version in package.json:**
    ```bash
    npm version minor  # Updates package.json version + creates git tag
@@ -101,6 +109,9 @@ Then publish a patch fix.
 - **Cross-platform support:** Shebang `#!/usr/bin/env bun` works on all platforms
   - macOS/Linux: Direct shebang execution
   - Windows: npm creates .cmd wrapper automatically (no manual creation needed)
+- **Live integration tests:** `tests/integration/live-db.test.ts` reads `.dbcli/config.json`
+  by default or `LIVE_DB_CONFIG_PATH` when you need to point at another config
+  directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
 
 ### Troubleshooting
 

package/README.md

@@ -1236,6 +1236,17 @@ bun run test:docker       # integration tests with docker-compose.test.yml (MySQ
 bun run build             # bundle CLI to dist/ (used before publish)
 ```
 
+Live database integration tests use `.dbcli/config.json` by default. If your live
+config lives elsewhere, set `LIVE_DB_CONFIG_PATH=/path/to/.dbcli` before running:
+
+```bash
+LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts
+```
+
+If no live config is available, `tests/integration/live-db.test.ts` skips instead
+of falling back to the default PostgreSQL configuration. Set
+`SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
+
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for full setup, testing, and release process.
 
 ---

package/README.zh-TW.md

@@ -1236,6 +1236,17 @@ bun run test:docker       # 搭配 docker-compose.test.yml（MySQL + PostgreSQL
 bun run build             # 建置 CLI 至 dist/（發布前使用）
 ```
 
+live DB 整合測試預設讀取 `.dbcli/config.json`。如果你的 live 設定放在其他位置，
+可先指定 `LIVE_DB_CONFIG_PATH=/path/to/.dbcli` 再執行：
+
+```bash
+LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts
+```
+
+如果沒有可用的 live config，`tests/integration/live-db.test.ts` 會直接 skip，
+不再回退到預設 PostgreSQL 設定。若要跳過所有整合測試，可設定
+`SKIP_INTEGRATION_TESTS=true`。
+
 完整環境、測試與發布流程見 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 ---

package/assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dbcli
-description: Database CLI for AI agents with permission-based access control. Use to query, inspect schemas, insert/update/delete data, export results, and manage sensitive data blacklists. Supports MySQL, PostgreSQL, MariaDB with multiple named connections per project and custom env files. Trigger when working with databases, running SQL, exploring table structures, switching between database environments, or protecting sensitive columns/tables from AI access.
+description: Database CLI for AI agents with permission-based access control. Use to query, inspect schemas, insert/update/delete data, export results, and manage sensitive data blacklists. Supports MySQL, PostgreSQL, MariaDB, and MongoDB with multiple named connections per project and custom env files. Trigger when working with databases, running SQL or MongoDB JSON queries, exploring table/collection structures, switching between database environments, or protecting sensitive columns/tables from AI access.
 ---
 
 # dbcli
@@ -27,6 +27,11 @@ dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
 dbcli init --no-interactive --force                     # Non-interactive mode
 
+# MongoDB
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
+dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
+dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
 dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-test
@@ -36,6 +41,8 @@ dbcli init --rename staging:production                   # Rename a connection
 
 **Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
+**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+
 **Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
@@ -61,7 +68,7 @@ dbcli list --use prod
 
 ### list
 
-List all tables.
+List all tables (SQL) or collections (MongoDB).
 
 ```bash
 dbcli list
@@ -70,35 +77,56 @@ dbcli list --format json
 
 **Permission:** query-only+
 
+> **MongoDB:** Lists collections with estimated document count instead of tables.
+
 ### schema
 
 Display table schema or scan entire database.
 
 ```bash
-dbcli schema                        # Scan all tables, save to .dbcli
+dbcli schema                        # Scan all tables, save to .dbcli/schemas/
 dbcli schema users                  # Show single table schema
 dbcli schema users --format json
 dbcli schema --refresh              # Detect and apply schema changes
 dbcli schema --reset                # Clear all schema data and re-fetch
 dbcli schema --reset --force        # Skip confirmation
+
+# Per-connection schema isolation (v2 multi-connection config)
+dbcli schema --use staging          # Scan staging DB; saves to .dbcli/schemas/staging/
+dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod/
 ```
 
-**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`
+**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`, `--use <connection>`
 **Permission:** query-only+
 
+**Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
+
 ### query
 
-Execute SQL query.
+Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
 
 ```bash
+# SQL databases
 dbcli query "SELECT * FROM users LIMIT 10"
 dbcli query "SELECT id, email FROM users" --format json
 dbcli query "SELECT * FROM logs" --no-limit
+
+# MongoDB: JSON filter (find)
+dbcli query '{"status": "active"}' --collection users
+dbcli query '{"age": {"$gt": 18}}' --collection users --format json
+
+# MongoDB: aggregation pipeline
+dbcli query '[{"$match": {"status": "active"}}, {"$group": {"_id": "$role", "count": {"$sum": 1}}}]' --collection users
 ```
 
-**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`
+**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB only)
 **Permission:** query-only+
 
+> **MongoDB notes:**
+> - SQL syntax is rejected — use JSON object (filter) or JSON array (pipeline)
+> - `--collection <name>` is required
+> - Auto-limit does not apply; use `$limit` in your pipeline if needed
+
 ### insert
 
 Insert data into a table.
@@ -319,6 +347,38 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+## MongoDB Support
+
+MongoDB connections use a JSON-based query model instead of SQL.
+
+**Supported commands:** `init`, `list`, `query`, `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`
+
+**Not supported (exit with error):** `schema`, `insert`, `update`, `delete`, `export`, `diff`, `migrate`, `check`
+
+### MongoDB-specific workflow
+
+```bash
+# 1. Initialize (URI or individual params)
+dbcli init --system mongodb --uri "mongodb://localhost:27017/mydb"
+
+# 2. List collections
+dbcli list --format json
+
+# 3. Query with JSON filter (find) or pipeline (aggregate)
+dbcli query '{}' --collection orders --format json          # All documents
+dbcli query '{"status": "paid"}' --collection orders        # Filter
+dbcli query '[{"$match": {"status":"paid"}}, {"$count":"total"}]' --collection orders  # Pipeline
+```
+
+### Query syntax
+
+| Intent | Syntax |
+|--------|--------|
+| All documents | `'{}'` |
+| Field filter | `'{"field": "value"}'` |
+| Comparison | `'{"age": {"$gt": 18}}'` |
+| Aggregation | `'[{"$match": {...}}, {"$group": {...}}]'` |
+
 ## Permission Levels
 
 | Level | Allowed Operations |