Workflow: zero-downtime migration onto Neon with logical replication

Workflow: zero-downtime migration onto Neon with logical replication

TL;DR

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

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Steps

1. Create the Neon project in the region closest to your app. Region cannot change later, so choose carefully.

   Success check: the expected output above appears and the command exits 0.

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.

   Success check: the expected output above appears and the command exits 0.

3. In Neon, create the subscription pointing at the source. Initial sync copies existing data; then changes stream.

   Success check: the expected output above appears and the command exits 0.

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.

   Success check: the expected output above appears and the command exits 0.

6. Keep the old database around (stopped, not deleted) for one full cycle as a rollback target.

Compatibility

Tool: Neon. The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Workflow: zero-downtime migration onto Neon

Goal

Move production Postgres to Neon with no write downtime.

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

Neon's logical replication guide (verified live 2026-09-26): when replicating to Neon, enable logical replication on the source; publication/slot on publisher, subscription on subscriber; schema/DDL considerations documented in the logical replication guides.