litestream: Usage, Options & Common CI Errors
litestream streams SQLite changes to S3-compatible storage and restores them.
litestream gives SQLite continuous backup to object storage. In CI it mostly appears as a restore step (pull a database from S3) or a smoke test, where credentials and the generation check matter.
What it does
litestream continuously replicates a SQLite database's WAL to S3/GCS/Azure/SFTP and can restore the database from that replica. replicate runs as a long-lived process; restore is a one-shot pull used to rehydrate a database.
Common usage
litestream replicate ./app.db s3://bucket/app.db
litestream restore -o ./app.db s3://bucket/app.db
litestream restore -config litestream.yml ./app.db
litestream replicate -config litestream.yml # long-runningOptions
| Item | What it does |
|---|---|
| replicate <db> <url> | Continuously back up to a replica |
| restore -o <db> <url> | Restore a database from a replica |
| -config <file> | Use a YAML config (dbs + replicas) |
| -if-replica-exists | Only restore when a replica exists |
| AWS_ACCESS_KEY_ID / _SECRET | Object-store credentials (env) |
Common errors in CI
litestream replicate runs forever, so in CI run it in the background (or only run a one-shot restore) - a foreground replicate will hang the job. "no generation found" / "no backups found" on restore means the replica is empty or the path is wrong. "NoCredentialProviders" / AccessDenied means the S3 credentials (AWS_ACCESS_KEY_ID/SECRET or the config) are missing or unauthorized. Restoring over an existing file fails unless you remove it or use -if-db-not-exists.