Discover PostgreSQL databases automatically with environment-first 0.3.1 setup

[codegiveness]

Final 0.3.1 hosted verification

At head 70bf2c7f9ee86c188754cd4baf94491481bb10ae, all 12 executed hosted checks passed: Linux integration and installed npm/NuGet verification, native npm/NuGet installation on macOS and Windows, SQL fuzzing, container/dependency/secret scans, four CodeQL baseline/candidate scans and the trusted raw-SARIF regression gate. The non-PR analyze job was skipped by design and is not counted as a pass.

• CI and native installation
• CodeQL and raw-SARIF gate
• SQL fuzzing
• Container security
• Dependency scan
• Secret scan

GitHub rendered README review was unavailable: both immutable-commit and branch browser URLs returned GitHub’s Unicorn error page. Local link/anchor/JSON review and exact documented command/runtime smoke passed; no successful hosted-page visual review is claimed.

Environment-first 0.3.1 patch follow-on

• Single-server setup inherits POSTGRES_CONNECTION_STRING; primary MCP JSON contains no credentials and requires no targets file. Existing protected multi-profile files remain optional.
• Exact masked Bash/PowerShell prompts, native Zsh prompt syntax and optional secret-free .bashrc/.zshrc functions; login profiles, ZDOTDIR, explicit invocation and same-shell client launch are documented. PowerShell 7.1+ must run in an interactive terminal.
• Explain plaintext/inheritance and persistence tradeoffs, full client restart for environment changes, stale client/file-setting removal, remote TLS verification and one-layer Npgsql versus two-layer JSON quoting. No operator credentials or startup files were changed.
• Package metadata uses 0.3.1, not another minor increment. The earlier discovery/default-unrestricted contract remains the 0.3.0 capability boundary. No release or registry publication is claimed.

Local verification

• Locked integration: environment-only discovery, all nine optional-target tools, concurrent physical selection, live creation/CONNECT revocation, permissions/RLS, read-only default, explicit writes/rollback, optional protected file, conflicting sources failing closed, capacity/cancellation/disposal and confidentiality passed.
• Build packaged portable/five-RID artifacts using committed locks; installed actual npm and NuGet 0.3.1 entrypoints offline and exercised discovery, newly created database selection, default read-only rejection, write commit/cleanup, missing-runtime diagnostics and shutdown.
• Full reachable Git history passed the maintained Gitleaks rules with redaction, inline bypasses disabled and no new exceptions.
• Exact README Bash and interactive PowerShell prompts passed with a synthetic semicolon/quote/dollar/backslash credential, stale-profile clearing, child-client MCP discovery/physical selection and no credential in captured output. Exact Bash/Zsh rc functions also passed empty/EOF rejection and left isolated secret-free rc files unchanged. Shell smoke ran on Linux with PowerShell 7; no operator database or rc file was used.
• CLI --version/--help report 0.3.1 and environment-first setup. Documentation audit: 38 local links/anchors and 11 JSON examples valid.

Hosted checks for the follow-on head passed as recorded above; historical results below still apply only to their named earlier revision.

---

Prior discovery-head hosted verification

At head d9e2b0eaf8467b7d6d0e472e7f7764cb2461f499, all 12 executed hosted checks passed: Linux integration/installed-package verification, native npm/NuGet installation on macOS and Windows, coverage-guided SQL fuzzing, container/dependency/secret scanning, all four CodeQL baseline/candidate scans and the trusted raw-SARIF regression gate. The non-PR analyze job was skipped by design, not counted as a pass.

• CI and native installation
• CodeQL and raw-SARIF comparison
• Coverage-guided SQL fuzzing

Native platform proof is installation/CLI/MCP/error/shutdown; live PostgreSQL discovery/query/write proof is provided by the Linux owned disposable fixture. PR remains unmerged; 0.3.0 is locally installed, not a published release.

Problem

Per-database alias registration prevented the agent from discovering and selecting newly accessible PostgreSQL tenant databases. The user requested server-catalog discovery modeled on their codegiveness/mssql-mcp repository and unrestricted access when no mode is supplied.

Behavior

• Prepare 0.3.0: targets-file entries are connection profiles/bootstrap seeds, not mandatory per-database allowlist entries. Existing aliases still select their seed DB.
• list_databases queries live pg_catalog.pg_database, excludes templates/disabled connections and checks CONNECT, returns {target, databases: QueryPage, access_mode, limits}. New databases require no file edits/restart.
• Other tools accept physical database names; optional target chooses a configured profile. No shared USE/current-database state, host/credential substitution or failure fallback.
• Bare connection strings work; explicit POSTGRES_DATABASES remains an optional restrictive allowlist.
• Default mode becomes unrestricted; explicit restricted remains effective. read_only=true remains the SQL-call default and writes still require read_only=false. PostgreSQL roles/RLS remain the authority.
• Normalize pool identity; keep at most 256 / PoolSize data sources, evict idle entries, retain in-flight leases, and include capacity waits in the original deadline.

Observed verification

Using the existing .NET 10.0.401 SDK with locked restores:

• dotnet run --project tools/PostgreSqlMcp.Verify -c Release -p:RestoreLockedMode=true -- integration passed all real MCP/PostgreSQL scenarios, including immutable single-seed configuration, concurrent physical switching, live creation/CONNECT revocation, punctuation names, explicit profiles/allowlists, permissions/RLS, default unrestricted DML/DDL commit and rollback, cache churn/busy capacity/deadline recovery and cleanup. Existing SQL/metadata/HypoPG/sanitization boundaries and 129 FsCheck PostgreSQL literal scenarios passed.
• dotnet run --project tools/PostgreSqlMcp.Build -c Release -p:RestoreLockedMode=true -- package --output artifacts/discovery-packages built npm/NuGet 0.3.0 artifacts and five RID apphosts.
• dotnet run --project tools/PostgreSqlMcp.Verify -c Release -p:RestoreLockedMode=true -- packages --artifacts artifacts/discovery-packages installed both artifacts into isolated locations and exercised their actual entrypoints, including live discovery/new database selection without seed edits and explicit write commit/cleanup.
• 30 local documentation links/anchors and 12 JSON examples checked; npm and best-practices JSON parsed.
• Initial punctuation fixture failed because psql treats -d values containing = as connection info; isolated CLI reproduced that parser error. Fixture now uses PGDATABASE, retaining the original boundary test; the full integration and package runs above passed afterward.

All database runtime evidence uses owned disposable fixtures. No operator databases were queried. Earlier README rendering/setup evidence and hosted results at e31de7b remain historical, not proof for this new runtime head.

Compatibility and limits

This broadens database reach to the configured role's existing grants and changes the default mode and listing payload. Review PUBLIC CONNECT/object grants before deployment; aliases are not a tenant isolation boundary. Existing sessions are not terminated merely by REVOKE CONNECT. Database-agnostic means PostgreSQL database independence, not multi-engine SQL support.

The release is not published; the available 0.2.0 archive lacks these features. README identifies this version boundary and source/local artifact routes. No merge, new registry publication or repository-setting change is authorized/performed by this PR. Hosted checks at 2ac00b8: Linux integration/package verification, coverage-guided SQL fuzzing, container/dependency/secret scans, four baseline/candidate CodeQL scans and the raw-SARIF comparison passed. Both native installation jobs failed because the new default package verifier requires Docker (missing executable on macOS; rejected container on Windows). Repair adds explicit --installation-only for these platform jobs: both actual installed distributions still run CLI/MCP/unavailable-endpoint checks; Linux retains full live database scenarios. Subsequent head checks are pending.

Local installation: the saved MCP command now points to installed 0.3.0. Protected targets bytes and 0600 permissions, explicit restricted mode and other MCP entries are unchanged. The saved command was exercised with a substituted owned disposable seed: MCP initialization/nine tools, live discovery after CREATE DATABASE, physical selection in a read-only transaction and clean shutdown passed. No operator database was queried.

Scanner repair: exact Password=writer-disposable is permitted only in the maintained Packages.cs disposable fixture. Different passwords at that path and the same password outside that path failed; corrected full reachable-history scan passed before push. Published rendered README version boundary checked visually.

Native-runner repair locally verified with locked restore: packages --artifacts artifacts/discovery-packages --installation-only passed actual npm/NuGet installation/CLI/MCP/error/shutdown checks; the default packages --artifacts artifacts/discovery-packages then passed the full live fixture scenarios for both distributions again. Combining --installation-only with --targets-file is rejected before installation or target access.

At b232fac, Windows native installation and all Linux/security checks passed; macOS reached MCP but rejected the unavailable-endpoint error code. The fixture had relied on an owned bound, non-listening socket. Repair owns a listening loopback socket, accepts and closes each handshake, and cancels/joins its accept task on disposal. The server error mapping and exact expected connection_error assertion are unchanged. Subsequent native checks will provide platform proof.