Heroku → Neon
Copy a Heroku Postgres database into Neon with a backup and pg_restore. Neon's Import Data Assistant refuses Heroku, and pg:pull is not the same command in both docs.
Should you make this move?
Both platforms have a case. Compare what you gain with what you give up before scheduling the cutover.
Heroku
- Git-based deploys, buildpacks, and add-ons offer an exceptionally approachable platform
- Managed deployments reduce infrastructure and release-management work
- Pricing and infrastructure control become limiting as applications grow
- Runtime assumptions, platform services, and pricing models shape the architecture
Neon
- Serverless PostgreSQL with branching and scale-to-zero creates excellent developer workflows
- A mature data model and query ecosystem supports serious production workloads
- Platform-specific branching, compute behavior, and pricing require workload-aware design
- Schema design, migration, tuning, and operations require specialist attention
Neon: Serverless PostgreSQL with branching and scale-to-zero creates excellent developer workflows. This removes a major source-side concern: Pricing and infrastructure control become limiting as applications grow.
What you lose: Git-based deploys, buildpacks, and add-ons offer an exceptionally approachable platform. What you inherit: Platform-specific branching, compute behavior, and pricing require workload-aware design.
Jump to a section
Know the shape of the move.
This timeline assumes
- This move is the Postgres database. The app may stay on Heroku. The site already documents Heroku → Railway, PlanetScale → Neon, and Supabase → Neon.
- You can run pg_restore at a version that understands the dump. Heroku warns that an old client fails with an unsupported version in the file header.
- The Neon target is empty enough for pg_restore --clean, or you are restoring into a new project.
- Writes freeze on Heroku for the final copy. Neon says a dump does not change the source.
- You keep the Heroku add-on until the app has run on the Neon URL.
What survives the move.
“Partial” and “manual” are not footnotes. They are work that must be scheduled and verified.
| Item | Outcome | Impact | What happens | Mitigation |
|---|---|---|---|---|
| Tables and rows | partial | critical | Heroku's portable export is heroku pg:backups:capture and heroku pg:backups:download. The file is pg_dump custom format. You load it with pg_restore. Neon also documents heroku pg:pull with the Neon connection string as the target, and tells you to use an unpooled string because that pull runs pg_dump toward Neon. | Take the backup either way. Rehearse pg_restore into a Neon branch or a new project before cutover. |
| pg:pull on Advanced databases | lost | critical | Heroku says pg:push and pg:pull are not supported on Heroku Postgres Advanced. Heroku's pg:pull page describes a pull into a local database that must not already exist. | If the add-on is Advanced, skip pg:pull and use the backup plus pg_restore. |
| Import Data Assistant | lost | high | Neon's assistant is for databases under 10 GB and has a 1 hour limit. Its known limitations say Supabase and Heroku databases are not supported because of unsupported Postgres extensions. The source is only read. | Do not plan this cutover around the assistant. |
| Pooled connection string | partial | critical | Neon says heroku pg:pull should use an unpooled connection string. The assistant docs say a Neon source hostname must not include -pooler. The app can use a different string after the copy. | Restore with the unpooled string. Point the app at the string you tested for runtime. |
| Roles and privileges | manual | critical | Heroku's documented local restore uses pg_restore --verbose --clean --no-acl --no-owner. Those flags skip Heroku roles that do not exist on Neon. | Use those flags. Then grant what the app role needs on Neon. |
| heroku_ext | partial | medium | Heroku says restore errors about the heroku_ext schema can be avoided by running CREATE SCHEMA heroku_ext first. Neon's sample pg:pull log shows pg_restore creating SCHEMA heroku_ext. | Expect that schema. Confirm the app does not need it. |
| Extensions | partial | critical | The assistant refuses Heroku because of unsupported extensions. A dump can still fail in pg_restore for the same reason. Neon does not publish a Heroku extension matrix on the pages above. | Run SELECT extname FROM pg_extension on Heroku and compare with what the Neon project can create. |
| Owners and passwords | manual | critical | The dump does not become the Neon role you connect with. You create the app user on Neon and put that URL in the app. | Do not reuse the Heroku credential string. |
| Followers, forks, and backups | lost | high | Heroku followers and the PGBackups schedule stay on Heroku. pg:backups:restore is how you load a dump into Heroku, and Heroku says that command drops existing schemas. It is not the Neon import. | Create a Neon backup or branch after the restore. Keep the Heroku backup file. |
| Writes during the copy | manual | critical | capture and pg:pull copy a point in time. Heroku does not pause writes for you. A later write on Heroku is missing from Neon. | Freeze app writes for the final capture, or accept a maintenance window. |
| App config | manual | critical | Moving the database does not change DATABASE_URL on the Heroku app, or on whatever host runs the app. | Change the URL only after the restore checks pass, and keep the old URL for rollback. |
| Large-object and version mismatches | partial | high | Neon's sample dump reads large objects, policies, publications, and subscriptions. Heroku says a pg_restore version mismatch stops the restore at the file header. | Match major versions closely enough that pg_restore --version can read the file. Check objects the app actually uses. |
Where each thing goes.
| Source | Destination | Method | Notes |
|---|---|---|---|
| Heroku Postgres add-on | Neon project | manual | Create the project first. Copy the unpooled connection string. |
| pg:backups capture | custom-format dump | automatic | heroku pg:backups:capture then pg:backups:download. |
| Dump file | pg_restore into Neon | transform | Use --verbose --clean --no-acl --no-owner and the unpooled URL. |
| pg:pull to a local name | Local database only, in Heroku's CLI doc | manual | The local database must not already exist. Not supported on Advanced. |
| pg:pull with a Neon URL | Neon database, in Neon's doc | transform | Neon's example uses the Neon URL as the target. Rehearse it. Still take a backup. |
| Extension | Neon extension, if it exists | manual | The assistant's Heroku refusal is the warning. |
| Role and ACL | Neon role you create | manual | --no-acl --no-owner drops the Heroku grants. |
| DATABASE_URL | Neon connection string | manual | Change it after the row checks, not before. |
| PGBackups schedule | No destination | unsupported | Stays on Heroku. Take a Neon branch or backup after restore. |
| Follower | No destination | unsupported | Not part of the dump you restore. |
Make the move recoverable.
Create the source-of-truth backup
Keep a Heroku backup file and the old DATABASE_URL until Neon has been read by the app.
- Record the add-on name, plan, and whether it is Advanced.
- Record Postgres version and the extension list.
- Run heroku pg:backups:capture and heroku pg:backups:download.
- Store the dump outside the laptop that will run pg_restore.
- Leave the Heroku add-on attached.
Proof to capture: A dump file, the extension list, and the current DATABASE_URL written down where you can put it back.
Restore
Load a Heroku custom-format dump into an empty Neon database.
- Create a Neon project and copy the unpooled connection string.
- If you are on Advanced, do not use pg:pull.
- Run pg_restore --verbose --clean --no-acl --no-owner against that string.
- If the client rejects the file header, upgrade pg_restore to a version that matches the dump.
Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.
Cutover URL
Make one database the writer.
- Freeze writes on the app.
- Capture and restore again, or restore the delta you measured.
- Point DATABASE_URL at Neon.
- Keep the Heroku URL until the checks pass.
Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.
The things most likely to hurt.
These are operating limits. Treat every “Stop if” condition as a blocked migration, not a suggestion.
The assistant is the plan
Someone starts the Import Data Assistant with a Heroku URL.
- Consequence
- Neon says Heroku is unsupported there, and a 10 GB or 1 hour limit would still not make it the procedure.
- Mitigation
- Use the backup and pg_restore.
Stop if: The only runbook is the assistant.
pg:pull against Advanced, or against a pooled string
The command is the one in Neon's Heroku page, and the add-on is Advanced or the host contains -pooler.
- Consequence
- Heroku says pg:pull is unsupported on Advanced. Neon says the pull should use an unpooled string.
- Mitigation
- Read the plan name. Use the unpooled host for the restore.
Stop if: You cannot say which command you are running and why both docs allow it.
Writes continue on Heroku
The app is up while capture or pg:pull runs.
- Consequence
- Neon is missing rows that Heroku accepted.
- Mitigation
- Freeze writes for the final copy and compare counts.
Stop if: You cannot pause the writer.
Do the work in this order.
- Days 1 to 2 · inventory
Plan and extensions
3 to 6 hours active1 to 2 days elapsedNone waiting- Note Advanced versus not, version, and extensions.
- Pick pg_restore rather than the assistant.
Depends on: Heroku and Neon access
Stop / go checkpointCapture a backup?
Go when: The restore command is chosen and the extension list is written down.
Stop when: The plan name or the extension list is unknown.
- Days 2 to 3 · backup
Capture
1 to 4 hours active1 day elapsedBackup creation waiting- Run pg:backups:capture and download.
- Store the file off the restore machine.
Depends on: Inventory
Stop / go checkpointRestore a rehearsal?
Go when: The dump file opens with a current pg_restore.
Stop when: The file header is an unsupported version.
- Days 3 to 6 · pilot
Restore into Neon
4 to 12 hours active2 to 4 days elapsedRestore runtime waiting- pg_restore with --no-acl --no-owner into the unpooled URL.
- Compare table counts and a few known rows.
- Create the app role.
Depends on: Dump file
Stop / go checkpointRehearse the freeze?
Go when: Counts match the Heroku database you captured.
Stop when: An extension failed or a table is missing.
- Days 6 to 8 · cutover
Freeze and switch
2 to 6 hours active1 to 2 days elapsedFinal capture waiting- Stop writes.
- Capture and restore again.
- Change DATABASE_URL.
Depends on: A rehearsal restore
Stop / go checkpointLet writes hit Neon?
Go when: The final counts match and the app connects.
Stop when: Heroku still accepts writes.
- Days 8 to 12 · observe
Keep the add-on
2 to 4 hours active2 to 4 days elapsedApp traffic waiting- Watch the app on the Neon URL.
- Keep the dump and the Heroku add-on.
- Take a Neon branch or backup of the restored data.
Depends on: URL switched
Stop / go checkpointDetach Heroku Postgres?
Go when: You can still put the old URL back.
Stop when: The dump or the add-on is already gone.
Cut over with a way back.
Cutover
Make Neon the only writer, with a Heroku backup still in hand.
- Freeze writes.
- Capture and download a final dump.
- pg_restore it into Neon with the unpooled URL and --no-acl --no-owner.
- Compare counts.
- Point the app at Neon.
- Leave the Heroku add-on attached.
Proof to capture: The app reads and writes Neon, and the Heroku dump from the freeze still exists.
Rollback
Point the app back at Heroku Postgres.
- Stop writes on Neon.
- Put the saved Heroku DATABASE_URL back.
- Decide whether any Neon-only rows must be replayed. The dump will not contain them.
- Confirm the app is on Heroku.
- Keep the Neon project for the next attempt.
Proof to capture: The app uses the Heroku URL and Heroku still has the pre-cutover data plus whatever you replayed.
- pg_restore stops on an extension or the file header
- Counts do not match
- The app was given a pooled URL for the restore
- Writes landed on Heroku after the capture
- The Import Data Assistant was used instead of the dump
Prove the migration worked.
Every blocking check must pass. Capture the evidence before cleanup begins.
| Pass | ID | Check | Method | Expected result | Evidence |
|---|---|---|---|---|---|
V-01Blocking | Advanced or not | Read the add-on plan before choosing pg:pull. | Advanced uses the backup path only. | Plan note. | |
V-02Blocking | File restores | pg_restore --version against the downloaded backup. | The client accepts the header. | Restore log. | |
V-03Blocking | Unpooled host | Read the hostname used for pg_restore. | It has no -pooler suffix. | Connection note, with the password redacted. | |
V-04Blocking | Tables | Compare table lists and row counts with Heroku. | No unexplained gap. | Count sheet. | |
V-05Blocking | extname list | Compare Heroku's extension list with what Neon created. | Each required extension exists, or the app no longer calls it. | Extension list. | |
V-06Blocking | App role | Connect as the app role and read and write one row. | The role works without Heroku ownership. | Query log. | |
V-07Blocking | No late writes | Compare a last Heroku id with Neon after the freeze. | They match. | Id check. | |
V-08Blocking | Old URL | Confirm the Heroku URL and the dump are still available. | You can switch back. | Config note. |
Remove the scaffolding safely.
Safe after: The app has run on Neon through a write cycle you care about, and the Heroku add-on still exists.
- Store the dump with the migration notes.
- Take a Neon branch or backup of the restored database.
- Remove heroku_ext from the app's assumptions if nothing uses it.
- Detach the Heroku add-on only when rollback no longer needs it.
- Update the runbook so nobody starts the Import Data Assistant for this database.
Verify against the primary material.
Platform behavior changes. Check these sources and the review dates above before executing a production migration.
- Neon: migrate from HerokuAccessed 2026-11-02
- Neon: Import Data AssistantAccessed 2026-11-02
- Heroku: import and export PostgresAccessed 2026-11-02
- Heroku: managing Postgres with the CLIAccessed 2026-11-02
- Neon: migration methodsAccessed 2026-11-02