@carllee1983/dbcli 1.4.1 → 1.5.2

package/CHANGELOG.md

@@ -5,15 +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.4.1] - 2026-04-21
+## [1.5.2] - 2026-04-22
 
-### Added
+### Fixed
 
-- **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.
+- **Doctor diagnostics for MongoDB SRV**: `dbcli doctor` now reports whether the current execution environment can resolve `mongodb+srv://` connections directly or only through the DNS-over-HTTPS fallback used by the MongoDB adapter.
+- **Documentation**: Clarified the new MongoDB SRV environment diagnostic in README, README.zh-TW, and `assets/SKILL.md`.
 
-## [1.4.0] - 2026-04-21
+## [1.5.1] - 2026-04-22
+
+### Fixed
+
+- **MongoDB SRV Connections**: `mongodb+srv://` URIs are now expanded and connected through the MongoDB adapter, and MongoDB operations consistently use the configured database.
+- **MongoDB Documentation**: Clarified SRV URI support and configured-database behavior in README, README.zh-TW, and `assets/SKILL.md`.
+
+## [1.5.0] - 2026-04-21
 
 ### Added
 
@@ -22,6 +28,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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
 

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

@@ -89,6 +89,23 @@ dbcli query "SELECT * FROM users"
 dbcli skill --install claude
 ```
 
+### MongoDB Atlas / SRV Connections
+
+MongoDB connections are supported via both standard `mongodb://` URIs and Atlas-style `mongodb+srv://` URIs.
+
+```bash
+# Atlas / SRV connection
+dbcli init --system mongodb --conn-name atlas --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
+
+# List collections in the configured MongoDB database
+dbcli list --use atlas
+
+# Query a collection with JSON filter or pipeline
+dbcli query '{"status":"active"}' --collection users --use atlas
+```
+
+For MongoDB, `list` and `query` operate on the database configured for the connection, and `query` requires `--collection <name>`.
+
 ---
 
 ## Multi-connection Support (v2)
@@ -637,6 +654,7 @@ dbcli doctor --format json      # JSON output for AI agents
 - **Environment:** Bun version compatibility, dbcli version (compares with npm registry)
 - **Configuration:** Config file exists/valid, permission level, blacklist completeness
 - **Connection & Data:** Database connectivity, schema cache freshness (> 7 days warning), large table warnings (> 1M rows)
+- **MongoDB SRV diagnostics:** For `mongodb+srv://` connections, `doctor` reports whether the current execution environment can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by `dbcli`
 
 **Options:** `--format <text|json>`
 **Exit code:** 0 = all pass or warnings only, 1 = errors found
@@ -1236,6 +1254,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

@@ -95,6 +95,23 @@ dbcli migrate create posts --column "id:int:pk" "title:varchar(100)"
 dbcli skill --install claude
 ```
 
+### MongoDB Atlas / SRV 連線
+
+MongoDB 連線同時支援標準 `mongodb://` URI 與 Atlas 常用的 `mongodb+srv://` URI。
+
+```bash
+# Atlas / SRV 連線
+dbcli init --system mongodb --conn-name atlas --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
+
+# 列出該 MongoDB 連線中的集合
+dbcli list --use atlas
+
+# 以 JSON filter 或 pipeline 查詢某個集合
+dbcli query '{"status":"active"}' --collection users --use atlas
+```
+
+對 MongoDB 而言，`list` 與 `query` 會使用該連線設定中的資料庫；`query` 也必須指定 `--collection <名稱>`。
+
 ---
 
 ## 多重連線支援 (v2)
@@ -647,6 +664,7 @@ dbcli doctor --format json      # JSON 輸出（供 AI 代理）
 - **環境：** Bun 版本相容性、dbcli 版本（與 npm registry 比對）
 - **設定：** 設定檔是否存在／有效、權限等級、黑名單完整性
 - **連線與資料：** 資料庫連線、schema 快取新鮮度（超過 7 天警告）、大表警告（超過 100 萬列）
+- **MongoDB SRV 偵測：** 對 `mongodb+srv://` 連線，`doctor` 會回報目前執行環境能否直接解析 SRV 記錄，或只能依賴 dbcli 內建的 DNS-over-HTTPS fallback
 
 **選項：** `--format <text|json>`  
 **結束代碼：** 0 = 全部通過或僅警告，1 = 有錯誤
@@ -1236,6 +1254,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,6 +77,8 @@ 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.
@@ -94,17 +103,30 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 ### 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.
@@ -226,6 +248,8 @@ dbcli doctor --format json      # JSON output for AI agents
 - Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
 - Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
 
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
 **Exit code:** 0 if all pass or warnings only, 1 if any error
 **Options:** `--format <text|json>`
 
@@ -325,6 +349,40 @@ 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.
+
+Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+
+**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+srv://user:pass@cluster.example.mongodb.net/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 |