⭐ If you find Zipline useful, please consider giving it a star on Github! ⭐
GuidesBackup

Backup Postgres

Back up and restore a PostgreSQL database with pg_dump

This guide works for any PostgreSQL database. The examples use Zipline's Docker Compose setup; replace the service name, database, and username with your own. Without Docker, run pg_dump and psql directly with your database's connection details.

For PGlite, use the PGlite backup instructions instead.

Identify credentials

Find the database username and name in your docker-compose.yml or .env. Zipline's provided Compose file uses:

postgresql:
  image: postgres:16
  restart: unless-stopped
  env_file:
    - .env
  environment:
    POSTGRES_USER: ${POSTGRESQL_USER:-zipline}
    POSTGRES_PASSWORD: ${POSTGRESQL_PASSWORD:?POSTGRESQL_PASSWORD is required}
    POSTGRES_DB: ${POSTGRESQL_DB:-zipline}

Unless overridden in .env, both the username and database name are zipline.

Create a backup

Make sure PostgreSQL is running, then run this from the directory containing your docker-compose.yml:

docker compose exec -T postgresql \
  pg_dump -U zipline zipline > zipline_backup_$(date +%F_%H-%M-%S).sql

This runs pg_dump inside the postgresql container and saves its output to a timestamped SQL file on your host. Check that the command finishes successfully before relying on the backup.

Do something with the backup

Save it somewhere safe, copy it to another server, or use it however you need. You don't have to restore it now. If you're moving servers, copy the SQL file to the destination before continuing.

The remaining steps explain how to restore it when you need to.

Restore a backup

Stop the application that uses the destination database, but keep PostgreSQL running. For Zipline:

docker compose stop zipline
docker compose up -d postgresql

Restore into an empty database. Replace zipline with its username and database name, and zipline_backup.sql with your backup's path:

docker compose exec -T postgresql \
  psql -v ON_ERROR_STOP=1 -U zipline zipline < zipline_backup.sql

Check the output for errors. Restoring into a database that already contains data can cause conflicts; this command doesn't clear it first.

After restoring

Start your application and check that the restored data is present. For Zipline:

docker compose up -d zipline

This backup contains database records only. Back up uploaded files or other application storage separately.