@carllee1983/dbcli 9.1.2 → 11.0.0

package/skills/dbcli/reference.md

@@ -119,24 +119,24 @@ dbcli query '{}' --collection events --format json 2>/dev/null | jq '.rows | len
 Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
 
 ```bash
-dbcli init                                              # Single connection (v1 format)
-dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
+dbcli init                                              # Prompt for a name; create named v2
+dbcli init --conn-name local --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
+dbcli init --conn-name local --no-interactive --force    # Non-interactive; credentials from environment
 
 # MongoDB — field-by-field (primary path, same shape as SQL)
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
-dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
-# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb  # No auth
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
+dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
-dbcli init --system redis --host localhost --port 6379
-dbcli init --system redis --host localhost --port 6379 --password secret --name 0
+dbcli init --conn-name local --system redis --host localhost --port 6379
+dbcli init --conn-name local --system redis --host localhost --port 6379 --password secret --name 0
 
 # Elasticsearch
-dbcli init --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
-dbcli init --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
+dbcli init --conn-name local --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
 
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
@@ -151,17 +151,43 @@ dbcli --global init --conn-name shared --system postgresql --host db.example.com
 dbcli --global use --list
 ```
 
+Every new or additional connection needs a nonblank connection name. Pass `--conn-name <name>`, or run `dbcli init` in an interactive terminal to be asked for one. The name prompt has no suggested `default`; empty or whitespace-only answers explain the requirement and prompt again. Cancelling or ending the name prompt stops before any connection test or configuration/credential write. An explicit nonblank `--conn-name` skips this prompt, and `--conn-name default` is valid. An explicitly blank `--conn-name` is an error in every mode, before connection tests or writes. `--name` still means the database name (the logical DB index for Redis), never the connection name.
+
+Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `--env-*` options automatically disables interaction, a missing or blank `--conn-name` fails with guidance to supply it, before database access or configuration/credential writes. Complete credentials, `--name`, `--env-file`, and `--force` do not supply a connection name.
+
+New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
+
 **Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
+**MongoDB-specific options:** `--uri <uri>` (full connection URI, decomposed into field config on write: `authSource`/`replicaSet`/`tls`(`ssl`) become dedicated fields, `mongodb+srv` becomes `srv: true`, the path database becomes `database`, other parameters go to `options`; multi-host strings, strings carrying `authMechanismProperties`/`tlsCertificateKeyFilePassword`/`proxyPassword`, strings repeating a query key, and strings whose `authMechanism` is not SCRAM-SHA-1/SCRAM-SHA-256 are stored as-is in `uri` with a plaintext-credentials warning; cannot be combined with `--host`/`--port`/`--user`/`--password`/`--auth-source`/`--replica-set`/`--srv`/`--tls`/`--no-tls` or `--use-env-refs`; `--name` may be combined), `--auth-source <db>` (auth database, default: `admin` when user/password set). `--replica-set <name>` (writes `replicaSet`), `--srv` (writes `srv: true` and no `port`; builds `mongodb+srv://` and resolves hosts via DNS SRV), `--tls` / `--no-tls` (writes `tls: true` / `tls: false`; neither flag writes no `tls` key, so the driver default applies). Interactive `init` skips the prompt for any of these given as a flag; otherwise it asks `srv` right after `host` (before `port`) and `replicaSet` / `tls` under an "advanced options?" prompt. The flags also apply with `--use-env-refs`.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
 **Redis note:** the `database` (or `--name`) field is the logical DB index (`"0"` … `"15"`), not a database name.
 
-**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.
+**Multi-connection:** Every newly created connection uses v2 with an explicitly supplied or interactively entered name. Each connection can have its own env file and permission level; `--env-file` does not replace the name requirement. Existing v1 configs are automatically imported as the `default` connection when upgrading.
+
+V2 may omit the top-level `default` field; if supplied, it must be a nonempty
+string naming an existing connection. `null`, `""`, and nonexistent names are
+invalid. The first explicitly named connection defaults a new registry; adding
+another preserves the existing default or no-default state. Existing v1 reads
+and named v1 imports remain supported; neither configuration version changes.
+
+Legacy project configuration compatibility: adding a connection cannot import a
+direct-project v2 registry when an existing connection uses an `envFile` other
+than `.env.local`. `init` refuses before writing and retains the existing config
+and env files. An administrator must migrate the registry and custom env files
+to supported home storage before retrying. Bound/home-storage v2 configs and
+direct-project v2 configs with no `envFile` or only `.env.local` remain supported.
+
+`init --remove <name>` clears `default` and reports that change when removing its
+connection; it never chooses another connection. Removing a non-default keeps
+the saved default, and removing a connection from a no-default config keeps that
+state. The public `removeConnection` helper follows the same rules. Deleting
+the last connection is rejected without changing the config. Renaming preserves
+the no-default state, or updates the default name when renaming that connection.
 
 Use root-level `--global` with `init`, `use`, `status`, `query`, or any other command to read or mutate the user-global v2 registry at `~/.config/dbcli/config.json`. Without it, the current project binding remains the source of truth. The global registry uses the same private file mode and integrity record as project home storage.
 
@@ -169,11 +195,12 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 ### use
 
-Switch or display the default database connection (v2 multi-connection config).
+Set, clear, or display the default database connection (v2 multi-connection config).
 
 ```bash
-dbcli use                   # Show current default connection
+dbcli use                   # Show the current default, or describe no default
 dbcli use staging           # Switch default to 'staging'
+dbcli use --unset            # Clear the saved default; connections are unchanged
 dbcli use --list            # List all connections (* marks default)
 dbcli use --list --format json # Credential-free connection identity inventory
 ```
@@ -188,17 +215,43 @@ Cloud ID-only Elasticsearch connections also return `null` instead of default
 placeholders. It deliberately excludes user names, passwords, URIs, Cloud IDs,
 API keys, and env variable names.
 Misspelled selectors suggest nearby configured connection names.
+Without a default, text inventory marks no connection as default and every JSON
+item has `isDefault: false`. Inventory remains usable, and `doctor` accepts an
+omitted default as valid v2 configuration. Its connection checks still require
+an explicit selector, for example `dbcli --use staging doctor`.
 
-Any command can also use `--use <name>` to temporarily select a connection without changing the default:
+Any command can also use root-level `--use <name>` before the command to
+temporarily select a connection without changing the default. `query`, `schema`,
+`list`, `export`, and `check` also accept it after the command:
 
 ```bash
 dbcli query --use staging "SELECT * FROM users LIMIT 10"
 dbcli list --use prod
 ```
 
+Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the
+saved default. Conflicting root-level and command-level selectors are an error;
+blank CLI selectors are invalid, while a blank environment selector is ignored.
+Without a default, connection-dependent commands require an explicit `--use` or
+`DBCLI_CONNECTION` selection. Otherwise they fail before database access with
+an error naming both selectors and listing available connection names, never
+endpoints or credentials. No caller selects the first connection automatically.
+Unknown names and production targets retain their validation and explicit
+selection safeguards.
+
+`use --unset` removes only the persisted v2 `default` field and reports that it
+was cleared. It also succeeds when the field is already absent without changing
+connections. It rejects a connection name, `--list`, `--confirm-production`, or
+`--format json` in the same invocation before writing, and never converts or
+overwrites v1. It uses the existing approved, integrity-protected configuration
+write path and is blocked under `DBCLI_AGENT_MODE=1`. To set a default again, use
+`dbcli use <name>`; production defaults still require the exact name repeated in
+`--confirm-production <name>`, and production database access still requires an
+explicit selector even if that connection is the saved default.
+
 **Requires v2 config** (created with `dbcli init --conn-name`).
 
-**Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
+**Options:** `--list`, `--unset`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
 
 ### password
 
@@ -3591,7 +3644,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow (stored as-is) and the non-interactive path via `--uri` (with the required `--conn-name`), where the string is decomposed into the field config on write. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 
@@ -3617,10 +3670,10 @@ The 5000ms default server-selection timeout is often too tight for a connection
 
 ```bash
 # 1. Initialize — field-by-field (primary path)
-dbcli init --system mongodb --host localhost --port 27017 \
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 \
   --user admin --password '<secret>' --auth-source admin --name mydb
 # ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
-dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
+dbcli init --conn-name local --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections
 dbcli list --format json