@carllee1983/dbcli 0.5.2-beta → 1.2.0

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. Trigger when working with databases, running SQL, exploring table structures, 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 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.
 ---
 
 # dbcli
@@ -22,16 +22,43 @@ dbcli query "SELECT * FROM users"   # Execute SQL
 Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
 
 ```bash
-dbcli init
+dbcli init                                              # Single connection (v1 format)
 dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
-dbcli init --use-env-refs           # Store env var references instead of values
-dbcli init --no-interactive --force # Non-interactive, skip overwrite confirmation
+dbcli init --use-env-refs                               # Store env var references
+dbcli init --no-interactive --force                     # Non-interactive mode
+
+# 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
+dbcli init --remove staging                              # Remove a named connection
+dbcli init --rename staging:production                   # Rename a connection
 ```
 
-**Key options:** `--system <postgresql|mysql|mariadb>`, `--permission <query-only|read-write|data-admin|admin>`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`
+**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+
+**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.
 
+### use
+
+Switch or display the default database connection (v2 multi-connection config).
+
+```bash
+dbcli use                   # Show current default connection
+dbcli use staging           # Switch default to 'staging'
+dbcli use --list            # List all connections (* marks default)
+```
+
+Any command can also use `--use <name>` to temporarily select a connection without changing the default:
+
+```bash
+dbcli query --use staging "SELECT * FROM users LIMIT 10"
+dbcli list --use prod
+```
+
+**Requires v2 config** (created with `dbcli init --conn-name`).
+
 ### list
 
 List all tables.
@@ -116,10 +143,11 @@ Export query results to file or stdout.
 
 ```bash
 dbcli export "SELECT * FROM users" --format csv --output users.csv
+dbcli export "SELECT * FROM users" --format csv --output users.csv --force  # Skip overwrite confirmation
 dbcli export "SELECT * FROM users" --format json | jq '.[]'
 ```
 
-**Options:** `--format <json|csv>` (required), `--output <path>`
+**Options:** `--format <json|csv>` (required), `--output <path>`, `--force`
 **Permission:** query-only+
 
 ### blacklist
@@ -222,6 +250,75 @@ dbcli upgrade --check           # Only check, do not upgrade
 
 **Background check:** Every command silently checks the npm registry for a newer version (at most once per 24 hours, cached in `.dbcli/version-check.json`). If a newer version is found, a one-line hint is printed to stderr after the command completes. Pass `-q` / `--quiet` to suppress the hint.
 
+### `dbcli shell`
+
+Start an interactive database shell.
+
+```bash
+dbcli shell          # Interactive mode with SQL + dbcli commands
+dbcli shell --sql    # SQL-only mode
+```
+
+Inside the shell:
+- Type SQL statements ending with `;` to execute
+- Type dbcli commands without the `dbcli` prefix (e.g., `schema users`)
+- Use Tab for auto-completion (SQL keywords, table names, column names)
+- Type `.help` for meta commands (.quit, .clear, .format, .history, .timing)
+- Multi-line SQL: keeps accumulating until `;` is found
+- History persists across sessions (~/.dbcli_history)
+
+### migrate
+
+Schema DDL operations. **All commands default to dry-run** — use `--execute` to actually run the SQL. Destructive operations (DROP) also require `--force`.
+
+```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()"
+
+# Drop table (dry-run by default)
+dbcli migrate drop posts
+dbcli migrate drop posts --execute --force   # Actually drop
+
+# Add/drop/alter column
+dbcli migrate add-column users bio text --nullable
+dbcli migrate drop-column users temp_field --execute --force
+dbcli migrate alter-column users name --type "varchar(200)"
+dbcli migrate alter-column users email --rename user_email
+dbcli migrate alter-column users status --set-default "'active'"
+dbcli migrate alter-column users bio --drop-default
+dbcli migrate alter-column users bio --set-nullable
+dbcli migrate alter-column users email --drop-nullable
+
+# Index management
+dbcli migrate add-index users --columns email --unique
+dbcli migrate add-index users --columns "last_name,first_name" --name idx_fullname
+dbcli migrate drop-index idx_fullname --execute --force
+
+# Constraint management
+dbcli migrate add-constraint orders --fk user_id --references users.id --on-delete cascade
+dbcli migrate add-constraint users --unique email
+dbcli migrate add-constraint users --check "age >= 0"
+dbcli migrate drop-constraint orders fk_orders_user_id --execute --force
+
+# Enum (PostgreSQL only — MySQL uses inline ENUM in column type)
+dbcli migrate add-enum status active inactive suspended
+dbcli migrate alter-enum status --add-value archived
+dbcli migrate drop-enum status --execute --force
+```
+
+**Column spec format:** `name:type[:modifier[:modifier...]]`
+- Modifiers: `pk`, `not-null`, `unique`, `auto-increment`, `default=<value>`, `references=<table>.<column>`
+- Serial types: `serial`, `bigserial`, `smallserial` (auto-expand per DB dialect)
+
+**Options (all subcommands):** `--execute`, `--force`, `--config <path>`
+**Permission:** admin
+
+**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.
+
 ## Permission Levels
 
 | Level | Allowed Operations |
@@ -229,7 +326,7 @@ dbcli upgrade --check           # Only check, do not upgrade
 | query-only | SELECT, list, schema, export |
 | read-write | query-only + INSERT, UPDATE |
 | data-admin | read-write + DELETE (full DML, no DDL) |
-| admin | data-admin + DROP, ALTER, CREATE, TRUNCATE |
+| admin | data-admin + DDL (migrate create/drop/alter, DROP, ALTER, CREATE, TRUNCATE) |
 
 Set via `dbcli init --permission <level>` or in `.dbcli` config.
 
@@ -238,6 +335,7 @@ Set via `dbcli init --permission <level>` or in `.dbcli` config.
 | Flag | Description |
 |------|-------------|
 | `--config <path>` | Path to .dbcli config file (default: `.dbcli`) |
+| `--use <connection>` | Use a specific named connection (v2 config) |
 | `-v, --verbose` | Increase verbosity (`-v` verbose, `-vv` debug) |
 | `-q, --quiet` | Suppress non-essential output |
 | `--no-color` | Disable colored output (also respects `NO_COLOR` env var) |