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).sqlThis 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 postgresqlRestore 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.sqlCheck 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 ziplineThis backup contains database records only. Back up uploaded files or other application storage separately.