Backing up and restoring a self-hosted copy

Back up the PostgreSQL database with pg_dump, restore it with pg_restore, and check that a backup is one you could actually use.

Edit this page

This page is for a copy you run yourself. On app.smpl.money, the copy of your records you can take with you is an export: Taking your data with you says how.

A self-hosted copy of Simple Balance has one thing to back up: its PostgreSQL database. No uploads directory, no object store, no state on disk in the container. Both deployment guides, Docker Compose and Oracle Cloud or AWS, set up a backup every night and say how to restore one. This page is the same thing by hand, for anywhere else.

A Simple Balance file, the export on Import/Export from 0.2.2, isn’t a backup. It’s one person’s ledger, or some of its accounts, for moving them into another copy of Simple Balance. A backup is the whole database, with everybody on your copy and every sign-in, and it’s put back with pg_restore.

Taking one

sh
pg_dump --format=custom "$DATABASE_URL" > simple-balance-$(date +%F).dump

--format=custom rather than plain SQL because it restores selectively and compresses.

$DATABASE_URL is the connection string written for the app, and PostgreSQL’s own tools read a few parts of it differently. They refuse sslmode=no-verify. They need the sslrootcert file where they run, and without one, verify-full looks for ~/.postgresql/root.crt. And pg_dump has to be the same major version as the server, or newer.

Restoring one

sh
createdb simple_balance_restored
pg_restore --no-owner --dbname=simple_balance_restored simple-balance-2026-09-17.dump

--no-owner so the restore doesn’t need the original role to exist. Point a deployment at the restored database and start it. Migrations run at startup, so a dump from an older release upgrades on first boot.

Checking the backup is real

A backup nobody has restored is a hypothesis. The cheap test:

  1. Restore into a scratch database.
  2. Start a deployment against it with SMTP_HOST and MAIL_FROM unset, so the copy mails nobody.
  3. Open the trial balance in Reports.

If it comes back and totals zero in every currency, your books in the restore are consistent rather than broken. That’s a stronger check than the file’s size, which is the thing people actually watch, but it has two limits. Each person’s trial balance covers only their own books, so on a deployment other people use, it checks yours and not theirs. And it can’t show that nothing’s missing: every transaction nets to zero by itself, so a ledger short a few of them still passes. For that, compare a few account balances with the live deployment, allowing for anything entered since the dump.