Migrate Shared Postgres

This guide shows how to dump schemas and table data from a Shared Postgres database on shuttle.rs, and upload them to shuttle.dev.

If you encounter issues, feel free to contact us for help.

​

Prerequisites

To run the data upload against the new database, you need a Postgres Client. In this guide, we will use psql. On Debian/Ubuntu, you can install it with:

sudo apt install postgresql-client

​

1. Deploy and provision Shared Postgres on shuttle.dev

Follow Platform Migration to deploy your app to shuttle.dev, including the provisioning of the database resource.

If you want the restore step to restore both the schema and data, you can temporarily disable migration logic in your app during this phase.

​

2. Upgrade container on shuttle.rs and Shuttle CLI

To use the dump command, your deployer and CLI need to be v0.49.0 or higher.

Upgrade the CLI by following the upgrading guide.

Restarting the project will upgrade the deployer to the latest version:

cargo shuttle project restart

​

3. (Optional) Stop running service on shuttle.rs

If your app is frequently writing to the tables, and you don’t want data to go missing after the migration, it is recommended to stop the current deployment while you perform the database maintenance.

cargo shuttle stop

​

4. Dump data from shuttle.rs

Since the Shared Postgres cluster has strict permissions, running pg_dump against your connection string is not possible. Instead, you can use the resource dump command that runs pg_dump with --no-owner --no-privileges for you.

The command writes a dump in SQL format to stdout, so you can use it to write to a file like so:

# dump database into /tmp/dump.sql
cargo shuttle resource dump database::shared::postgres > /tmp/dump.sql

You can inspect the file and edit it to your liking. If you already let your schema migrations run in the new db, you could for instance remove the CREATE TABLE, ALTER TABLE etc, and only keep the table data COPY statements and so on.

​

5. Restore data on shuttle.dev

Use the following command to get the connection string for the new database:

shuttle resource list --show-secrets

Use psql to run the dump file against it:

psql -d <connection string> -f /tmp/dump.sql

You might see various errors about tables, rows, or constraints already existing in the new database. In most cases this is fine, but you can verify that everything looks good by connecting to the database, and testing the app.

psql <connection string>

If something has gone wrong, you can cancel the migration for now and deploy the service on shuttle.rs again.

​

Final steps

If you are happy with the migration to the new platform, you can shut down the old project’s container (no need to delete the project):

cargo shuttle project stop

If you don’t want to keep the SQL dump file on disk, remember to delete it.