docs: profile selection logic

radim · radim · commit dae4e537ef35 · 2026-05-01T21:39:14.000+02:00
diff --git a/README.md b/README.md
@@ -167,6 +167,10 @@ dryrun --profile billing snapshot diff --latest
 
 See [`docs/dryrun-toml.md`](docs/dryrun-toml.md) for all profile options.
 
+Every DB-related command (`init`, `import`, `probe`, `dump-schema`, `lint`, `drift`, `stats apply`, all `snapshot` subcommands) accepts `--profile` and falls back to the resolved profile's `db_url` and `schema_file` when the corresponding CLI flag is not provider.
+
+> **Note:** the MCP server is currently single-database. Using the default profile. Or the option is to run one `dryrun mcp-serve` process per database. Native multi-database support inside one MCP process is tracked in [#4](https://github.com/boringSQL/dryrun/issues/4).
+
 ## MCP server
 
 Add `dryrun` to your AI assistant. If you installed via Homebrew, `dryrun` is already on your PATH:
@@ -183,6 +187,8 @@ claude mcp add dryrun -- /path/to/dryrun mcp-serve
 
 That's it. The server auto-discovers `.dryrun/schema.json` in the current project. No database credentials needed, your AI assistant gets full schema intelligence from the offline snapshot.
 
+For projects with multiple databases, run one `dryrun mcp-serve` per database and add an entry per server in your client config. Native multi-database serving inside one MCP process is tracked in [#4](https://github.com/boringSQL/dryrun/issues/4).
+
 See the [Tutorial](TUTORIAL.md) for live database setup, SSE transport, and Claude Desktop configuration.
 
 ## More
diff --git a/docs/dryrun-toml.md b/docs/dryrun-toml.md
@@ -56,12 +56,16 @@ profile = "offline"
 
 ### Resolution order
 
-1. `--db` flag (CLI only, bypasses profiles entirely)
-2. `--schema-file` flag (CLI only)
-3. `--profile` flag
-4. `PROFILE` environment variable
-5. `[default].profile` in dryrun.toml
-6. Auto-discovery of `.dryrun/schema.json`
+A profile is selected from:
+
+1. `--profile` flag
+2. `PROFILE` environment variable
+3. `[default].profile` in dryrun.toml
+4. Auto-discovery of `.dryrun/schema.json` (no profile, just a schema)
+
+CLI flags `--db` and `--schema-file` override the resolved profile's matching fields for that invocation; they don't bypass the profile, so `database_id` and `project_id` are still taken from it. `--profile billing --db $OTHER` connects to `$OTHER` but keys snapshots under billing's `database_id`.
+
+Every DB command (`init`, `import`, `probe`, `dump-schema`, `lint`, `drift`, `stats apply`, all `snapshot` subcommands) accepts `--profile` and falls back to the resolved profile's `db_url` / `schema_file` when the corresponding CLI flag is omitted.
 
 Relative paths in `schema_file` are resolved from the project root (the directory containing `dryrun.toml`). Absolute paths work too.
 
