# Workflow: zero-downtime migration onto Neon

## Goal
Move production Postgres to Neon with no write downtime.

## Steps
1. Create the Neon project in the region closest to your app. Region cannot change later, so choose carefully.
2. On the source database, set `wal_level = logical` and restart (schedule this; it is the one disruptive step). Create the publication and replication slot.
3. In Neon, create the subscription pointing at the source. Initial sync copies existing data; then changes stream.
4. Let it catch up and verify: row counts per table, checksums on critical tables, and application-level read checks against Neon.
5. Cut over: put the app in brief read-only or maintenance mode, wait for lag to hit zero, flip `DATABASE_URL` to Neon, re-enable writes.
6. Keep the old database around (stopped, not deleted) for one full cycle as a rollback target.

## Ordering constraints
- Schema first: logical replication copies data, not DDL. Create the schema in Neon before subscribing.
- Tables need primary keys (replica identity) for updates/deletes to replicate.
- Cut over only at zero lag; verify with the subscription status, not by guessing.

## Traps
- Enabling logical replication on the source restarts it: that is your maintenance window, plan it.
- DDL changes during replication do not propagate; freeze schema changes during the migration window.
- Sequence values: verify sequences are set past the max synced value or new inserts collide.

## Verify
App runs on Neon, old source shows no new writes, row counts match, and rollback to the old DB was never needed.