Skip to content

Migration · By Rivtor · Updated

Migrate from Neon to PostgreSQL: export, restore and cutover

Plan a Neon PostgreSQL move by separating database data from branch, connection and authentication workflows. Check destination version, extensions, privileges and a supported import path, rehearse a restore, then schedule a write-consistent cutover.

Compare Rivtor plans for your workload →

Inventory the database contract

Record PostgreSQL version, database size, extensions, roles, schema ownership and application connection method. Inspect whether the application depends on Neon branching, an HTTP driver or a pooled endpoint. A normal PostgreSQL destination may require a different driver or operating workflow.

Keep source and destination credentials private. Do not paste connection URLs into a migration report or commands that will be stored in shared logs. Record variable names and the method for obtaining authorized access.

Rehearse export and restore

Use the source provider’s current export guidance and PostgreSQL tooling compatible with the source server. Restore into an empty disposable database with the destination’s actual privileges. Confirm extensions and ownership behaviour before importing valuable data.

Start from a direct Neon connection for the export, then inspect the custom-format archive before restoring it. The example assumes private libpq service entries named neon_source and staging_destination, each with authorized access and appropriate TLS settings. It is for staging, where the target already exists and is empty.

pg_dump --dbname='service=neon_source' --format=custom --file=neon-staging.dump
pg_restore --list neon-staging.dump
pg_restore --dbname='service=staging_destination' --exit-on-error --no-owner --no-privileges neon-staging.dump

--no-owner and --no-privileges skip source ownership and grants. Review and apply the destination's least-privilege grants separately. Protect the dump itself as private data, even if the command does not print credentials. If your target is Rivtor, confirm the supported database access path below before running pg_restore.

CheckWhy it matters
Tables and countsDetects missing or incomplete data
Constraints and indexesPreserves application guarantees and query paths
SequencesAvoids collisions on later inserts
Extensions and functionsDetects unsupported dependencies
Application driverConfirms the destination protocol and pooling contract

Do not assume pg_dump and pg_restore automatically recreate provider-specific services. Logical data migration and platform feature replacement are separate concerns.

Confirm destination connectivity

On Rivtor, review PostgreSQL access and the supported operator/import mechanism. A private application database address is not necessarily reachable directly from your workstation. Confirm a documented route and sufficient import privileges before the production cutover is scheduled.

Update application configuration according to the selected driver. Test actual queries, migrations and pool behaviour using the destination. A SELECT 1 result does not establish compatibility with the application’s schema.

Control the final write boundary

Define when API and worker writes stop, when the final export occurs and which checks allow traffic to resume. Keep the source available until destination acceptance completes. If destination writes have begun, switching back requires a data reconciliation plan.

Record the state of any preview or branch environments too. Moving the primary database without changing branch-specific URLs can leave test or scheduled workloads writing to the retired system unnoticed.

References