Last updated July 06, 2026

Heroku Postgres Advanced (Limited GA) 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.

Considerations

• The migration requires some downtime on the source database you’re migrating. The length of downtime depends on the migration method and the size of your database.
• The migration doesn’t automatically recreate follower databases. Prescale the follower pools of your Advanced database and prepare your app to use it or 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.

Migration Methods

Heroku supports two methods 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.

Streaming Migration

The Streaming migration method performs an initial data copy from your source database to the destination database. Then, this method streams any changes to the destination until you run the migration.

When you run the migration, Heroku waits until the streaming lag is lower than 5 seconds and then restricts access to your source database while the remaining changes replicate to the destination database. This method minimizes the database downtime it takes for replication to fully catch up and stream any pending latest changes.

The heroku data:pg:migrate command shows the streaming lag after the migration starts:

=== Configured Migrations

  Source Database             Destination Database            Status
 ───────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Migrating: 0.2s lag

Overview

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 databases to migrate to and from.

This command prepares the migration process from a source classic database to an Advanced database. The preparation step runs various checks to make sure the migration succeeds. 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 due to errors, you can’t start the migration until you resolve the errors and run the preparation step again. You receive an email with the error details.

Your source database is still 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 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 database migration
     - Start a migration (no ready migrations on ⬢ example-app)
     - Cancel a migration (no ready migrations on ⬢ example-app)
     ──────────────
     Exit
   
   ? Select the source database: (Use arrow keys)
   ❯ ⛁postgresql-clean-29349 as DATABASE
     ⛁postgresql-sharp-38258 as HEROKU_POSTGRESQL_PURPLE
     ⛁postgresql-clean-10367 as HEROKU_POSTGRESQL_YELLOW
     ──────────────
     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 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.
   · Streaming: Replicates changes from the source database to the destination database continuously until you start the migration. Requires minimal downtime. Best for larger databases or when you need near-zero downtime.
   
   ? Select the migration method: (Use arrow keys)
   ❯ Snapshot
     Streaming
     ──────────────
     Go back
   

   See Migration Methods for details.

4. Then, 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
   === Configured Migrations
   
     Source Database             Destination Database            Status
    ───────────────────────────────────────────────────────────────────────
     ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Preparing
   

You can run heroku:data:pg:migrate to see the status of the migration preparation. It can take up to 30 minutes to prepare a migration.

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

Migrate existing classic Heroku Postgres databases to Advanced databases
Press Ctrl+C to cancel

=== Configured Migrations

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

If you see Error - Check Email in the Status field, there was an issue during the preparation step. Check your email for the necessary steps to fix the errors before running the preparation again.

Step 2: Enter Maintenance Mode to Prevent Database Writes

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

When the migration preparation is complete, you get an email that your database is ready to migrate. You can also run the heroku:data:pg:migrate command and see Ready in the migration status.

$ 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            Status
 ───────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Ready

To start the migration, run the heroku data:pg:migrate command and select Start a migration from the interactive prompts. Then, select any configured migrations that are ready to run, and confirm:

$ 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            Status
 ───────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Ready

? What do you want to do? (Use arrow keys)
  Configure a database migration
❯ Start a migration
  Cancel a migration
  ──────────────
  Exit

? Select the migration to start: (Use arrow keys)
❯ From ⛁ postgresql-clean-29349 to ⛁ postgresql-circular-11223
  ──────────────
  Go back

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.
You can't cancel the migration after starting it.

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

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

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

After starting a migration, your source classic Postgres database becomes unavailable depending on the migration method you select until the process completes.

If there are any issues that prevent the migration, Heroku stops the migration process and your source database is available again. You receive an email when the task is complete. You can’t cancel the migration after starting it.

You can run heroku:data:pg:migrate to see the status of the migration. When the migration is complete, you see Completed in the migration status.

$ 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            Status
 ───────────────────────────────────────────────────────────────────────
  ⛁ postgresql-clean-29349   ⛁ postgresql-circular-11223   Completed

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 DATABASE_URL with heroku pg:promote:

$ heroku pg:promote postgresql-circular-11223 -a example-app
Ensuring an alternate alias for existing ⛁ DATABASE_URL... HEROKU_POSTGRESQL_ROSE_URL
Promoting ⛁ postgresql-circular-11223 to ⛁ DATABASE_URL on ⬢ example-app... done
Checking release phase... pg:promote succeeded. It is safe to ignore the failed Detach DATABASE (@ref:postgresql-clean-29349) release.

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, you can 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

Additional Reading

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