Migrate from Heroku Postgres

Get the source connection string

The reliable way is the CLI:

heroku pg:credentials:url DATABASE -a your-app

This prints the full connection URL (and the individual fields). heroku config:get DATABASE_URL -a your-app works too, but pg:credentials:url is explicit about which credential you are getting on multi-credential databases.

postgres://user:password@ec2-xx-xx-xx-xx.eu-west-1.compute.amazonaws.com:5432/dbname

Heroku-specific caveats

• Credentials rotate. Heroku rotates database credentials on certain maintenance events — grab the URL right before the import window, not the day before.
• TLS is required on Heroku Postgres; the importer's automatic sslmode=require matches. Heroku's server certificates are not always verifiable by hostname, which is fine for require.
• Essential-tier databases (formerly mini/basic) have row limits but are small by definition — they fit any CapyDB plan.
• Extensions: Heroku enables few by default; pg_stat_statements is common and allowlisted. If you used postgis or other non-allowlisted extensions, the preflight will say so.

Preflight

capydb import preflight --source-url "$(heroku pg:credentials:url DATABASE -a your-app | grep -o 'postgres://[^ ]*')"

(or paste the URL into the dashboard's Import panel).

Import

Put the app in maintenance mode so writes stop:

heroku maintenance:on -a your-app
capydb import --source-url "postgres://..." --recreate --wait

After the import

1. Spot-check sequences.
2. \dx for extensions.
3. ANALYZE;
4. Point the app at CapyDB (heroku config:set DATABASE_URL=... if the app stays on Heroku, noting some buildpacks expect the Heroku-managed var; otherwise set env wherever the app now runs), then heroku maintenance:off.