Wire Neon Postgres into Vercel production and preview deployments

[ncolesummers]

Summary

Neon has been added to the Vercel project and is intended to be Loopworks' hosted Postgres provider. The repo already uses Postgres + Drizzle and reads DATABASE_URL, but the deploy-time contract still needs to be made explicit: Vercel environment scoping, pooled vs direct connection usage, Drizzle migrations, preview database branching, and production verification.

This issue is the operational wiring follow-up for ADR 0002 (Vercel stack) and ADR 0004 (Postgres + Drizzle). It is adjacent to #37, but separate: #37 wires portal pages to existing database-backed read paths, while this issue makes sure deployed environments have a real Neon database and safe migration/bootstrap behavior.

Deliverables

• Confirm which Neon/Vercel integration mode is installed: Vercel-managed Neon Postgres or Neon-managed connectable account.
• Verify DATABASE_URL, DATABASE_URL_UNPOOLED, and PG* variables are injected with the intended Vercel environment scopes: Production, Preview, and Development if local vercel env pull should receive them.
• Keep runtime app queries on the pooled DATABASE_URL path and document why src/db/client.ts remains compatible with Neon PgBouncer (prepare: false).
• Update the migration/bootstrap path so Drizzle migrations use DATABASE_URL_UNPOOLED when available, falling back only when appropriate.
• Decide and document how migrations run for production and preview deploys, including whether the Vercel build command should run bun run db:migrate before bun run build.
• Validate automated preview branching behavior if enabled by the Neon integration, including branch creation, branch-specific env injection, migration behavior, and cleanup expectations.
• Add or update docs/ADR coverage for the Neon provider and deployment migration contract, keeping existing ADR 0002 and ADR 0004 as the baseline unless a new proposed ADR is warranted.

Acceptance Criteria

• A Vercel production deployment can connect to Neon using the expected environment variables without falling back to fixture-only behavior.
• A Vercel preview deployment has an isolated and migrated database path, or the issue documents why preview branching is intentionally deferred.
• bun run db:migrate can be run against Neon using the intended direct connection variable and does not rely on the pooled PgBouncer URL for migration/admin work.
• Local development instructions include the vercel env pull .env.local --yes step after Neon provisioning and clarify that .env.local remains untracked.
• bun run db:seed / bun run db:seed:reset remain local-only and continue to refuse non-loopback database URLs; Neon must not be seeded by the demo-data script.
• The implementation includes focused tests or deterministic verification for env selection / migration configuration, plus bun run build if runtime config changes.

Notes

Relevant docs checked while creating this issue:

• Neon/Vercel integration overview: https://neon.com/docs/guides/vercel
• Vercel-managed Neon integration: https://neon.com/docs/guides/vercel-managed-integration
• Neon-managed Vercel integration: https://neon.com/docs/guides/neon-managed-vercel-integration
• Neon connection pooling: https://neon.com/docs/connect/connection-pooling

Do not include secrets in repo files or issue comments. If local validation needs real Vercel env vars, pull them into .env.local only.