@carllee1983/dbcli 0.1.0 → 0.3.0-beta

package/CHANGELOG.md

@@ -5,11 +5,48 @@ 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.0.0] - 2026-03-26
+## [0.2.0-beta] - 2026-03-26
+
+### Data Access Control — Blacklist System
+
+Added table and column-level blacklisting to protect sensitive data from AI agent access.
+
+### Added
+
+- **`dbcli blacklist` command suite:** Manage blacklist rules via CLI
+  - `blacklist list` — display current blacklist configuration
+  - `blacklist table add/remove <table>` — manage table-level blacklist
+  - `blacklist column add/remove <table>.<column>` — manage column-level blacklist
+- **Table-level blacklisting:** Reject all operations (query, insert, update, delete) on blacklisted tables
+- **Column-level blacklisting:** Automatically omit blacklisted columns from SELECT results
+- **Security notifications:** Footer in table/CSV/JSON output when columns are filtered (e.g., "Security: 2 column(s) were omitted based on your blacklist")
+- **Context-aware override:** `DBCLI_OVERRIDE_BLACKLIST=true` environment variable for temporary bypass with warning
+- **i18n support:** Blacklist messages in English and Traditional Chinese
+- **Performance:** < 1ms overhead per query (O(1) Set/Map lookups)
+- **103 new tests:** 83 core + 12 CLI wiring + 8 formatter security tests
+- **`dbcli schema --reset`:** Clear all existing schema data and re-fetch from database — solves stale schema after switching DB connections
+
+### Configuration
+
+Blacklist rules stored in `.dbcli`:
+```json
+{
+  "blacklist": {
+    "tables": ["audit_logs", "secrets_vault"],
+    "columns": {
+      "users": ["password_hash", "ssn"]
+    }
+  }
+}
+```
+
+---
+
+## [0.1.0-beta] - 2026-03-26
 
 ### Initial Release - AI-Ready Database CLI
 
-dbcli v1.0.0 is a complete, production-ready CLI tool enabling AI agents and developers to safely interact with PostgreSQL, MySQL, and MariaDB databases through a permission-controlled interface.
+dbcli v0.1.0-beta is a complete, production-ready CLI tool enabling AI agents and developers to safely interact with PostgreSQL, MySQL, and MariaDB databases through a permission-controlled interface.
 
 **Key Achievement:** Single command-line tool bridging AI agents (Claude Code, Gemini, Copilot, Cursor) to database access without requiring multiple MPC integrations.
 
@@ -176,9 +213,8 @@ dbcli v1.0.0 is a complete, production-ready CLI tool enabling AI agents and dev
 
 ## Known Limitations (V1)
 
-- **Single database per project:** Multi-connection support deferred to V1.1
-- **Coarse-grained permissions:** Per-table/column access control not in scope
-- **No audit logging:** WHO/WHAT/WHEN tracking deferred to V1.1
+- **Single database per project:** Multi-connection support deferred to a future version
+- **No audit logging:** WHO/WHAT/WHEN tracking deferred to a future version
 - **Read-only schema:** No schema modification commands (ALTER TABLE, etc.) in V1
 - **CLI-only:** No visual schema designer, REPL, or interactive shell in V1
 

package/README.md

@@ -1,8 +1,33 @@
 # dbcli — Database CLI for AI Agents
 
+**Languages:** [English](./README.md) | [繁體中文](./README.zh-TW.md)
+
 A unified database CLI tool that enables AI agents (Claude Code, Gemini, Copilot, Cursor) to safely query, discover, and operate on databases.
 
-**Core Value:** AI agents can safely and intelligently access project databases through a single, permission-controlled CLI tool.
+**Core Value:** AI agents can safely and intelligently access project databases through a single, permission-controlled CLI tool with sensitive data protection.
+
+## Internationalization (i18n)
+
+dbcli supports multiple languages via the `DBCLI_LANG` environment variable:
+
+```bash
+# English (default)
+dbcli init
+
+# Traditional Chinese
+DBCLI_LANG=zh-TW dbcli init
+
+# Or set in .env
+export DBCLI_LANG=zh-TW
+dbcli init
+```
+
+**Supported languages:**
+- `en` — English (default)
+- `zh-TW` — Traditional Chinese (Taiwan)
+
+All messages, help text, error messages, and command output respond to the language setting automatically.
+
 
 ## Quick Start
 
@@ -124,8 +149,9 @@ dbcli schema users           # Show structure of 'users' table
 
 **Options:**
 - `--format json` — Output as JSON
-- `--refresh` — Detect and update schema changes (requires --force for approval)
-- `--force` — Skip confirmation for schema refresh/overwrite
+- `--refresh` — Detect and update schema changes incrementally (requires --force for approval)
+- `--reset` — Clear all existing schema data and re-fetch from database (useful after switching DB connections)
+- `--force` — Skip confirmation for schema refresh/overwrite/reset
 
 **Examples:**
 ```bash
@@ -135,12 +161,12 @@ dbcli schema users
 # JSON output with full metadata
 dbcli schema users --format json
 
-# Update schema with new tables
-dbcli schema --refresh
-
-# Auto-approve schema refresh
+# Update schema with new tables (incremental)
 dbcli schema --refresh --force
 
+# Clear and re-fetch all schema (after switching DB)
+dbcli schema --reset --force
+
 # Scan entire database
 dbcli schema
 ```
@@ -352,9 +378,63 @@ dbcli skill --install cursor
 
 ---
 
+#### `dbcli blacklist`
+
+Manage the data access blacklist to block AI agents from accessing sensitive tables or columns.
+
+**Usage:**
+```bash
+dbcli blacklist list
+dbcli blacklist table add <table>
+dbcli blacklist table remove <table>
+dbcli blacklist column add <table>.<column>
+dbcli blacklist column remove <table>.<column>
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `dbcli blacklist list` | Show current blacklist (tables and columns) |
+| `dbcli blacklist table add <table>` | Add table to blacklist (blocks all operations) |
+| `dbcli blacklist table remove <table>` | Remove table from blacklist |
+| `dbcli blacklist column add <table>.<column>` | Add column to blacklist (omitted from SELECT results) |
+| `dbcli blacklist column remove <table>.<column>` | Remove column from blacklist |
+
+**Behavior:**
+- Table blacklist blocks all operations on that table (query, insert, update, delete)
+- Column blacklist silently omits columns from SELECT results and shows a security notification
+- Blacklist rules are stored in `.dbcli` and apply to all permission levels
+- Override for admin use via `DBCLI_OVERRIDE_BLACKLIST=true` environment variable
+
+**Examples:**
+```bash
+# View current blacklist
+dbcli blacklist list
+
+# Block all access to sensitive tables
+dbcli blacklist table add audit_logs
+dbcli blacklist table add secrets_vault
+
+# Hide sensitive columns from query results
+dbcli blacklist column add users.password_hash
+dbcli blacklist column add users.ssn
+
+# Remove a table from blacklist
+dbcli blacklist table remove audit_logs
+
+# Remove a column from blacklist
+dbcli blacklist column remove users.ssn
+
+# Override blacklist (admin use only)
+DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
+```
+
+---
+
 ## Permission Model
 
-dbcli implements a coarse-grained permission system with three levels. Permission level is set during `dbcli init` and stored in `.dbcli` config file.
+dbcli implements a coarse-grained permission system with three levels. Permission level is set during `dbcli init` and stored in `.dbcli` config file. The blacklist system works alongside permissions to provide fine-grained protection for sensitive tables and columns (see [Data Access Control](#data-access-control)).
 
 ### Permission Levels
 
@@ -417,6 +497,79 @@ dbcli delete users --where "id=1" --force  # Only Admin can delete
 
 ---
 
+## Data Access Control
+
+dbcli provides a blacklist system that works alongside the permission model to prevent AI agents from accessing sensitive tables or columns, regardless of their permission level.
+
+### Table-Level Blacklist
+
+Blocking a table prevents all operations on it — queries, inserts, updates, and deletes are all refused with a clear error message.
+
+```bash
+# Block a table
+dbcli blacklist table add secrets_vault
+
+# Attempting access is blocked at all permission levels
+dbcli query "SELECT * FROM secrets_vault"
+# ERROR: Table 'secrets_vault' is blacklisted
+```
+
+### Column-Level Blacklist
+
+Blacklisted columns are silently omitted from SELECT results. A security notification is shown in the output so the agent is aware that the result set has been filtered.
+
+```bash
+# Blacklist sensitive columns
+dbcli blacklist column add users.password_hash
+dbcli blacklist column add users.ssn
+
+# Query returns all other columns; notification shown
+dbcli query "SELECT * FROM users"
+# [Security] Columns omitted by blacklist: password_hash, ssn
+```
+
+### Security Notifications
+
+Whenever a blacklist rule filters query output, dbcli appends a notification line to the result. This ensures AI agents do not silently operate on incomplete data without awareness.
+
+### Override via Environment Variable
+
+Administrators can bypass the blacklist for emergency or maintenance operations using the `DBCLI_OVERRIDE_BLACKLIST=true` environment variable:
+
+```bash
+DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
+```
+
+This override is logged and should only be used by administrators when necessary.
+
+### Blacklist Configuration
+
+Blacklist rules are stored in the `.dbcli` config file and can also be set manually:
+
+```json
+{
+  "blacklist": {
+    "tables": ["audit_logs", "secrets_vault"],
+    "columns": {
+      "users": ["password_hash", "ssn"]
+    }
+  }
+}
+```
+
+### Blacklist vs. Permissions
+
+The blacklist and permission model are complementary layers of access control:
+
+| Layer | Controls | Applies To |
+|-------|----------|------------|
+| **Permission Model** | Operation type (read/write/delete) | All tables |
+| **Blacklist** | Specific tables and columns | Targeted sensitive data |
+
+A Query-only agent cannot write to any table, and also cannot read blacklisted tables or columns — both restrictions apply simultaneously.
+
+---
+
 ## AI Integration Guide
 
 dbcli generates AI-consumable skill documentation and can be integrated into your favorite AI development tools.