Skip to main content
We offer complimentary hands-on migration assistance for Heroku migrations on a case-by-case basis. Reach out to learn more.
Heroku notably does not support logical replication, which has left many of its customers on outdated Postgres and without a convenient migration path to another provider. PlanetScale has tested a wide variety of plausible strategies and Bucardo’s trigger-based asynchronous replication has proven to be the most reliable option with the least downtime. There may be a variation of this strategy that uses the ff-seq.sh tool from our logical replication strategy that can provide a true zero-downtime exit strategy from Heroku. Get in touch if this is a requirement for you.

​
Setup, copy, and replication

  1. Create a PlanetScale Postgres database.
    • Choose a size with similar CPU and RAM as what you run in Heroku. Don’t stress as resizing in PlanetScale is an online operation.
    • Ensure you have at least twice the storage space as Heroku reports using. (Postgres disk usage can vary wildly and Bucardo is not very space-efficient. It is not uncommon for a database to use 50% more or less space on PlanetScale than on Heroku. Automatic vacuuming will return disk usage to its true size over time.) Either choose a PlanetScale Metal size with enough space or visit the Storage tab of the Cluster Configuration page to proactively adjust how much space is available on your network-attached storage volumes.
  2. Launch an EC2 instance where you’ll run Bucardo. It must run Linux and have network connectivity to both Heroku and PlanetScale. We recommend something at least medium-sized e.g. t3a.medium.
  3. Install and configure Bucardo there: 
    sh install-bucardo.sh
  4. Export two environment variables there:
    • HEROKU: URL-formatted Heroku Postgres connection information for the source database.
    • PLANETSCALE: Space-delimited PlanetScale Postgres connection information for the postgres role (as shown on the Connect page for your database) for the target database.
  5. Ensure via heroku pg:locks there are no VACUUM queries with (to prevent wraparound) running as these will block the creation of triggers in the next step which could in turn block the execution of your application’s queries. (If you’re following this guide but aren’t actually on Heroku, use SELECT * FROM pg_stat_activity WHERE query LIKE '% (to prevent wraparound)'; instead.)
  6. Configure and start Bucardo: 
    sh mk-bucardo-repl.sh --primary "$HEROKU" --replica "$PLANETSCALE"

​
Monitor progress

Use the stat-bucardo-repl.sh tool to monitor the overall state of your migration: 
sh stat-bucardo-repl.sh --primary "$HEROKU" --replica "$PLANETSCALE"
It is also wise to directly confirm that the complete data is present (e.g. by using the count(*) aggregation or by specifically SELECTing data you know to have just written) before moving on. Count rows to gauge how caught-up the asynchronous replication is (where example is one of your table names): 
psql "$HEROKU" -c "SELECT count(*) FROM example;"; psql "$PLANETSCALE" -c "SELECT count(*) FROM example;"
Finally, in the event of trouble, the Bucardo logs may be illuminating: 
tail -F "/var/log/bucardo/log.bucardo"

​
Switch traffic

Because Bucardo is replicating both table and sequence data, it’s critical to stop write traffic at the source completely. heroku maintenance:on can stop all traffic but if you want to continue to allow read traffic, you can either arrange for that at the application level or enforce it at the database level thus: 
psql "$HEROKU" -c "REVOKE INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public FROM $(echo "$HEROKU" | cut -d "/" -f 3 | cut -d ":" -f 1);"
Once writes have stopped reaching Heroku and replicated to PlanetScale, it’s safe to begin writes to PlanetScale via an application deploy or reconfiguration. If you issued the REVOKE statement above and need to abort before switching traffic and return to service on Heroku, revert as follows: 
psql "$HEROKU" -c "GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO $(echo "$HEROKU" | cut -d "/" -f 3 | cut -d ":" -f 1);"

​
Cleanup

  1. Remove the Bucardo sync and metadata: 
    sh rm-bucardo-repl.sh --primary "$HEROKU" --replica "$PLANETSCALE"
  2. Optionally, terminate the EC2 instance that was hosting Bucardo.
  3. When the migration is complete and validated, delete the source Heroku Postgres database.

​
See also

​
Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.