Last updated November 12, 2026

Heroku Postgres Advanced is the newest Heroku Postgres database tier on new and improved infrastructure, and offers flexible customization options to fit your database needs. Advanced databases are on different infrastructure than classic Standard, Premium, Private, and Shield-tier databases. This article walks through how to migrate from a classic Postgres database to an Advanced database.

To test your migration from a classic Heroku Postgres plan to Heroku Postgres Advanced, see Testing Heroku Postgres Advanced Migrations.

Considerations

• The migration requires some downtime on the source database you’re migrating. The length of downtime depends on the size of your database.
• The migration doesn’t recreate follower databases automatically. Before migrating, configure follower pools on your Advanced database and prepare your app to use them. Or, you can automatically fall back to use the leader pool.
• Some features on classic Postgres aren’t supported on Advanced databases when you migrate. See the feature parity table on what features Advanced databases don’t support.
• You can upgrade your Postgres version as part of the migration by creating a destination Advanced database on a higher Postgres version than your source. You can upgrade up to three major versions in a single migration.
• After your migration completes, you must promote the destination database and re-attach the custom credentials in your Advanced database to the apps where you use them. The migration process doesn’t automatically update your app’s attachments from your classic database to the Advanced database.

Migration Methods

Heroku supports the snapshot method for migrating a classic Heroku Postgres database to an Advanced database.

Snapshot Migration

The snapshot migration copies the data from your source database to the destination database.

When you run the migration, Heroku restricts access to your source database while the full data copy migration completes. The source database can be offline for several hours during the migration, depending on its size.

A snapshot migration migration has these statuses:

Manage Database Migrations

Check the Details of a Migration

Run heroku data:pg:migrate to see the status and details of all configured migrations for an app. The command lists each migration with its source database, destination database, migration method, and status. Select Refresh from the interactive prompts to reload the status.

For a description of each status for a snapshot migration, see Snapshot Migration.

Start a Migration

After you configure a migration, you can start running it when its status shows Migration is ready. Check your email for details.. Make sure your app is in maintenance mode and no dynos are writing to the source database before starting.

If you don’t start the migration within 24 hours of the preparation completing, Heroku automatically cancels it, deprovisions the destination database, and restores source database connections. You receive a Migration failed email indicating that the migration timed out, with instructions to retry.

See Step 3: Run the Migration on Your Database for details on starting a migration via the heroku data:pg:migrate interactive prompts.

Cancel a Migration

You can cancel a migration at any point before it begins promoting. If the migration was running, canceling restores connections to your source database and brings it back online. If you didn’t start the migration, canceling has no impact on your source database.

To cancel a migration:

1. Run heroku data:pg:migrate.

2. Select Manage migration from ... for the migration to manage.

   $ heroku data:pg:migrate -a example-app
   
   ...
   
   ? What do you want to do? (Use arrow keys)
   ❯ Manage migration from ⛁ postgresql-clean-29349 to ⛁ postgresql-circular-11223
     Configure a new database migration
     ──────────────
     Refresh
     Exit
   

3. Select Cancel from the migration details.

   === Migration Details
   
   
   Source:        ⛁ postgresql-clean-29349 (DATABASE) - Postgres 18.6 - Available
   Destination:   ⛁ postgresql-circular-11223 (HEROKU_POSTGRESQL_BLUE) - Postgres 18.4 - Migrating
   Method:        Snapshot
   Configured at: 2026-11-03 15:41 UTC
   Status:        Migration is ready. Check your email for details.
   
   
   ? What do you want to do?
     Refresh
     Start
     ❯ Cancel
     ──────────────
     Go back
   

4. Select Confirm to cancel the migration.

   After canceling, you must create a new migration configuration and wait for the migration tooling to finish preparing to
   migrate ⛁ postgresql-clean-29349 again.
   
   
   ? Confirm to cancel migration: (Use arrow keys)
   ❯ Confirm
     Go back
   

Step-by-Step Migration

The steps to migrate a classic database to an Advanced database are:

1. Prepare and select the migration method
2. Enter maintenance mode
3. Start the migration
4. Promote your database
5. Exit maintenance mode
6. Destroy your old classic database

You can migrate your classic Postgres database to an existing Advanced database, or create an Advanced database as the migration destination database directly during the migration process. See Choosing the Right Heroku Postgres Plan for which Advanced plan level fits the database size of the source database you’re migrating.

Step 1: Prepare the Migration on Your Database

Start the migration process by running the heroku:data:pg:migrate command and follow the interactive prompts to configure the source and destination databases.

This command prepares the migration process from a source classic database to an Advanced database. The preparation step runs various checks to make sure that your database schema and configuration are compatible with the migration process. You receive an email when the setup process is complete and your database is ready to migrate. If your database doesn’t pass the checks, you receive an email with the error details. You must resolve the errors and prepare a new migration.

Your source database remains available while Heroku sets up the necessary tooling for the migration. After setting up the migration tooling, you have 24 hours to begin the migration. The migration puts your database offline until it’s complete.

To start the migration preparation, run heroku data:pg:migrate:

1. Select Configure a database migration, then Select the source database, and select the classic Postgres database to migrate from.

   $ heroku data:pg:migrate -a example-app
   
   Migrate existing classic Heroku Postgres databases to Advanced databases
   Press Ctrl+C to cancel
   
   === Configured Migrations
   
   You haven't configured any migrations for ⬢ example-app yet.
   
   ? What do you want to do? (Use arrow keys)
     Configure a new database migration
     ──────────────
   ❯ Refresh
     Exit
   
   ? Select the source database: (Use arrow keys)
   ❯ ⛁ postgresql-clean-29349 v18.6 as DATABASE as DATABASE
     ──────────────
     Go back
   
   

2. Next, select an existing destination Postgres Advanced database to migrate to, or create an Advanced database from the migration interactive prompts.

   Preparing the migration deletes all the content on the destination database. Make sure to select an empty Advanced database to migrate to, or create an Advanced database.

   ? Select the destination database: (Use arrow keys)
   ❯ ⛁postgresql-circular-11223 v18.4 as HEROKU_POSTGRESQL_BLUE
     ──────────────
     Create a new Advanced database
     Go back
   
   

3. Select the method to use for your database migration:

   Migration Methods:
   · Snapshot: Copies the data from the source database to the destination database.
     Requires downtime on the source database depending on the size.
     Best for smaller databases or when a maintenance window is acceptable.
   
   ? Select the migration method: (Use arrow keys)
   ❯ Snapshot
     ──────────────
     Go back
   

4. Then, select Confirm to configure the migration:

   By continuing, we prepare the necessary steps for the migration.
   Your source database is available while we prepare the migration.
   You'll receive an email when the preparation is complete or if there's an error.
   You have 24 hours to begin the migration after the preparation is complete.
   Your source database will be unavailable during the migration.
   Preparing the migration deletes all the data on the destination database ⛁ postgresql-circular-11223.
   
   ? Confirm migration configuration: (Use arrow keys)
   > Confirm
     Go back
   
   ? Confirm migration configuration: Confirm
   
   Configuring migration... done
   === Migration Details
   
   Source:        ⛁ postgresql-clean-29349 (DATABASE) - Postgres 18.6 - Available
   Destination:   ⛁ postgresql-circular-11223 (HEROKU_POSTGRESQL_BLUE) - Postgres 18.4 - Available
   Method:        Snapshot
   Configured at: 2026-11-03 15:41 UTC
   Status:        Preparing
   
   ...
   

Run heroku:data:pg:migrate to check the status of the migration preparation. It can take around 30 minutes to prepare a migration.

Step 2: Enter Maintenance Mode

When the migration preparation is complete, you receive an email that your database is ready to migrate. You can also run heroku data:pg:migrate and check that the status shows Migration is ready. Check your email for details.:

heroku data:pg:migrate -a example-app

Migrate an existing classic Postgres database to an Advanced database
Press Ctrl+C to cancel

=== Configured Migrations

  Source Database             Destination Database           Method     Status
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223    Snapshot   Migration is ready. Check your email for details.

Before starting the migration, put your app into maintenance mode or read-only mode so you don’t write to the source database when the migration is complete:

$ heroku maintenance:on -a example-app
Enabling maintenance mode for ⬢ example-app... done

Step 3: Run the Migration on Your Database

To start the migration, run the heroku data:pg:migrate command, select the migration to manage from the list, and select Start from the migration actions:

$ heroku data:pg:migrate -a example-app

=== Configured Migrations

  Source Database             Destination Database            Status
 ───────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Ready

? What do you want to do? (Use arrow keys)
❯ Manage migration from ⛁ postgresql-clean-29349 to ⛁ postgresql-circular-11223
  Configure a new database migration
  ──────────────
  Refresh
  Exit

? What do you want to do? Manage migration from ⛁ postgresql-clean-29349 to ⛁ postgresql-circular-11223

=== Migration Details

Source:        ⛁ postgresql-clean-29349 (DATABASE) - Postgres 18.6 - Available
Destination:   ⛁ postgresql-circular-11223 (HEROKU_POSTGRESQL_BLUE) - Postgres 18.4 - Migrating
Method:        Snapshot
Configured at: 2026-11-03 15:41 UTC
Status:        Migration is ready. Check your email for details.

? What do you want to do? (Use arrow keys)
  Refresh
❯ Start
  Cancel
  ──────────────
  Go back

Then, select Confirm to start the migration:

? What do you want to do? Start

Your database ⛁ postgresql-clean-29349 will be unavailable after starting the migration until the migration is complete.
If there are any issues during the migration, we end the migration and make the source database available again.
The database ⛁ postgresql-clean-29349 can be offline for several hours during the migration.
You'll receive an email when the migration is complete.

? Confirm to start migration: (Use arrow keys)
❯ Confirm
  Go back

Starting migration of ⛁ postgresql-clean-29349 to ⛁ postgresql-circular-11223... done

After starting a snapshot migration, your source classic Postgres database becomes unavailable until the process completes.

If the migration fails, Heroku stops it and restores access to your source database. You receive an email when the migration completes. You can cancel the migration at any point before it begins promoting the destination database.

When the migration completes, its status shows Migration completed successfully. Check your email for details..

Step 4: Promote Your Destination Database

Verify the data on the newly migrated Advanced database to confirm the migration was successful.

After verifying the data, promote your destination Advanced database to use your app’s primary DATABASE attachment with heroku addons:attach.

First, create an alternate alias for your previous classic database. In this example, postgresql-clean-29349 is our source database for the migration:

$ heroku addons:attach postgresql-clean-29349 --as OLD_DATABASE -a example-app
Attaching ⛁ postgresql-clean-29349 as OLD_DATABASE to ⬢ example-app... done
Setting OLD_DATABASE config vars and restarting ⬢ example-app... done, v1047

Then, attach the new Advanced database with the primary DATABASE alias. In this example, postgresql-circular-11223 is our target database for the migration:

$ heroku addons:attach postgresql-circular-11223 --as DATABASE -a example-app
Attaching ⛁ postgresql-circular-11223 as DATABASE to ⬢ example-app... !
 ›   Warning: Adding DATABASE to app example-app would overwrite existing vars DATABASE_URL.

✔ To proceed, type example-app or re-run this command with --confirm example-app example-app
Attaching ⛁ postgresql-circular-11223 as DATABASE to ⬢ example-app... done
Setting DATABASE config vars and restarting ⬢ example-app... done, v1049

Step 5: Exit Maintenance Mode

To resume normal app operation, scale any non-web dynos back to their original levels (for example, heroku ps:scale worker=1).

Turn off maintenance mode:

$ heroku maintenance:off -a example-app
Disabling maintenance mode for ⬢ example-app... done

Step 6: Destroy Your Source Database

After the migration is complete and the new Advanced database works as expected with your app, destroy your old source classic database with heroku addons:destroy:

$ heroku addons:destroy postgresql-clean-29349 -a example-app
 ›   Warning: Destructive Action
 ›   This command will affect the app ⬢ example-app

✔ To proceed, type example-app or re-run this command with --confirm example-app example-app
Destroying postgresql-clean-29349 on ⬢ example-app... done

Troubleshooting

If you run into issues migrating your database, check your email for details on how to resolve. You can also see the Heroku Postgres Advanced Migration Failure Troubleshooting Guide for common migration failures and how to fix them.

Limitations

• Follower databases: You can only configure migrations from a leader database. You can’t use follower databases as a migration source. To test a migration without impacting your production database, see Testing Migrations from Classic Heroku Postgres to Heroku Postgres Advanced.
• Data connectors: Databases with active data connectors can’t migrate.
• Version restrictions: The destination Advanced database must be on the same or a higher Postgres version than the source. Migrations support upgrading up to three major versions. You can’t migrate to a destination database running a lower Postgres version than the source.
• Reserved credential names: Advanced-tier databases reserve certain credential names for platform use. If any credentials on your source database use reserved names, destroy them and recreate them with different names before preparing the migration. You receive an email with the affected credential names if the migration preparation checks detect any reserved credential names in your source database.
• Essential databases: This migration process doesn’t support Essential-tier databases as the source database.
• Dataclips: Dataclips associated with your source database don’t transfer to the Advanced database. You must recreate or re-attach them after migration. See Dataclip Recovery for details.
• Temporal constraints: Primary key, unique, and foreign key constraints declared WITHOUT OVERLAPS or PERIOD in Postgres 18 can’t migrate. See our troubleshooting guide on how to resolve.
• Database and role settings: Settings such as TimeZone, DateStyle, and IntervalStyle that you set for your database or roles don’t migrate. See our troubleshooting guide on how to resolve.
• Replica identity set to an index: A replica identity set with REPLICA IDENTITY USING INDEX doesn’t migrate. See our troubleshooting guide on how to resolve.
• Comments on indexes and constraints: Comments on indexes and constraints don’t migrate. See our troubleshooting guide on how to resolve.
• Event triggers: Advanced databases don’t support creating event triggers. If your source database uses them, plan another way to get the same behavior. See our troubleshooting guide on how to resolve.

Additional Reading

• Heroku Postgres Advanced category
• Getting Started with Heroku Postgres Advanced