Migrating to Heroku Postgres Advanced (Limited GA)

Last updated May 18, 2026

Heroku Postgres Advanced is in limited general availability. To start creating and using Advanced databases, open a ticket with Heroku Support to request access. Subscribe to our changelog to stay informed of when Heroku Postgres Advanced is generally available.

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.

If you’re new to Heroku Postgres Advanced, get started with our tutorial Getting Started with Heroku Postgres Advanced.

To change plans between Essential and classic Postgres database tiers, see Changing the Plan or Infrastructure of a Heroku Postgres Database.

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 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 aren’t supported.

Overview

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

  1. Provision an Advanced database
  2. Prepare the migration
  3. Enter maintenance mode
  4. Start the migration
  5. Promote your database
  6. Exit maintenance mode
  7. Destroy your old classic database

Step 1: Provision an Advanced Database

First, provision an Advanced database on your app if you don’t have one. You can run the data:pg:create command and follow the interactive prompts, or provision through flags. If you need follower pools, create them in the interactive command or with the --followers flag, or add them after provisioning with data:pg:update.

See Choosing the Right Heroku Postgres Plan for which Advanced plan level fits the database size of the source database you’re migrating.

After provisioning, you can see the database on your app with heroku addons:

$ heroku addons -a example-app
Add-on                                            Plan       Price   Max price State
───────────────────────────────────────────────── ────────── ─────── ───────── ───────
heroku-postgresql (postgresql-circular-11223)     advanced   metered metered   created
  └─ as DATABASE

Step 2: Prepare the Migration on Your Database

Next, start the migration process by running the 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 will be successful. You’ll 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’ll receive an email with the error details.

Your source database is still available while Heroku sets up the necessary tooling for the migration. After the migration tooling is set up, you have 24 hours to begin the migration. The migration will put 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 the destination Postgres Advanced database to migrate to, or create a new Advanced database. You can use an existing Advanced database as your destination database or create an Advanced database.

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

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

  3. 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.

? 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 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 3: Enter Maintenance Mode to Prevent Database Writes

Maintenance mode doesn’t automatically scale down dynos. Scale down web and any non-web dynos (for example, heroku ps:scale worker=0) to ensure that no connections are writing data to the database.

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 4: 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 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 data:pg:migrate command and select Start a migration from the interactive prompts and select the configuration migration to run before confirming:

$ 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

Your source database is unavailable from the time the migration starts until the migration is complete. If there are any issues that prevent the migration, we terminate the process and your source database is available again. The source database can be offline for several hours during the migration. You’ll receive an email when the task is complete. You can’t cancel the migration after starting it.

You can run 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 5: Promote Your Target Database

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

After verifying the data, promote your target 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 6: Exit Maintenance Mode

To resume normal application 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 7: Destroy Your Source Database

After the migration is completed 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