Neon local DB (opt-in)
bun run dev always uses a local database: each worktree's own, in Docker or Colima — see Golden Seed (Local DB). This page is for running the stack against a golden-seeded Neon branch instead, with its own commands: bun run db.neon creates the branch, and bun run dev:neon runs against it. Nothing changes for anyone who doesn't run them, and the branch's connection lives in a file on your machine, never in the repo.
Why you might want it
- Always current, always golden. The branch forks from the golden parent, which is reseeded from
devtools/db/seed_data.sql. Nobun run db.seed, no volume that drifts behind newer migrations, nothe or_permissions table does not existwedge in a fresh worktree. - Fixtures the docker volume doesn't have. The golden parent carries the Salesforce and HubSpot
or_integrationrows on vendor 0, so CRM/workflow surfaces are drivable locally — including theplaywright/workflowsCRM specs, which cannot run against a docker DB with no integrations at all. - Zero docker. Useful for onboarding and for cloud/remote sessions.
The trade is a slower boot (~+20s) and per-connection TLS. Interactive DX over raw speed was a deliberate call; E2E CI keeps using the local Postgres for that reason.
What it costs
Neon's per-project branch allowance is an included amount, not a hard cap — extra branches are billed (~$1.50/branch-month), not blocked. One branch per developer is noise next to the preview fleet. Idle branches are archived by Neon automatically (older than 14 days and untouched for 24 hours); re-running the command unarchives yours.
Opt in
You need a NEON_API_KEY with access to the previews Neon project. Export it in your shell profile, then:
bun run db.neonThat ensures a branch named dev-<you> off the golden parent, waits for Neon's asynchronous branch operations to actually finish, writes the pointer to ~/.onramp/db.env (mode 0600), turns off the flags local can't serve (below), and migrates to your worktree's head.
Then bun run dev:neon from any worktree — it prints the branch and host it connected to, and applies any migrations your worktree has that the branch doesn't before it starts. Plain bun run dev keeps using a local database.
One branch per developer, shared by all your worktrees. That is the same model as the old shared docker volume and it is safe under expand-and-contract: expand migrations are additive, so any worktree can migrate the shared branch forward. Use --branch <name> if you genuinely need a separate one.
bun run db.neon --reset # throw away local changes, refork from golden
bun run db.neon list # branch + where the pointer points
bun run db.neon --print-exports # for a shell that doesn't load .env
bun run db.neon rm # delete the branch and the pointerWhat the pointer is
~/.onramp/db.env holds the branch's connection, so bun run dev:neon finds it from any worktree without anything in the worktree's .env. bun run dev never reads it, and removes a copy of it from .env if one is there, since Bun's auto-load would otherwise hand it to every bun run script. bun run db.neon rm deletes the branch and the pointer.
Feature flags
Your branch carries the same flags the docker seed does: every flag on for every vendor, except the few devtools/db/seed-feature-flags.ts leaves off (the reason for each is next to it). db.neon re-applies that after migrating, so a flag your worktree's own migration adds comes up on. A flag you turned off yourself stays off. To keep a flag off everywhere the seed reaches, add it to FLAGS_LEFT_OFF in that file.
Notes
- The app connects through Neon's pooled endpoint and migrations run unpooled — the same split
devtools/db/preview-branch.tsuses, because PgBouncer's transaction pooling is wrong for alembic's session-scoped DDL. - On a worktree that is behind
main, the branch records main migrations the worktree does not have.db.neonborrows those scripts frommainand applies only your worktree's own migrations on top, printing "This worktree is behind main" (seedevtools/db/migration-graft.ts). "…which neither this build's migrations/ nor main contains" means the shared branch carries another worktree's migration; the message names the fix.bun run devalso looks in your other worktrees for such a migration, so it can still apply this worktree's own on top. reseed-neon.tsand the preview sweeper both act onpr-*branches only, so adev-*branch survives reseeds and sweeps.- The read-only SQL tool works out of the box:
or_readonly_user's local-dev password is baked into the golden parent and written into the pointer.