@carllee1983/dbcli 0.5.2-beta → 1.2.0

package/README.md

@@ -37,6 +37,7 @@ All messages, help text, error messages, and command output respond to the langu
 
 ```bash
 npm install -g @carllee1983/dbcli
+# or: bun install -g @carllee1983/dbcli
 ```
 
 #### Zero-Install (No Installation Needed)
@@ -44,6 +45,7 @@ npm install -g @carllee1983/dbcli
 ```bash
 npx @carllee1983/dbcli init
 npx @carllee1983/dbcli query "SELECT * FROM users"
+# or with Bun: bunx @carllee1983/dbcli init
 ```
 
 #### Update
@@ -59,12 +61,15 @@ npm update -g @carllee1983/dbcli
 #### Development Installation
 
 ```bash
-git clone <repository>
+git clone https://github.com/CarlLee1983/dbcli.git
 cd dbcli
 bun install
-bun run dev -- --help
+bun run src/cli.ts -- --help
+# or: bun run dev -- --help
 ```
 
+When `dbcli` is not on your `PATH`, use `bun run src/cli.ts <subcommand> ...` (same as `bun run dev -- <subcommand> ...`).
+
 ### First Steps
 
 ```bash
@@ -86,9 +91,57 @@ dbcli skill --install claude
 
 ---
 
-## API Reference
+## Multi-connection Support (v2)
+
+dbcli supports multiple named database connections within a single project. This is useful for managing different environments (development, staging, production) or multiple databases.
+
+### Initializing Named Connections
+
+To create a named connection, use the `--conn-name` option during `init`. You can also specify a custom `.env` file for that connection.
+
+```bash
+# Add a staging connection using .env.staging
+dbcli init --conn-name staging --env-file .env.staging
+
+# Add a production connection with environment variable references
+dbcli init --conn-name prod --env-file .env.production --use-env-refs
+```
+
+### Managing Connections
+
+Use the `dbcli use` command to switch between connections or list them.
+
+```bash
+# List all connections (* marks the current default)
+dbcli use --list
+
+# Switch the default connection to 'staging'
+dbcli use staging
+
+# Show the current default connection
+dbcli use
+
+# Remove a connection
+dbcli init --remove staging
+
+# Rename a connection
+dbcli init --rename staging:production
+```
+
+### Using a Specific Connection Temporarily
+
+You can use the `--use <name>` global flag to execute any command against a specific connection without changing the default.
+
+```bash
+# Query the production database once
+dbcli query "SELECT count(*) FROM users" --use prod
+
+# Check staging table health
+dbcli check users --use staging
+```
+
+---
 
-### Commands
 
 #### `dbcli init`
 
@@ -99,7 +152,7 @@ Initialize a new dbcli project with database connection configuration.
 dbcli init [OPTIONS]
 ```
 
-**Options:**
+**Options (Basic):**
 - `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`
 - `--host <host>` — Database host
 - `--port <port>` — Database port
@@ -108,15 +161,16 @@ dbcli init [OPTIONS]
 - `--name <db>` — Database name
 - `--permission <level>` — Permission level: `query-only`, `read-write`, `data-admin`, `admin`
 - `--use-env-refs` — Store environment variable references instead of actual values in config
-- `--env-host <var>` — Env var name for host (with `--use-env-refs`)
-- `--env-port <var>` — Env var name for port (with `--use-env-refs`)
-- `--env-user <var>` — Env var name for user (with `--use-env-refs`)
-- `--env-password <var>` — Env var name for password (with `--use-env-refs`)
-- `--env-database <var>` — Env var name for database (with `--use-env-refs`)
 - `--skip-test` — Skip connection test
 - `--no-interactive` — Non-interactive mode (requires all options)
 - `--force` — Overwrite existing config without confirmation
 
+**Options (Multi-connection v2):**
+- `--conn-name <name>` — Create a named connection (e.g., `staging`, `prod`)
+- `--env-file <path>` — Load credentials from a specific `.env` file for this connection
+- `--remove <name>` — Remove a named connection from the config
+- `--rename <old:new>` — Rename an existing connection (format: `old:new`)
+
 **Behavior:**
 - Reads `.env` file if present (auto-fills DATABASE_URL, DB_* variables)
 - Prompts for missing values (host, port, user, password, database name, permission level)
@@ -128,15 +182,9 @@ dbcli init [OPTIONS]
 # Interactive initialization
 dbcli init
 
-# With environment variables pre-set
-export DATABASE_URL="postgresql://user:pass@localhost/mydb"
-dbcli init
-
-# Specify permission level
-echo "PERMISSION_LEVEL=admin" >> .env && dbcli init
-
-# Store env var references instead of values (interactive)
-dbcli init --use-env-refs
+# Multi-connection setup
+dbcli init --conn-name staging --env-file .env.staging
+dbcli init --conn-name prod --env-file .env.production --use-env-refs
 
 # Store env var references (non-interactive)
 dbcli init --use-env-refs --system mysql \
@@ -146,6 +194,34 @@ dbcli init --use-env-refs --system mysql \
   --no-interactive
 ```
 
+---
+
+#### `dbcli use` (Requires v2 config)
+
+Manage or switch the default database connection in multi-connection projects.
+
+**Usage:**
+```bash
+dbcli use [connection-name] [OPTIONS]
+```
+
+**Options:**
+- `--list` — List all connections and show the current default
+
+**Examples:**
+```bash
+# Show current default connection
+dbcli use
+
+# Switch default connection to 'prod'
+dbcli use prod
+
+# List all connections
+dbcli use --list
+```
+
+---
+
 > **`--use-env-refs`:** When enabled, the config stores environment variable names (e.g., `{"$env": "DB_HOST"}`) instead of actual values. This avoids writing sensitive credentials into the config file, making it suitable for multi-environment deployments and CI/CD pipelines. At connection time, dbcli automatically reads the actual values from the referenced environment variables.
 
 ---
@@ -224,12 +300,14 @@ dbcli query "SELECT * FROM users"
 
 **Options:**
 - `--format json|table|csv` — Output format (default: table)
-- `--output file` — Write to file instead of stdout
+- `--limit <number>` — Cap rows (overrides the automatic limit in query-only mode)
+- `--no-limit` — Disable the automatic 1000-row cap in query-only mode
 
 **Behavior:**
 - Enforces permission-based restrictions (Query-only mode blocks INSERT/UPDATE/DELETE)
-- Auto-limits results to 1000 rows in Query-only mode (notification shown)
+- Auto-limits results to 1000 rows in Query-only mode (notification shown), unless `--no-limit` or `--limit` applies
 - Returns structured results with metadata (row count, execution time)
+- To write CSV/JSON to a file, use shell redirection or the `export` command
 
 **Examples:**
 ```bash
@@ -239,8 +317,8 @@ dbcli query "SELECT * FROM users"
 # JSON (for AI/programmatic parsing)
 dbcli query "SELECT * FROM users" --format json
 
-# CSV export
-dbcli query "SELECT * FROM users" --format csv --output users.csv
+# CSV to stdout (redirect to a file)
+dbcli query "SELECT * FROM users" --format csv > users.csv
 
 # Pipe to other tools
 dbcli query "SELECT * FROM products" --format json | jq '.data[] | .name'
@@ -316,9 +394,9 @@ dbcli update users --where "id=2" --set '{"email": "new@example.com"}' --force
 
 ---
 
-#### `dbcli delete [table]` (Requires Admin permission only)
+#### `dbcli delete [table]` (Requires Data-Admin or Admin permission)
 
-Delete rows (admin-only for safety).
+Delete rows (blocked for query-only and read-write; requires elevated DML permission).
 
 **Usage:**
 ```bash
@@ -472,6 +550,80 @@ DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
 
 ---
 
+#### `dbcli check`
+
+Run data-quality and health checks on tables.
+
+**Usage:**
+```bash
+dbcli check [table] [OPTIONS]
+```
+
+**Options:**
+- `--all` — Check every table (skips huge tables unless `--include-large`)
+- `--include-large` — Include huge tables in `--all` scan
+- `--checks <types>` — Comma-separated checks: `nulls`, `duplicates`, `orphans`, `emptyStrings`, `rowCount`, `size`
+- `--sample <number>` — Sample size for large tables (default: 10000)
+- `--format json|table` — Output format (default: json)
+
+**Examples:**
+```bash
+# Check users table
+dbcli check users
+
+# Run specific checks only
+dbcli check orders --checks nulls,orphans --format table
+# Scan all tables
+dbcli check --all
+```
+
+---
+
+**Examples:**
+```bash
+dbcli check orders --format table
+dbcli check --all --checks nulls,duplicates --format json
+```
+
+---
+
+#### `dbcli diff`
+
+Save a schema snapshot or compare the live database to a previous snapshot (tables, columns, indexes).
+
+**Usage:**
+```bash
+dbcli diff --snapshot ./schema-before.json
+dbcli diff --against ./schema-before.json
+dbcli diff --against ./schema-before.json --format table
+```
+
+**Options:**
+- `--snapshot <path>` — Write the current schema to a JSON file
+- `--against <path>` — Diff live schema vs. the saved snapshot
+- `--format json|table` — Output format (default: `json`)
+- `--config <path>` — Config path (default: `.dbcli`)
+
+---
+
+#### `dbcli status`
+
+Show non-sensitive configuration summary (permission level, DB system, blacklist counts, config metadata version). Does not print connection credentials — intended for AI agents.
+
+**Usage:**
+```bash
+dbcli status
+dbcli status --format text
+dbcli status --format json
+```
+
+**Options:**
+- `--format text|json` — Output format (default: `json`)
+
+**Note:** This command reads the default project config path `.dbcli` (not the global `--config` flag).
+
+---
+
 #### `dbcli doctor`
 
 Run diagnostic checks on environment, configuration, connection, and data.
@@ -519,6 +671,72 @@ 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.
 
+#### `dbcli shell`
+
+Interactive database shell with SQL execution, auto-completion, and syntax highlighting.
+
+**Usage:**
+```bash
+dbcli shell          # Interactive mode (SQL + dbcli commands)
+dbcli shell --sql    # SQL-only mode
+```
+
+**Inside the shell:**
+- Type SQL statements ending with `;` to execute queries
+- Type dbcli commands without the `dbcli` prefix (e.g., `schema users`, `list`)
+- Press Tab for context-aware auto-completion (SQL keywords, table/column names)
+- Use `.help` for meta commands (`.quit`, `.clear`, `.format`, `.history`, `.timing`)
+- Multi-line SQL: input accumulates until `;` is found
+- History persists across sessions in `~/.dbcli_history`
+
+**Permission:** Inherits from config. SQL and commands are fully permission/blacklist enforced.
+
+#### `dbcli migrate`
+
+Schema DDL operations. **All commands default to dry-run** — use `--execute` to actually run the SQL.
+
+**Usage:**
+```bash
+# Create table
+dbcli migrate create posts \
+  --column "id:serial:pk" \
+  --column "title:varchar(200):not-null" \
+  --column "body:text" \
+  --column "created_at:timestamp:default=now()"
+
+# Execute (actually run the SQL)
+dbcli migrate create posts --column "id:serial:pk" --execute
+
+# Drop table (destructive — requires --execute --force)
+dbcli migrate drop posts --execute --force
+
+# Column operations
+dbcli migrate add-column users bio text --nullable --execute
+dbcli migrate alter-column users name --type "varchar(200)" --execute
+dbcli migrate alter-column users email --rename user_email --execute
+dbcli migrate drop-column users temp_field --execute --force
+
+# Index operations
+dbcli migrate add-index users --columns email --unique --execute
+dbcli migrate drop-index idx_users_email --table users --execute --force
+
+# Constraint operations
+dbcli migrate add-constraint orders --fk user_id --references users.id --on-delete cascade --execute
+dbcli migrate add-constraint users --unique email --execute
+dbcli migrate add-constraint users --check "age >= 0" --execute
+dbcli migrate drop-constraint orders fk_orders_user_id --execute --force
+
+# Enum (PostgreSQL only)
+dbcli migrate add-enum status active inactive suspended --execute
+dbcli migrate alter-enum status --add-value archived --execute
+dbcli migrate drop-enum status --execute --force
+```
+
+**Column spec format:** `name:type[:modifier...]` — Modifiers: `pk`, `not-null`, `unique`, `auto-increment`, `default=<value>`, `references=<table>.<column>`
+
+**Options (all subcommands):** `--execute` (run SQL), `--force` (skip confirmation for DROP), `--config <path>`
+**Permission:** admin only
+
 ---
 
 ## Global Options
@@ -534,6 +752,40 @@ All commands support these global options:
 
 ---
 
+## Internals & Strategy
+
+### Schema Update Strategy
+
+dbcli maintains a schema snapshot in your `.dbcli` config file. This allows AI agents to understand the database structure without constant network overhead. Understanding when this cache updates is key:
+
+1.  **Manual Updates:**
+    *   `dbcli schema`: Performs a full scan of the database.
+    *   `dbcli schema --refresh`: Incremental update. Detects changes and updates only the affected tables.
+    *   `dbcli schema --reset`: Clears the cache and re-fetches everything.
+2.  **Automatic Updates (DDL):**
+    *   When you execute DDL through `dbcli migrate` (e.g., `add-column`), the CLI automatically re-scans the affected table and updates the `.dbcli` snapshot after successful execution.
+3.  **Real-time Validation (Non-cached):**
+    *   Commands like `insert`, `update`, `delete`, and `check` fetch the latest schema from the database immediately before execution to ensure data integrity, but they **do not** update the long-term snapshot in `.dbcli`.
+
+> **Note:** If you change the database schema using external tools (like DBeaver or migration scripts), you **must** run `dbcli schema --refresh` to sync the snapshot so AI agents can see the changes.
+
+### How `dbcli migrate` Works
+
+The `migrate` command follows a strict safety pipeline to prevent accidental database corruption:
+
+1.  **Permission Check:** Verifies the user has `admin` privileges. DDL is blocked for all other levels.
+2.  **Blacklist Check:** Ensures the operation isn't targeting a table restricted in the security blacklist.
+3.  **Dialect-Specific Generation:** The `DDLGenerator` translates your request into the correct SQL for your system:
+    *   **PostgreSQL:** Uses `SERIAL`, native `ENUM` types, and double-quoted identifiers.
+    *   **MySQL/MariaDB:** Uses `AUTO_INCREMENT`, inline `ENUM` definitions, and backticked identifiers.
+4.  **Dry-run (Default):** All commands output the generated SQL for review without executing it.
+5.  **Execution & Confirmation:**
+    *   Requires the `--execute` flag to run.
+    *   Destructive operations (like `drop`) require both `--execute` and `--force`.
+6.  **Snapshot Sync:** After successful execution, it automatically triggers a schema refresh for the modified table to keep your `.dbcli` file up to date.
+
+---
+
 ## 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. The blacklist system works alongside permissions to provide fine-grained protection for sensitive tables and columns (see [Data Access Control](#data-access-control)).
@@ -542,9 +794,10 @@ dbcli implements a coarse-grained permission system with three levels. Permissio
 
 | Level | Allowed Commands | Blocked Commands | Use Case |
 |-------|------------------|------------------|----------|
-| **Query-only** | `init`, `list`, `schema`, `query`, `export` (limited to 1000 rows) | `insert`, `update`, `delete` | Read-only AI agents, data analysts, reporting |
-| **Read-Write** | + `insert`, `update` | `delete` | Application developers, content managers |
-| **Admin** | All commands | — | Database administrators, schema modifications |
+| **Query-only** | `init`, `list`, `schema`, `query`, `export` (limited to 1000 rows) | `insert`, `update`, `delete`, `migrate` | Read-only AI agents, data analysts, reporting |
+| **Read-Write** | + `insert`, `update` | `delete`, `migrate` | Application developers, content managers |
+| **Data-Admin** | + `delete` | `migrate` | Full DML access, no DDL |
+| **Admin** | All commands including `migrate` (DDL) | — | Database administrators, schema modifications |
 
 ### Configuration
 
@@ -552,8 +805,8 @@ Permission level is set during initialization:
 
 ```bash
 dbcli init
-# Prompts: "Permission level? (query-only / read-write / admin)"
-# Stored in ~/.dbcli as: "permissionLevel": "query-only"
+# Prompts: permission level (query-only / read-write / data-admin / admin)
+# Stored in project .dbcli/config.json as: "permission": "query-only"
 ```
 
 ### Permission-Based Examples
@@ -577,17 +830,18 @@ dbcli query "SELECT * FROM users"
 dbcli insert users --data '{"name": "Alice"}'
 dbcli update users --where "id=1" --set '{"name": "Bob"}'
 
-# Blocked: Delete (safety feature)
-dbcli delete users --where "id=1"  # ERROR: Admin only
+# Blocked: Delete (requires data-admin or admin)
+dbcli delete users --where "id=1"  # ERROR: Permission denied (read-write cannot DELETE)
 ```
 
 #### Admin Mode (Database Administrator)
 ```bash
-# Allowed: Everything
+# Allowed: Everything including DDL
 dbcli query "SELECT * FROM users"
 dbcli insert users --data '{"name": "Eve"}'
 dbcli update users --where "id=1" --set '{"status": "active"}'
-dbcli delete users --where "id=1" --force  # Only Admin can delete
+dbcli delete users --where "id=1" --force  # Data-Admin+ can delete
+dbcli migrate create posts --column "id:serial:pk" --execute  # Admin only
 ```
 
 ### Best Practices
@@ -700,7 +954,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### Claude Code (Anthropic)
 
-1. Install dbcli globally: `npm install -g dbcli`
+1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init` (choose permission level)
 3. Install skill: `dbcli skill --install claude`
 4. Restart Claude Code extension
@@ -712,7 +966,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### Gemini CLI (Google)
 
-1. Install dbcli globally: `npm install -g dbcli`
+1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install gemini`
 4. Start Gemini: `gemini start`
@@ -724,7 +978,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### GitHub Copilot CLI
 
-1. Install dbcli globally: `npm install -g dbcli`
+1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install copilot`
 4. Install Copilot CLI: `npm install -g @github-next/github-copilot-cli`
@@ -736,7 +990,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### Cursor IDE
 
-1. Install dbcli globally: `npm install -g dbcli`
+1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install cursor`
 4. Open Cursor editor
@@ -752,7 +1006,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 ```bash
 # 1. Install and initialize
-npm install -g dbcli
+npm install -g @carllee1983/dbcli
 dbcli init  # Choose "query-only" for safety
 
 # 2. Install skill to Claude Code
@@ -773,7 +1027,7 @@ dbcli dynamically generates skills based on your current configuration:
 
 ```bash
 # When permission level changes, skill updates automatically
-# Edit ~/.dbcli and change "permissionLevel" to "admin"
+# 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
@@ -812,8 +1066,8 @@ Hostname resolution failed (typo or DNS issue).
 **Solutions:**
 
 ```bash
-# Verify hostname in .dbcli
-cat ~/.dbcli | grep host
+# Verify hostname in project config (directory layout: .dbcli/config.json)
+grep host .dbcli/config.json
 
 # Test DNS resolution
 ping your-hostname.com
@@ -833,18 +1087,18 @@ Trying to write with Query-only permission level.
 **Solution:** Re-initialize with higher permission level:
 
 ```bash
-rm ~/.dbcli  # Remove old config
-dbcli init  # Re-run, choose "read-write" or "admin"
+rm -rf .dbcli   # Remove project config (destructive — backup if needed)
+dbcli init      # Re-run, choose "read-write", "data-admin", or "admin"
 ```
 
-#### "Permission denied: DELETE requires Admin"
+#### "Permission denied: DELETE operation requires Data-Admin or Admin"
 
-Only Admin can delete rows (safety feature).
+DELETE is not allowed in query-only or read-write mode.
 
-**Solution:** Re-initialize with Admin permission, or ask administrator.
+**Solution:** Use `data-admin` or `admin` permission (re-run `dbcli init`, or edit `.dbcli/config.json`), or ask an administrator.
 
 ```bash
-dbcli init  # Choose "admin"
+dbcli init  # Choose "data-admin" or "admin"
 dbcli delete users --where "id=1" --force
 ```
 
@@ -907,11 +1161,11 @@ npx is downloading and caching package.
 **Solution:** This is normal on first run. Subsequent runs are instant:
 
 ```bash
-npx dbcli init  # First run: 30s (downloads)
-npx dbcli init  # Second run: <1s (cached)
+npx @carllee1983/dbcli init  # First run: 30s (downloads)
+npx @carllee1983/dbcli init  # Second run: <1s (cached)
 
 # Or install globally for faster startup
-npm install -g dbcli
+npm install -g @carllee1983/dbcli
 dbcli init  # All future runs: <1s
 ```
 
@@ -928,8 +1182,8 @@ npm .cmd wrapper not created or PATH not updated.
 ```bash
 # Restart terminal to refresh PATH
 # OR reinstall globally
-npm uninstall -g dbcli
-npm install -g dbcli
+npm uninstall -g @carllee1983/dbcli
+npm install -g @carllee1983/dbcli
 
 # Verify installation
 where dbcli  # Windows command to find executable
@@ -971,7 +1225,12 @@ chmod +x dist/cli.mjs
 
 ## Development
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, testing, and release process.
+```bash
+bun test        # run test suite
+bun run build   # bundle CLI to dist/ (used before publish)
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for full setup, testing, and release process.
 
 ---