feat: PostgreSQL backend

[YpNo]

Closes #605.

Adds PostgreSQL as an alternative to the embedded SQLite database. SQLite stays
the default and the zero-config path. Omitting server.database changes
nothing for an existing install.

Six commits, each reviewable on its own:

1. fix(auth) : two bugs found while scoping this, unrelated to PostgreSQL.
   Concurrent first logins could leave the instance with no owner (the count
   ran as a statement separate from the insert, so both racers saw two rows and
   neither promoted itself), and nothing ever closed the database handle. The
   regression test fails on the old code.
2. refactor(db) : createDbClient returns the connection bundled with its
   schema and dialect. auth.ts and hp-agent.ts unpack it once, so every query
   body is unchanged apart from users becoming tables.users.
3. docs(changelog)
4. feat(config) : server.database, which also lets the SQLite file live
   somewhere other than data_path.
5. feat(db) : the PostgreSQL backend, migrations, and the contract tests.
6. feat(db) : a SQLite -> PostgreSQL copy helper.

One thing to look at first

The plan was for the query layer to be typed against a union of both dialects'
clients. That does not compile: TypeScript cannot call a method on a union of
generic signatures, and every .select() fails with "none of those signatures
are compatible with each other". The only union that compiles contains any,
which would erase type checking from every query in the codebase.

So queries stay typed against the SQLite client and the PostgreSQL client is
cast to it once, in createPostgresClient, with the reasoning written at the
definition. The alternative was a repository port with one implementation per
dialect. The large refactor you have said you do not want, for a three-table
schema.

What makes the cast safe is tests/integration/db, which runs the same query
code against both engines: SQLite in memory, and real PostgreSQL 17 under
testcontainers (already a devDependency, already used by the docker and dex
suites). 31 tests, covering the divergences types would not have caught anyway.
Timestamps surfacing as Date from both an integer epoch and a timestamptz,
JSON round-tripping as an object from both text and jsonb, nullable columns,
upserts, ownership transfer.

I also checked that no SQLite-only method (.get(), .all(), .run()) appears
in shared query code, and said so in a comment where the cast lives.

If you would rather have compiler-proven safety than tested safety, say so. But
that means the repository port, and I did not want to spring that on you.

Owner bootstrap under READ COMMITTED

The single-statement guard from commit 1 is atomic under SQLite's serialized
writes. It is not under PostgreSQL: two concurrent first logins update
different rows, take no conflicting row locks, both see no owner, and both
commit. The PostgreSQL schema carries a partial unique index on role = 'owner'
as the real guarantee, with a test asserting it actually rejects a second owner.

It is created unconditionally because PostgreSQL support is new. No existing
database could already hold two owners. SQLite deliberately does not get it:
that migration would fail to apply on any install where the race already fired.

Notes

• Existing drizzle/* migrations are untouched; PostgreSQL lives in
  drizzle/postgres/.
• The migrators differ by dialect (SQLite synchronous, PostgreSQL returning a
  promise). A failed migration drains the pool before rethrowing so a failed
  start does not hang the process.
• Connection strings are redacted wherever they are logged.
• server.database.password_path follows the existing _path secret convention.
• Driver is pg.
• docs/configuration/database.md is new. The database was undocumented.

Testing

• pnpm run typecheck, pnpm run lint clean
• pnpm test:unit -> 210 passing
• pnpm vitest run --project integration:db -> 31 passing against PostgreSQL 17

Not included

docs/NixOS-options.md needs regenerating from nix/options.nix (I added the
server.database submodule there). It is built by nixosOptionsDoc and I do not
have nix available, so I left the generated file alone rather than hand-editing
build output. Happy for you to regenerate, or I can if you tell me the command
you use.

[pullfrog]

ℹ️ No critical issues — this is a clean, well-documented feature with strong cross-dialect test coverage. One inline nit and a couple of minor observations below.

Reviewed changes

• Atomic owner bootstrap (fix(auth)) — findOrCreateUser now promotes the first user with a single conditional UPDATE guarded by not exists, closing the concurrent-first-login race that could leave an instance ownerless, and HeadplaneDb.dispose() releases the SQLite handle (or drains the pg pool) on shutdown.
• HeadplaneDb bundle (refactor(db)) — createDbClient returns { client, tables, dialect, dispose }; auth.ts and hp-agent.ts unpack it once, so query bodies only change users → tables.users.
• server.database config (feat(config)) — new block for sqlite path / postgres url or host/name/user, ssl_mode, max_connections; omitting it preserves the historical <data_path>/hp_persist.db.
• PostgreSQL backend (feat(db)) — schema.postgres.ts, migrations under drizzle/postgres/, and a partial unique index enforcing a single owner.
• SQLite→Postgres copy helper (feat(db)) — scripts/db-copy.ts with --dry-run / --allow-nonempty, plus contract and copy test suites running against real PostgreSQL 17.

ℹ️ Concurrent first login can surface a 500 on PostgreSQL

The single-owner guarantee is correct: the partial unique index on role = 'owner' makes two owners impossible, and the conditional UPDATE handles the SQLite case. The remaining rough edge is that under a genuinely simultaneous first pair of logins on PostgreSQL, the NOT EXISTS guard evaluates before the other racer has committed, so both UPDATEs attempt to promote — and the index makes the loser throw 23505, which findOrCreateUser does not catch. The result is a one-off failed login for one of the two users, not data corruption; they retry and become a member. This is a once-per-install-lifetime race, so leaving it as-is is defensible, but it is worth a conscious decision.

Technical details

# Losing owner-bootstrap racer errors on PostgreSQL

## Affected sites
- app/server/web/auth.ts — the conditional owner-promotion UPDATE in findOrCreateUser does not tolerate a unique_violation losing the race

## Required outcome
- Decide whether a concurrent-first-login should surface as a 500 (current) or resolve cleanly (e.g. catch 23505 and treat it as "someone else became owner")

## Open questions for the human
- Is failing the losing racer acceptable given the race requires two simultaneous first logins on a brand-new instance?

ℹ️ Nitpicks

• scripts/db-copy.ts --dry-run still runs pgMigrate on the target and creates the tables before short-circuiting, so the "without writing anything" wording in docs/configuration/database.md is slightly inaccurate — it writes schema, just no rows.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

AssertUserRowsMatch only pins users. The HeadplaneTables doc comment (lines 33–36) says it pins "the two schemas" to identical row shapes, but authSessions and hostInfo are only guarded by the contract tests — a drift in either (e.g. authSessions.expires_at inferring string instead of Date) compiles clean and fails only at runtime. Consider adding equivalent Exact assertions for AuthSessionRecord and HostInfoRecord (both already exported from schema.ts), or narrowing the doc comment.