v1.7: Postgres migration (WIP — tasks 1-4 done, 5 has open defects)

[NeverEndingCode]

Status: in progress — do not merge, do not run against production data

Tasks 1–4 are complete and reviewed. Task 5 is built but has four unfixed defects. Tasks 6–8 are not started, which means the migrator itself does not exist yet.

Task	State
1. Async db interface (292 call sites)	✅ complete, review clean
2. Facade + SQLite driver + schema split	✅ complete, 1 fix round
3. Postgres test harness + CI matrix	✅ complete, review clean
4. Postgres schema + driver	✅ complete, 1 fix round
5. identities auth split	⚠️ built, 4 Important findings unfixed
6. The SQLite → Postgres migrator	❌ not started
7. Auto-migrate on boot	❌ not started
8. Deployment config + docs	❌ not started

Current suite: SQLite 470/470, Postgres 467/470 + 3 legitimate skips, both backends green in CI matrix.

Documents

• Design spec: docs/superpowers/specs/2026-08-01-postgres-supertokens-design.md
• Implementation plan: docs/superpowers/plans/2026-08-01-v1.7-postgres.md
• Backup / cutover / rollback runbook: docs/postgres-migration-runbook.md — the backup half is valid today

Task 5's open defects

All four are in the migration paths, not the application layer. The reviewer confirmed the username-collision retry logic, the provider subquery, and shared.js reuse are all correct.

1. upsertUser writes users and identities non-atomically. A partial write leaves a users row with no identity. Every subsequent login then misses the identity lookup, retries INSERT INTO users on the same primary key, gets SQLSTATE 23505, misdiagnoses it as a username collision, and 500s — permanently, with no recovery path. This is the exact lockout class the retry logic exists to prevent.
2. SQLite's foreign_key_check runs after COMMIT. A violation crashes one boot with the rebuild already durably committed; on restart the guard sees no provider column, returns early, and never checks again. Orphaned saves survive. The documented rebuild procedure runs the check inside the transaction so it can roll back.
3. CREATE TABLE identities sits inside SQLite's guarded rebuild but outside Postgres's guard. On SQLite the table exists only as a side-effect of the users rebuild, so a database in a partially-migrated state boots clean and throws on first login. The Postgres path self-heals from the identical state.
4. The base users DDL still declares provider/provider_id, which the migration then removes on every boot. users_new hardcodes a duplicate column list, so the next guardedAddColumn added in a future release would exist on users but be absent from users_new — silently losing that column's data on upgrade.

Landmines caught and fixed along the way

Found during implementation, not anticipated by the plan:

• await x().prop parses as await (x().prop) — reads a property off a Promise, yields undefined rather than throwing. ~25 instances.
• An ambient DATABASE_URL redirected the entire SQLite test run at a live database, writing to it and running DROP INDEX against it while reporting green — voiding the dual-backend guarantee with no signal. tests/helpers/backend.js is now the only writer of that variable.
• A static import hoisting above process.env.DB_PATH, booting the driver against the on-disk database mid-test.
• pg returns BIGINT as a string by default; every epoch-ms column here is BIGINT.
• Postgres folds unquoted identifiers to lowercase, so listLeaderboard's AS userId would have returned userid and every rungsClaimed would read undefined on a leaderboard that still rendered.

Environment note

The dev machine has no docker binary — Podman 5.8.4 only. The test harness auto-detects the Podman socket and disables Ryuk (which cannot get the privileges it needs when rootless), while leaving the CI service-container path untouched. Task 8's docker compose verification steps will need Podman equivalents locally; the shipped docker-compose.yml remains correct for Unraid.

🤖 Generated with Claude Code