Databases

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.

·
5 min read
·
AI-assisted

AI tooling disclosure

Generative AI materially contributed to this article.

Human review confirmed by the author.

Litestream: Continuous SQLite Backups to S3

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.

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:

PRAGMA busy_timeout = 5000;
-- Only for very write-heavy apps (tens of thousands of small transactions per second):
-- PRAGMA wal_autocheckpoint = 0;

Install

# Debian/Ubuntu: download the latest .deb for your architecture (x86_64 shown) from GitHub Releases
wget https://github.com/benbjohnson/litestream/releases/download/v<version>/litestream-<version>-linux-x86_64.deb
sudo dpkg -i litestream-<version>-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:

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.

sudo systemctl enable --now litestream
sudo journalctl -u litestream -f

After you edit the config, run sudo systemctl restart litestream.

Restore

# 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:

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

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.

Comments(0)

Join the discussion by logging into your account.

No comments yet. Be the first to comment!

Anshu Pathak

Passionate developer sharing knowledge about modern web technologies and best practices.

Subscribe to Anshu Pathak's Newsletter

Direct email dispatches when new stories are published. Zero algorithms.