fix: TOML config loading, DSN conflict, and .env interpolation

[tianzhou]

Three related fixes to how database sources are configured. Two are breaking. Follow-up to #367, where investigating a test failure surfaced the first.

1. TOML config is loaded only via --config

resolveTomlConfigPath() fell back to ./dbhub.toml in the current working directory when --config was absent. Since TOML config selects the database outright, that meant running DBHub from the wrong directory could silently repoint it at a different database — or make an explicitly supplied DSN look ignored for no reason:

$ npx tsx src/index.ts --dsn="sqlite://:memory:"     # in a dir with dbhub.toml
Configuration source: dbhub.toml
Fatal error: error: database "employee" does not exist

The user asked for SQLite and got a Postgres error, never having mentioned TOML.

Nothing shipped depends on the old fallback: the MCPB bundle already passes --config ${__dirname}/dbhub.toml (mcpb/manifest.json), and every documented invocation passes --config explicitly.

2. --config and --dsn cannot be combined

resolveSourceConfigs() returned the TOML config before resolveDSN() was ever consulted, so --dsn was silently ignored. The documented priority order said the opposite — CLAUDE.md and docs/config/command-line.mdx both claimed "command-line arguments (highest priority)" over TOML.

TOML wins, and the docs were wrong. The two are conflicting rather than layered: TOML is multi-database, a DSN is single-database. Passing both flags now errors, mirroring the existing --id guard:

Error: The --dsn flag cannot be used with TOML configuration (dbhub.toml). ...

The guard is deliberately limited to the flag. DSN and DB_* environment variables are not conflicts, whether exported or read from .env — see below.

3. .env is loaded before TOML, so ${VAR} interpolation resolves

interpolateEnvVars() reads process.env, but .env was only loaded inside resolveDSN() — the fallback path that never runs when --config is given. So the recommended pattern of keeping credentials out of the config file did not work:

# .env
DSN=postgres://user:pass@localhost:5432/mydb

# dbhub.toml
[[sources]]
id = "prod"
dsn = "${DSN}"

Configuration source: dbhub.toml
  - prod: ${DSN}
Fatal error: No connector found for DSN: ${DSN}

This is the same fix as #358 by @kevinke, narrowed in scope and with a regression test — that PR can be closed once this merges.

The narrowing matters: #358 calls loadEnvFiles() unconditionally. On the DSN path resolveDSN() already loads .env itself, and it does so after checking process.env so it can report whether a value came from the environment or from the file. Preloading unconditionally relabels every .env-sourced DSN as environment variable in the startup log. Scoping the load to TOML mode avoids that; verified the DSN path still reports Configuration source: .env file.

Why fixes 2 and 3 belong together

They pull in opposite directions, and getting one right requires the other. An earlier revision of this PR rejected any DSN-shaped environment variable as a conflict — which would have broken the interpolation pattern above outright. Only --dsn expresses unambiguous intent; environment variables are config material for TOML, not a competing setup.

⚠️ Breaking changes

1. dbhub.toml in the current directory is no longer loaded. Pass --config ./dbhub.toml.
2. --config together with --dsn now fails to start instead of silently using TOML.

Both warrant a release note. The second was chosen over a warning because silent-ignore is what produced the confusing failure above, and a stderr warning is easy to miss in stdio mode.

Docs

Both docs described a single priority ladder. The accurate model is two independent rules, since TOML only defines sources and tools and cannot express transport/port/host:

• Source selection: TOML (via --config) or a DSN. Within DSN mode: --dsn > DSN > DB_* > .env.
• Everything else: CLI > env > .env > defaults (unchanged, always correct).

Rewritten to describe the model directly rather than contrast against previous behavior. Updated CLAUDE.md, docs/config/command-line.mdx, docs/config/toml.mdx.

Verification

• 1107 tests passing. New coverage: --dsn + --config rejected; DSN env var + --config allowed; DB_* + --config allowed; .env loaded before TOML parsing; a cwd dbhub.toml ignored.
• The .env-before-TOML test was confirmed to fail without the fix, not merely pass alongside it.
• The 106 toml-loader tests that wrote dbhub.toml into a temp cwd now point --config at it via one line in beforeEach, rather than 106 edits.
• Manually verified against real configs: dsn = "${DSN}" resolves from both an exported variable and a .env file; the DSN path still reports .env file as its source; --dsn + --config errors; cwd dbhub.toml ignored; missing --config path still errors.
• Only failure is sqlserver.integration.test.ts (container won't boot on arm64) — fails identically on clean main.

Rebased onto main after #367 merged.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes TOML-based multi-database configuration mutually exclusive with single-database DSN configuration, rejecting ambiguous setups (e.g., dbhub.toml present alongside --dsn, DSN, DB_*, or DSN in .env) with an explicit, actionable error. It also updates the documentation to reflect the clarified configuration model and adds tests around DSN conflict detection and side-effect-free .env inspection.

Changes:

• Split env file discovery into findEnvFile() so DSN conflict detection can inspect .env contents without mutating process.env.
• Add detectDSNConfig() and enforce TOML/DSN mutual exclusivity in resolveSourceConfigs(), reporting the DSN’s origin in the error.
• Update docs (and CLAUDE.md) to describe the two-rule model: “sources” are TOML-or-DSN, while all other settings follow the normal CLI/env precedence; add tests for the new detection logic.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/config/env.ts	Adds side-effect-free DSN detection and rejects TOML+DSN combinations; refactors env file discovery.
src/config/tests/env.test.ts	Adds tests for DSN detection and TOML/DSN conflict handling.
docs/config/toml.mdx	Documents TOML/DSN mutual exclusivity and the startup error behavior.
docs/config/command-line.mdx	Rewrites the priority explanation into separate “database sources” vs “other settings” rules and documents the exclusivity constraint.
CLAUDE.md	Updates configuration guidance and priority rules to match the new behavior.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.