@carllee1983/dbcli 1.2.1 → 1.4.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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
+
+### Added
+
+- **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.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.
+
+## [1.3.0] - 2026-04-02
+
+### Added
+
+- **Skill Update Reminders**: Added automated reminders for updating AI agent skills (`SKILL.md`).
+  - New `dbcli upgrade` check that notifies if installed skills are outdated compared to the project's `assets/SKILL.md`.
+  - Background check in CLI that displays a one-line reminder to stderr after commands finish.
+  - Support for checking skills in `.claude/`, `.local/share/gemini/`, etc.
+
 ## [1.2.1] - 2026-03-31
 
 ### Fixed

package/README.md

@@ -472,9 +472,9 @@ dbcli skill --install cursor          # Install to Cursor IDE
 ```
 
 **Behavior:**
-- Dynamically generates SKILL.md from CLI introspection
-- Filters commands by permission level (Query-only hides write commands)
-- Supports multiple output modes: stdout, file, platform installation
+- Ships a canonical **`assets/SKILL.md`** in the package (single source of truth)
+- Prints that file to **stdout**, writes it with **`--output`**, or copies it to a **platform-specific path** with **`--install`**
+- Actual database access is still enforced by your `.dbcli` permission level and blacklist — the skill text describes the full CLI surface
 
 **Examples:**
 ```bash
@@ -669,7 +669,10 @@ dbcli upgrade --check           # Only check, do not upgrade
 ```
 
 **Options:** `--check` — check only, don't install
-**Background check:** dbcli silently checks npm registry once per 24 hours. If a newer version is found, a hint is shown after command output.
+
+**Background checks (stderr, skipped when `--quiet` or for `upgrade` / `skill`):**
+- **CLI version:** dbcli checks the npm registry (cached, about once per 24 hours). If a newer package exists, a one-line hint prints after normal command output.
+- **Installed skills:** If you used `dbcli skill --install <platform>`, dbcli compares each installed copy to the bundled `assets/SKILL.md`. When they differ, a short reminder lists which platforms to re-install (`dbcli skill --install <platform>`). Run `dbcli upgrade` to see the same skill status together with version info.
 
 #### `dbcli shell`
 
@@ -746,6 +749,7 @@ All commands support these global options:
 | Flag | Description |
 |------|-------------|
 | `--config <path>` | Path to .dbcli config file (default: `.dbcli`) |
+| `--use <connection>` | Use a named v2 connection for this invocation only (does not change the default) |
 | `-v, --verbose` | Increase verbosity (`-v` verbose, `-vv` debug) |
 | `-q, --quiet` | Suppress non-essential output |
 | `--no-color` | Disable colored output (respects `NO_COLOR` env var) |
@@ -928,7 +932,7 @@ A Query-only agent cannot write to any table, and also cannot read blacklisted t
 
 ## AI Integration Guide
 
-dbcli generates AI-consumable skill documentation and can be integrated into your favorite AI development tools.
+dbcli ships AI-consumable skill documentation (`assets/SKILL.md`) and can copy it into your favorite AI development tool directories.
 
 ### Quick Start
 
@@ -960,7 +964,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Restart Claude Code extension
 5. In Claude Code chat, ask: "Show me the database schema" or "Query active users"
 
-**Skill location:** `~/.claude/skills/SKILL.md`
+**Skill location:** `~/.claude/skills/dbcli/SKILL.md`
 
 ---
 
@@ -972,7 +976,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Start Gemini: `gemini start`
 5. In chat, request: "Query the users table" or "Show database tables"
 
-**Skill location:** `~/.local/share/gemini/skills/` (Linux) or platform equivalent
+**Skill location:** `~/.gemini/skills/dbcli/SKILL.md`
 
 ---
 
@@ -984,7 +988,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Install Copilot CLI: `npm install -g @github-next/github-copilot-cli`
 5. Use copilot preview: `copilot --help` and explore dbcli integration
 
-**Skill location:** Per Copilot configuration
+**Skill location:** `.github/skills/dbcli/SKILL.md` under the **current working directory** when you run `dbcli skill --install copilot` (typically your project root).
 
 ---
 
@@ -996,7 +1000,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Open Cursor editor
 5. Use Cursor's Composer: "Insert a new user" or "Export user data"
 
-**Skill location:** `~/.cursor/skills/`
+**Skill location:** `.cursor/rules/dbcli.mdc` under the **current working directory** when you run `dbcli skill --install cursor` (project-level Cursor rule).
 
 ---
 
@@ -1021,19 +1025,18 @@ dbcli skill --install claude
 # - Provide analysis
 ```
 
-### Skill Refresh
+### Updating the skill after upgrades
 
-dbcli dynamically generates skills based on your current configuration:
+The markdown installed by `dbcli skill` is the bundled **`assets/SKILL.md`**. It is **not** regenerated from your live config. When you **upgrade dbcli** or the bundled skill changes, re-copy it to each platform you use:
 
 ```bash
-# When permission level changes, skill updates automatically
-# Edit .dbcli/config.json and set "permission" to "admin" (or re-run dbcli init)
-dbcli skill  # Now shows delete and admin commands
-
-# Re-install to push changes to AI platform
 dbcli skill --install claude
+dbcli skill --install gemini
+# ... etc.
 ```
 
+If an installed copy is older than the bundled file, dbcli prints a **stderr reminder** after most commands (see **`dbcli upgrade`**). Changing **permission level** or **blacklist** in `.dbcli` affects what the CLI allows at runtime — keep project context (e.g. `dbcli status`, `dbcli blacklist list`) in mind for agents even though the skill text lists the full command set.
+
 ---
 
 ## Troubleshooting
@@ -1226,8 +1229,11 @@ chmod +x dist/cli.mjs
 ## Development
 
 ```bash
-bun test        # run test suite
-bun run build   # bundle CLI to dist/ (used before publish)
+bun test                  # full test suite (Bun test runner)
+bun run test:unit         # unit + core tests only
+bun run test:integration  # integration tests
+bun run test:docker       # integration tests with docker-compose.test.yml (MySQL + PostgreSQL)
+bun run build             # bundle CLI to dist/ (used before publish)
 ```
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for full setup, testing, and release process.

package/README.zh-TW.md

@@ -99,53 +99,64 @@ dbcli skill --install claude
 
 ## 多重連線支援 (v2)
 
-dbcli 支援在單一專案中管理多個具名的資料庫連線。這對於管理不同環境（開發、測試、正式）或多個資料庫非常有用。
+在**同一個專案目錄**裡，dbcli 可以保存多組**具名資料庫連線**（例如 `dev`、`staging`、`prod`），各自可有不同主機、資料庫、權限與選用的 `.env` 檔。適合同一 repo 對應多環境、或多個資料庫後端。
 
-### 初始化具名連線
+### v1 與 v2 設定檔
 
-若要建立具名連線，請在 `init` 時使用 `--conn-name` 選項。您也可以為該連線指定自訂的 `.env` 檔案。
+| 項目 | **v1（單一連線）** | **v2（多重連線）** |
+|------|-------------------|-------------------|
+| 設定 | 單一連線物件 | `config.json` 內 `version: 2`，含 `connections`（多個具名連線）與 `default`（預設使用哪一組） |
+| 典型檔案 | 舊版可能為單一 `.dbcli` 檔或目錄內單一連線 | `.dbcli/config.json`（目錄結構） |
+
+若你已有 **v1** 設定，之後執行 `dbcli init --conn-name ...` 追加連線時，工具會把既有連線**匯入為名稱 `default` 的連線**，再寫入 v2 結構，無須手動搬設定。
+
+### 預設連線 vs 單次指定
+
+- **`dbcli use <名稱>`** — 變更設定檔裡的**預設連線**（持久）。之後執行 `dbcli query`、`dbcli list` 等**未**加 `--use` 的指令，都會用這一組。
+- **`dbcli ... --use <名稱>`**（全域選項）— **只影響這一條指令**，不改預設。適合在仍以 `dev` 為預設時，偶爾查一下 `prod`。
+
+兩者都**需要 v2 設定**；若指令回報需要 v2，請先完成至少一次具名連線初始化（見下方）。
+
+### 初始化與追加連線
+
+第一次可直接 `dbcli init`（可互動輸入）；要**追加**另一環境時，在 `init` 加上 **`--conn-name`**，並可搭配 **`--env-file`** 讓該連線讀獨立的環境檔：
 
 ```bash
 # 使用 .env.staging 建立名為 staging 的連線
 dbcli init --conn-name staging --env-file .env.staging
 
-# 建立名為 prod 的正式環境連線，並使用環境變數引用
+# 建立名為 prod 的正式環境連線，並使用環境變數引用（憑證不寫死進 repo）
 dbcli init --conn-name prod --env-file .env.production --use-env-refs
 ```
 
-### 管理連線
+每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。同一專案下的 **schema 快取、黑名單** 等仍共用同一個 `.dbcli` 目錄；切換連線只改「連到哪一台資料庫」，不複製整份專案設定目錄。
 
-使用 `dbcli use` 指令切換連線或列出所有連線。
+### 管理連線（`use` / 移除 / 更名）
 
-```bash
-# 列出所有連線（* 標記目前的預設值）
-dbcli use --list
+使用 **`dbcli use`** 切換預設或列出連線（列表中 **`*`** 表示目前的預設連線）：
 
-# 將預設連線切換至 'staging'
-dbcli use staging
-
-# 顯示目前的預設連線
-dbcli use
+```bash
+dbcli use --list          # 列出全部；* = 預設
 
-# 移除連線
-dbcli init --remove staging
+dbcli use staging         # 將預設連線改為 staging（寫入設定）
+dbcli use                 # 顯示目前預設名稱並列出連線
 
-# 重新命名連線
-dbcli init --rename staging:production
+dbcli init --remove staging              # 從設定移除某具名連線
+dbcli init --rename staging:production    # 更名（格式：舊名:新名）
 ```
 
-### 臨時使用特定連線
+### 臨時指定連線（不改預設）
 
-您可以使用 `--use <name>` 全域旗標，針對特定連線執行任一指令，而無需變更預設設定。
+任何子指令皆可加全域 **`--use <名稱>`**，僅本次使用該連線：
 
 ```bash
-# 針對正式資料庫執行一次查詢
 dbcli query "SELECT count(*) FROM users" --use prod
-
-# 檢查測試環境資料表的健康狀態
 dbcli check users --use staging
+dbcli list --use prod
 ```
 
+若同時需要自訂設定路徑，可與 **`--config <路徑>`** 併用（仍指向含 `config.json` 的 `.dbcli` 目錄）。
+
 ---
 
 
@@ -176,6 +187,7 @@ dbcli init [OPTIONS]
 - `--env-file <path>` — 從指定的 `.env` 檔案載入此連線的憑證
 - `--remove <name>` — 從設定中移除具名連線
 - `--rename <old:new>` — 重新命名現有連線（格式：`舊名:新名`）
+
 **行為：**
 - 若存在 `.env` 會讀取（自動帶入 DATABASE_URL、DB_* 等變數）
 - 缺少的欄位會互動提示（主機、埠、使用者、密碼、資料庫名、權限等級）
@@ -477,9 +489,9 @@ dbcli skill --install cursor          # 安裝至 Cursor IDE
 ```
 
 **行為：**
-- 依 CLI 內省動態產生 SKILL.md
-- 依權限等級過濾指令（Query-only 會隱藏寫入類指令）
-- 支援 stdout、檔案、各平台安裝等輸出方式
+- 套件內建唯一的 **`assets/SKILL.md`**（單一來源）
+- 可輸出至 **stdout**、以 **`--output`** 寫入檔案，或以 **`--install`** 複製到**各平台預設路徑**
+- 實際能否存取資料庫仍由 `.dbcli` 的**權限等級**與**黑名單**決定；skill 文字描述的是完整 CLI 能力
 
 **範例：**
 ```bash
@@ -666,8 +678,11 @@ dbcli upgrade                   # 有新版則升級
 dbcli upgrade --check           # 僅檢查，不安裝
 ```
 
-**選項：** `--check` — 只檢查，不安裝  
-**背景檢查：** dbcli 每 24 小時會靜默查詢 npm registry 一次；若有新版，會在指令輸出結束後顯示提示。
+**選項：** `--check` — 只檢查，不安裝
+
+**背景檢查（stderr；使用 `--quiet` 或執行 `upgrade` / `skill` 時略過）：**
+- **CLI 版本：** dbcli 會查詢 npm registry（有快取，約每 24 小時一次）。若有新版，一般指令結束後會印一行提示。
+- **已安裝的 skill：** 若曾執行 `dbcli skill --install <platform>`，dbcli 會比對各平台安裝檔與套件內的 `assets/SKILL.md`；若不一致，會列出需重新安裝的平台（`dbcli skill --install <platform>`）。執行 `dbcli upgrade` 時也會一併顯示 skill 狀態與版本資訊。
 
 #### `dbcli shell`
 
@@ -744,6 +759,7 @@ dbcli migrate drop-enum status --execute --force
 | 旗標 | 說明 |
 |------|------|
 | `--config <path>` | `.dbcli` 設定檔路徑（預設：`.dbcli`） |
+| `--use <connection>` | 僅本次指令使用具名的 v2 連線（不變更預設連線） |
 | `-v, --verbose` | 提高詳細度（`-v` 詳細、`-vv` 除錯） |
 | `-q, --quiet` | 抑制非必要輸出 |
 | `--no-color` | 關閉彩色輸出（亦遵守 `NO_COLOR` 環境變數） |
@@ -922,7 +938,7 @@ Query-only 代理無法寫入任何表，也無法讀取黑名單表或欄位
 
 ## AI 整合指南
 
-dbcli 可產生供 AI 使用的 skill 文件，並可整合至常見 AI 開發工具。
+dbcli 內建可供 AI 使用的 skill 文件（`assets/SKILL.md`），並可複製到常見 AI 開發工具的目錄。
 
 ### 快速開始
 
@@ -954,7 +970,7 @@ dbcli skill --install cursor
 4. 重新啟動 Claude Code 擴充
 5. 在對話中詢問：「顯示資料庫 schema」或「查詢作用中使用者」
 
-**Skill 路徑：** `~/.claude/skills/SKILL.md`
+**Skill 路徑：** `~/.claude/skills/dbcli/SKILL.md`
 
 ---
 
@@ -966,7 +982,7 @@ dbcli skill --install cursor
 4. 啟動 Gemini：`gemini start`
 5. 在對話中請求：「查詢 users 表」或「列出資料庫資料表」
 
-**Skill 路徑：** `~/.local/share/gemini/skills/`（Linux）或各平台對應路徑
+**Skill 路徑：** `~/.gemini/skills/dbcli/SKILL.md`
 
 ---
 
@@ -978,7 +994,7 @@ dbcli skill --install cursor
 4. 安裝 Copilot CLI：`npm install -g @github-next/github-copilot-cli`
 5. 使用 `copilot --help` 並探索與 dbcli 的整合
 
-**Skill 路徑：** 依 Copilot 設定而定
+**Skill 路徑：** 執行 `dbcli skill --install copilot` 時，寫入**目前工作目錄**下的 `.github/skills/dbcli/SKILL.md`（通常為專案根目錄）。
 
 ---
 
@@ -990,7 +1006,7 @@ dbcli skill --install cursor
 4. 開啟 Cursor
 5. 在 Composer 中：「新增一筆使用者」或「匯出使用者資料」
 
-**Skill 路徑：** `~/.cursor/skills/`
+**Skill 路徑：** 執行 `dbcli skill --install cursor` 時，寫入**目前工作目錄**下的 `.cursor/rules/dbcli.mdc`（專案層級 Cursor 規則）。
 
 ---
 
@@ -1015,18 +1031,18 @@ dbcli skill --install claude
 # - 提供分析
 ```
 
-### 重新整理 Skill
+### 升級後更新 skill
 
-權限或設定變更後，可重新產生 skill：
+`dbcli skill` 安裝的是套件內建的 **`assets/SKILL.md`**，**不會**依你目前的設定即時重新產生。當你**升級 dbcli** 或內建 skill 內容變更時，請對各平台重新安裝：
 
 ```bash
-# 例如編輯 .dbcli/config.json，將 "permission" 設為 "admin"（或重新執行 dbcli init）
-dbcli skill  # 會顯示 delete 與 migrate 等指令
-
-# 再安裝一次以更新 AI 平台
 dbcli skill --install claude
+dbcli skill --install gemini
+# …依需求
 ```
 
+若本機安裝檔與套件內檔案不一致，多數指令結束後會在 **stderr** 提示（見 **`dbcli upgrade`**）。**權限**或**黑名單**變更會影響 CLI 實際允許的操作 — 建議搭配 `dbcli status`、`dbcli blacklist list` 等讓代理掌握專案現況；skill 文字仍可能列出完整指令集。
+
 ---
 
 ## 故障排除
@@ -1213,8 +1229,11 @@ chmod +x dist/cli.mjs
 ## 開發
 
 ```bash
-bun test        # 執行測試
-bun run build   # 建置 CLI 至 dist/（發布前使用）
+bun test                  # 完整測試（Bun test runner）
+bun run test:unit         # 僅單元與 core 測試
+bun run test:integration  # 整合測試
+bun run test:docker       # 搭配 docker-compose.test.yml（MySQL + PostgreSQL）
+bun run build             # 建置 CLI 至 dist/（發布前使用）
 ```
 
 完整環境、測試與發布流程見 [CONTRIBUTING.md](./CONTRIBUTING.md)。

package/assets/SKILL.md

@@ -75,17 +75,23 @@ dbcli list --format json
 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.