--- title: "Litestream: Continuous SQLite Backups to S3" author: "Anshu Pathak" published: "2026-11-21T04:55:00.038Z" updated: "2026-11-21T03:56:09.731Z" url: "https://zyvop.com/litestream-continuous-sqlite-backups-to-s3-a290e" canonical: "https://zyvop.com/litestream-continuous-sqlite-backups-to-s3-a290e" tags: ["S3","backup","SQLite","DevOps","litestream"] --- # Litestream: Continuous SQLite Backups to S3 Stream every SQLite change to S3 within about a second and restore to any recent point in time. Setup, restores, tuning and caveats for Litestream v0.5. ![Cover image]() SQLite is one file, which makes it easy to run and easy to lose. Copying it with `cp` while your app is writing can give you a broken copy, and a nightly snapshot can cost you a day of data. Litestream is a small open-source (Apache-2.0) tool that runs beside your app, streams every change to S3-compatible storage, and restores the database to its latest state or an earlier point in time. > This post covers v0.5.x (latest at the time of writing: v0.5.18). Some flags below, such as `-dry-run` and `-force`, need v0.5.12 or later. ## How it works Litestream needs SQLite's WAL journal mode and turns it on automatically if your app has not. It watches the write-ahead log, controls checkpointing so no page is lost before it has been copied, and uploads the changes as small LTX files. By default it also uploads a full snapshot every 24 hours. A restore takes the latest snapshot and replays the LTX files recorded since. ```mermaid flowchart LR A[App] -->|writes| D[(SQLite DB and WAL)] D -->|WAL changes| L([Litestream]) L -->|LTX files and snapshots| S[S3-compatible bucket] S -->|litestream restore| N[(Restored DB)] ``` Your application needs no code changes beyond a pragma or two. Litestream takes short write locks when it checkpoints, and SQLite returns an error by default if your app tries to write at the same moment. Set a busy timeout on every connection so writes wait (up to 5 seconds here) instead of failing: ```sql PRAGMA busy_timeout = 5000; -- Only for very write-heavy apps (tens of thousands of small transactions per second): -- PRAGMA wal_autocheckpoint = 0; ``` ## Install ```bash # Debian/Ubuntu: download the latest .deb for your architecture (x86_64 shown) from GitHub Releases wget https://github.com/benbjohnson/litestream/releases/download/v/litestream--linux-x86_64.deb sudo dpkg -i litestream--linux-x86_64.deb # macOS brew tap benbjohnson/litestream && brew install litestream litestream version ``` The Debian package also installs a systemd service, and RPM packages are available for RHEL, Fedora and CentOS. Linux and macOS are the officially supported platforms. ## Configure and run The service reads `/etc/litestream.yml` by default: ```yaml dbs: - path: /var/lib/myapp/app.db replica: url: s3://my-backup-bucket/myapp ``` Credentials come from the config file or from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables (`LITESTREAM_ACCESS_KEY_ID` and `LITESTREAM_SECRET_ACCESS_KEY` also work). A systemd service does not inherit your shell's environment, so either put the keys in the config (and make it readable only by the account that runs the service) or pass the variables with a systemd `Environment=` or `EnvironmentFile=` line. Providers other than AWS (for example MinIO or Backblaze B2) need an `endpoint` setting too. ```bash sudo systemctl enable --now litestream sudo journalctl -u litestream -f ``` After you edit the config, run `sudo systemctl restart litestream`. ## Restore ```bash # Latest state, written to a new file litestream restore -o /tmp/app-restored.db s3://my-backup-bucket/myapp # A point in time (UTC) litestream restore -timestamp 2026-11-20T09:00:00Z -o /tmp/app-9am.db s3://my-backup-bucket/myapp # Restore and run SQLite's integrity check litestream restore -integrity-check quick -o /tmp/app-restored.db s3://my-backup-bucket/myapp ``` Restoring by URL does not read the config file, so export the same credentials in your shell first. If the database is listed in your config, you can restore by path instead (`litestream restore -o /tmp/app-restored.db /var/lib/myapp/app.db`) and Litestream takes the replica and credentials from the config. Restore refuses to overwrite an existing non-empty file unless you pass `-force`. Point-in-time restores can only land on the boundaries of files still stored in the replica, and those points get coarser as files age. The finest restore points (one per sync) survive only while their raw L0 files are kept, which is 5 minutes after compaction by default (`l0-retention`). Use `litestream ltx -level all /var/lib/myapp/app.db` to see what is available and `-dry-run` to preview a restore plan. Snapshots and their files are kept for 24 hours by default, so you can recover roughly the last day. Raise `snapshot.retention` for longer (durations use `s`, `m` and `h` only, so a week is `168h`). On a fresh server or container, restore before starting your app: ```bash litestream restore -if-db-not-exists -if-replica-exists /var/lib/myapp/app.db ``` This restores only when the local database is missing and a backup exists. In the other cases it exits successfully without touching anything, though real errors such as network or permission failures still return a non-zero exit code. You can also set `restore-if-db-not-exists: true` on the database in your config (or pass `-restore-if-db-not-exists` to `replicate`) and let Litestream restore itself on startup. ## Tune it ```yaml snapshot: interval: 1h # default 24h retention: 24h # default 24h heartbeat-url: https://hc-ping.com/your-uuid heartbeat-interval: 5m dbs: - path: /var/lib/myapp/app.db replica: url: s3://my-backup-bucket/myapp sync-interval: 1s ``` - **Snapshot interval:** a restore replays every file since the last snapshot, so write-heavy databases restore faster with more frequent snapshots. - **Sync interval:** every upload is a PUT request. Constant writes at the default 1 second is roughly 2.6 million PUTs a month, so raise `sync-interval` if a few seconds of potential loss is acceptable. - **Heartbeat:** Litestream pings the URL (for example a Healthchecks.io check) only while every database is syncing successfully, so a missing ping means replication is unhealthy or the daemon is down. ## Caveats - **Replication is asynchronous.** With the default settings, a hard crash can lose up to about a second of writes. On a normal shutdown Litestream tries to sync outstanding changes first. - **One writer per replica path.** Do not let two applications or instances replicate into the same bucket and path. It can leave you unable to restore. Litestream is a backup and recovery tool, not a multi-primary database. - **One replica per database in v0.5.** The old `replicas` list is deprecated. If you need a second copy, use your provider's cross-region replication or run another Litestream instance. - **No client-side** `age` **encryption in v0.5.x.** Since v0.5.1, a config that sets `age` identities or recipients makes Litestream refuse to start (v0.5.0 accepted the settings but silently ignored them). For S3 replicas, use server-side encryption (SSE-C or SSE-KMS) instead. - **Old tutorials may not match.** Guides written for v0.3 use `replicas:` and `generations`, which do not apply to v0.5. - **Recreating a database:** Litestream does not track deletions. Delete the `-wal` and `-shm` files along with the database, then run `litestream reset` on the database path and restart Litestream. - **Optional hardening:** setting `retention.enabled: false` stops Litestream deleting remote files, so its credentials do not need `DeleteObject`. Use bucket lifecycle rules to expire old data instead. ## Wrap-up Install it, point it at a bucket, and make one test restore into a temporary file before you trust it. That takes about ten minutes and turns a single SQLite file into a database you can recover to within about a second of a failure with the default settings.