feat: per-connection session setup SQL (survives connection pooling)

[soukicz]

Summary

Adds an opt-in session setup SQL (initSql) per PostgreSQL connection — one or more statements that dotaz runs on every backend session and re-applies after the internal DISCARD ALL reset. This makes dotaz usable against databases that gate data access on session state, the headline case being Row-Level Security keyed on a session GUC:

CREATE POLICY tenant_isolation ON sale_item
  USING (shop = current_setting('app.current_shop'));

Today such databases show every table as empty in dotaz with no workaround that survives table browsing. With initSql = "SET app.current_shop = 'acme'", clicking a table shows that tenant's rows, and it stays scoped across repeated browsing/queries.

The feature is opt-in and empty by default — a no-op for existing users.

Why a startup parameter isn't enough

The pool resets reused connections with DISCARD ALL (i.e. RESET ALL), which clears any session GUC — including startup-supplied ones. So forwarding a startup option only works for the first query; every subsequent pooled query/table-browse goes empty again. The correct primitive is re-runnable SQL re-applied after every reset, not a startup option.

What changed

• ConnectionPool gains an optional initFn, applied at every point a physical connection is (re)established or reset: system-connection connect/reconnect, freshly created pinned/ephemeral connections, and after DISCARD ALL on release. createConnection/acquireConnection are now async (callers updated).
• PostgresDriver derives initFn from config.initSql. A failing initSql rejects connect() with a surfaced error; init-failure paths clean up rather than leaking a socket or publishing an un-initialized system connection.
• MySQL driver: await-only updates for the now-async pool methods (no feature — PostgreSQL-only scope).
• Headless / Docker (env-connection.ts): reads DOTAZ_INIT_SQL (takes precedence) and translates a libpq-style ?options=-c key=value in DATABASE_URL into SET key = 'value'; so standard libpq URLs work and survive the pool reset.
• UI: a "Session setup SQL" textarea (PostgreSQL only) in the connection editor.
• Config type: initSql?: string on PostgresConnectionConfig, stored as plain config metadata (like host/user), not via the encrypted secrets path.

Empty/unset initSql ⇒ behavior is byte-for-byte unchanged (DISCARD ALL only, as today).

Coverage

All four session-start points are covered: the pooled table-browser/grid/loadSchema path (persistent system connection), the acquire/release + DISCARD ALL path (CSV/JSON export, iterate, default transaction), and pinned/ephemeral sessions.

Tests

• tests/postgres-init-sql.test.ts (new, docker-gated): against a real RLS table and a non-superuser role — proves a pooled query is scoped, that scoping survives DISCARD ALL across repeated iterate/export passes (not just the first query), that a pinned session is scoped without a manual SET, per-tenant isolation, the empty-initSql control, and that a failing initSql surfaces a connection error.
• tests/env-connection.test.ts (extended): DOTAZ_INIT_SQL, libpq ?options= translation, precedence, and quote-escaping.

bunx tsc --noEmit, bun run lint, and dprint check all clean; no regressions in the existing pg/driver/pool/export/explain suites.

Acceptance criteria

1. ✅ With initSql (or DATABASE_URL=…?options=-c app.current_shop=acme, or DOTAZ_INIT_SQL), clicking a table shows the tenant's rows.
2. ✅ Browsing many tables / running many queries stays scoped (survives the reset).
3. ✅ A pinned/manual session is scoped without typing SET.
4. ✅ EXPLAIN/ANALYZE and CSV/JSON export return scoped data.
5. ✅ With initSql empty, behavior is identical to current main.
6. ✅ A failing initSql produces a visible connection error.

🤖 Generated with Claude Code

[matej21]

Thanks a lot for this 🙏 Really nicely solved — especially the insight that a startup parameter isn't enough and the session SQL has to be re-applied after DISCARD ALL. That's exactly the right call.

While reviewing, we went ahead and extended it to MySQL (re-applied after RESET CONNECTION) and SQLite (per-connection setup, also applied to the separate iterate connection) — so initSql is now consistent across all three drivers, including DOTAZ_INIT_SQL for MySQL in headless mode and the connection-dialog UI field.

One thing we hit while testing: on SQLite, Bun's driver stops a multi-statement unsafe() at the first statement that returns rows (PRAGMA x = N returns its value), so a typical PRAGMA a; PRAGMA b silently dropped the second one — handled now by running statements one at a time. Added tests cover it (mysql-init-sql, sqlite-init-sql), CI green.

Squash-merged into main. Thanks again! 🚀

[matej21]

Shipped in v0.0.23 🎉 — https://github.com/contember/dotaz/releases/tag/v0.0.23

Desktop builds (Linux x64/ARM64, macOS x64/ARM64, Windows x64), the ghcr.io/contember/dotaz Docker image and the @dotaz/server npm package are all out. Thanks again for the contribution! 🙏