Litestream: SQLite Replication to S3, R2 and MinIO
Litestream is an open-source tool that continuously streams changes from a SQLite database’s write-ahead log (WAL) to object storage such as AWS S3, giving a SQLite app off-server backups and point-in-time restore without running a database server. The SQLite database itself stays on a local disk; S3 holds the replica.
OpenRun is an open-source web app deployment platform with built-in Litestream support for SQLite applications. App SQLite databases are continuously replicated to AWS S3 or S3-compatible object storage such as Cloudflare R2, MinIO and SeaweedFS, and are automatically restored before the app starts if its local volume is lost. Applications do not need to package, configure or run Litestream themselves: OpenRun manages the replication and restore lifecycle on Docker, Podman and Kubernetes.
Two types of SQLite data can be replicated:
- App data: the SQLite databases behind SQLite service bindings.
- Server metadata: OpenRun’s own metadata and audit databases (single node, SQLite metadata).
This page covers the litestream configs, metadata replication, app data replication, monitoring and the operational notes for disaster recovery.
Automatic SQLite Backup and Restore
- Backup: replication is continuous; changes upload within about a second.
- Restore: automatic. A new node, a lost volume or a re-attached binding is repopulated from the replica before the app starts.
- Metadata: with server metadata replicated as well, a new OpenRun server can recover apps, bindings, services, versions and audit history after a complete node loss. It also needs the server config, credentials and encryption keys described in Operational Notes.
S3-Compatible Storage
OpenRun’s Litestream integration works with:
- AWS S3
- Cloudflare R2
- MinIO
- SeaweedFS
- Other S3-compatible object stores
Example configs for Cloudflare R2 and MinIO (see Litestream Configs for all keys):
# Cloudflare R2: use the account's S3 API endpoint and region "auto"
[litestream.r2]
endpoint = "https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
bucket = "openrun-backups"
region = "auto"
access_key_id = '{{secret_from "env" "R2_ACCESS_KEY_ID"}}'
secret_access_key = '{{secret_from "env" "R2_SECRET_ACCESS_KEY"}}'
force_path_style = true
# Self-hosted MinIO
[litestream.minio]
endpoint = "http://localhost:9000"
bucket = "openrun-backups"
region = "us-east-1"
access_key_id = '{{secret_from "env" "MINIO_ACCESS_KEY"}}'
secret_access_key = '{{secret_from "env" "MINIO_SECRET_KEY"}}'
force_path_style = trueHow It Works
On Docker and Podman, OpenRun manages a Litestream companion container. On Kubernetes, OpenRun creates the restore init container and Litestream sidecar automatically.
Litestream Configs
Litestream settings are named entries in the server config. Multiple configs allow different buckets, endpoints or credentials to coexist (per team, per environment, metadata vs apps):
[litestream.mainbackup]
endpoint = "https://s3.example.com" # S3-compatible endpoint; empty for AWS S3
bucket = "openrun-backups"
region = "us-east-1"
path_prefix = "openrun" # replica key prefix inside the bucket
access_key_id = '{{secret_from "env" "LITESTREAM_KEY_ID"}}'
secret_access_key = '{{secret_from "env" "LITESTREAM_KEY"}}'
force_path_style = true # required by most S3-compatibles
sync_interval = "1s"
retention = "72h"
snapshot_interval = "24h"
[metadata]
litestream_config = "mainbackup" # replicate the server's own databases| Key | Default | Description |
|---|---|---|
type | s3 | Replica type. file replicates to a local directory (metadata only; not usable for app bindings) |
endpoint | S3-compatible endpoint URL; leave empty for AWS S3 | |
container_endpoint | Endpoint as reachable from inside app containers, when it differs from endpoint (see Container-visible endpoints) | |
bucket | Bucket name (required for s3) | |
region | S3 region | |
path_prefix | Key prefix inside the bucket | |
path | Local directory (required for file) | |
access_key_id, secret_access_key | Credentials; support secret references, resolved at startup | |
force_path_style | false | Path-style S3 URLs, required by most S3-compatible servers |
sign_accept_encoding | true | Include the Accept-Encoding header in request signatures. Set false for S3-compatible services that rewrite the header in transit (Garage, some proxies) and reject the signature. Google Cloud Storage endpoints (*.googleapis.com) are detected automatically and never sign it |
sync_interval | 1s | How often changes are uploaded. This bounds the data loss window on a crash |
retention | 24h | How long replica history is kept. This bounds how far back a restore can go |
snapshot_interval | 24h | Snapshot frequency; lower values make restores faster |
sidecar_image | litestream/litestream:0.5 | Litestream image for app replication containers. Keep pinned: the replica format ties restores to the image series |
checkpoint_interval, min_checkpoint_page_count, truncate_page_n | 1m, 1000, ~500MB of pages (Litestream defaults) | Checkpoint tuning, see Litestream’s guide. Apps with long-running reads should set truncate_page_n = 0 to disable the blocking TRUNCATE checkpoint |
storage_class, sse_kms_key_id | Optional S3 storage class and server-side encryption settings |
- Credentials: cannot use the
dbsecret provider, since metadata replication must be resolvable before the metadata database is opened. - Validation: all configured entries are validated at server startup.
- Log level:
logging.litestream_log_levelsets the verbosity of replication logs (the embedded metadata replication, written to the server log, and the app sidecar containers’ own logs). It defaults toWARNindependent of the mainlogging.level, since litestream logs every compaction and snapshot atINFO; set it toINFOorDEBUGto see those.
Metadata Replication
Set metadata.litestream_config to a config name to replicate the server’s metadata and audit databases (the file cache is a rebuildable cache and is not replicated). This applies when the metadata database is SQLite; with PostgreSQL metadata there is nothing to do.
Replication runs inside the OpenRun server process (Litestream is embedded as a library); no separate binary or process is needed. On startup, if a metadata database file is missing and a replica exists, it is restored before the server opens it.
To rebuild a lost node:
- Install OpenRun on a new machine.
- Use the same config file.
- Start the server. Apps, bindings, services, versions and audit history are restored from the replica; containerized apps then redeploy on first request, restoring their SQLite data the same way.
App Data Replication
Enable replication for a SQLite service by referencing a config:
openrun service create sqlite/main --config litestream_config=mainbackup
openrun app create --bind sqlite/main --approve github.com/example/notes-app /notesEvery *.db file the app creates in its binding directory is replicated, including files created while the app is running (Litestream’s directory watcher discovers them within seconds). The file selection can be changed per binding with the pattern binding config key, e.g. --config "pattern=*.sqlite3".
How it runs:
- Docker/Podman: a per-app companion container (
clc-<app-id>-ls) runslitestream replicatesharing the app’s data volume. Before the app container starts on an empty volume, one-shot restore containers pull any replicated databases back. The sidecar survives app version updates, stops gently (after a final sync) when the app is idle-shut-down, and restarts with the app. - Kubernetes: restore init containers plus a native sidecar (init container with
restartPolicy: Always) run inside the app’s pod. Requires Kubernetes 1.29 or newer. The sidecar starts before the app container and is terminated after it, so it can perform a final sync during graceful shutdown. Abrupt node loss or an unavailable object store can prevent that sync.
Replica locations are keyed by binding identity and environment:
s3://<bucket>/<path_prefix>/bindings/<binding-id>/prod/...
s3://<bucket>/<path_prefix>/bindings/<binding-id>/staged/...- Prod and staging apps replicate to separate locations. To use different buckets or credentials per environment, link a staging service whose config names a different litestream config.
- The replica follows the binding, not the app: detaching a binding and attaching it to a new app restores the data into the new app’s fresh volume.
- Changing a service’s
litestream_configtakes effect on the next app reload: replication starts fresh in the new location, and the old location stops advancing but keeps its history.
Container-visible endpoints
The S3 endpoint must be reachable from inside app containers. For a localhost endpoint with Docker/Podman, OpenRun automatically substitutes the container-reachable host name (like host.docker.internal). Kubernetes has no automatic mapping: if pods reach the endpoint through a different address than the server, set container_endpoint on the litestream config. The server keeps using endpoint for its own access.
Monitoring
openrun replication status reports the state of every replicated database:
$ openrun replication status -f table
Kind Target Config State LastSync Files Apps
metadata metadata mainbackup healthy 2026-07-25 16:31:42 -
metadata audit mainbackup healthy 2026-07-25 16:31:42 -
app /auto/app_prd_.../sqlite (prod) mainbackup healthy 2026-07-25 23:31:30 data.db /notes
app /auto/app_prd_.../sqlite (staged) mainbackup pending - - stage.localhost:/notesUse -f json for full detail, including the per-file breakdown and replica transaction ids. The same data is available to apps through the read-only replication_status function of the openrun.in plugin.
| State | Meaning |
|---|---|
healthy | Replica advanced within the last 10 × sync_interval (at least 2 minutes); for metadata, local and replica are in sync |
idle | Replica is reachable but has not advanced recently; normal for an app that is not writing |
syncing | Metadata only: the local database is ahead of the replica and the upload is in progress |
pending | Nothing replicated yet (fresh binding, or an environment that has not deployed) |
sidecar_down | The replication container is not running while replicated data exists; fix by reloading the app (app reload --promote) |
misconfigured | The service references a litestream config that is not defined (or not usable for apps) |
error | The replica location could not be checked; see the error field |
App states combine the replica listing in object storage with the replication container’s state, so a dead sidecar is flagged even when the app is idle.
Operational Notes
openrun.toml, object-store credentials and the encryption key for the embedded secrets store ($OPENRUN_HOME/config/secret.key when using the default). Metadata replication does not back up that key, local dev source directories, arbitrary mounted files or the store.in database. Keep separate backups of those assets as needed. Restore the configuration and keys before starting a replacement server against the replicas.- Data loss window: replication is asynchronous.
sync_interval(1s by default) is an upload interval, not a guaranteed recovery point. Network failures, object-store outages or replication lag can increase the amount of data lost on host failure. - Restore window: bounded by
retention. Increase it (and considersnapshot_interval) if you need to restore older states. - Storage: app volumes are Docker named volumes or block-backed PVCs. Network filesystems (NFS/SMB) are not supported for SQLite data, and NFS-backed PVCs may delay discovery of new database files.
- Volume permissions: fresh volumes and restored files are made writable for non-root app users with a
chmodthat runs using the Litestream image, so distroless app images work with replication enabled. Kubernetes pods additionally getfsGroup: 65532. - App deletion removes local data: deleting an app removes its managed volumes or PVCs. Object-storage replicas are not deleted. Preserve the binding if it will be reattached to another app; a newly created binding has a different ID and does not automatically find a deleted binding’s replica.
- Image pinning:
sidecar_imageand the embedded Litestream are on the 0.5 series (LTX replica format). Upgrades are an operator action. - Windows: fully supported. App replication runs in Linux containers; metadata replication runs on the host through the embedded library.
Frequently Asked Questions
What is Litestream?
Litestream is an open-source streaming replication tool for SQLite. It runs alongside the app, copies new WAL pages to S3-compatible object storage about every second, and can restore the database from that replica. OpenRun runs and configures Litestream for each app, so the app only uses SQLite.
Can SQLite run directly on S3?
No. SQLite needs a local file system with working file locks; it cannot use S3 (or NFS) as its storage. The usual pattern, which OpenRun implements, is to keep the database on a local volume and continuously replicate it to S3 with Litestream, restoring from S3 when the volume is empty.
How do I run Litestream with Docker?
Without a platform, the common approaches are to add the Litestream binary to the app image and start the app through litestream replicate -exec, or to run Litestream as a second container sharing the data volume and add a litestream restore -if-replica-exists step to the startup script. OpenRun does this for you: it runs the litestream/litestream image as a companion container next to the unchanged app image and runs the restore before the app container starts.
Do I need litestream restore -if-replica-exists in my entrypoint?
No. OpenRun lists the replica in object storage and restores each database with litestream restore -if-db-not-exists before the app starts. A new app with no replica starts with an empty volume, and an app with existing local data is not overwritten.
Can I restore a SQLite database to an earlier point in time?
Automatic restore always uses the latest replicated state. To recover an earlier state, use the Litestream CLI from the same 0.5 image series with its restore -timestamp option against the binding’s replica path. The retention setting bounds how far back you can go.
Can I run SQLite on Kubernetes with Litestream?
Yes. The app’s SQLite volume becomes a PersistentVolumeClaim, and OpenRun adds the restore init container and Litestream sidecar to the pod. SQLite allows one writer, so apps with a SQLite binding run as a single replica with the Recreate update strategy.
Does OpenRun automatically back up SQLite databases to S3?
Yes. OpenRun uses Litestream to continuously replicate SQLite databases to AWS S3 or compatible object storage. Changes are uploaded according to the configured sync_interval, which defaults to one second.
Does OpenRun automatically restore SQLite after volume loss?
Yes. When an app starts with an empty or recreated volume, OpenRun restores its replicated SQLite databases from object storage before starting the application. The replica follows the binding, so data can also be restored when that binding is attached to a new app.
Do I need to add Litestream to my Docker image?
No. On Docker and Podman, OpenRun runs Litestream in a managed companion container that shares the app’s data volume. Your application image does not need to include or configure Litestream.
Can I use Cloudflare R2 or MinIO instead of AWS S3?
Yes. OpenRun supports Cloudflare R2, MinIO, SeaweedFS and other S3-compatible object stores. Configure the provider’s endpoint and enable path-style URLs when the provider requires them.
Does Litestream replication work with OpenRun on Kubernetes?
Yes. OpenRun automatically adds a restore init container and Litestream sidecar to the app pod. Kubernetes 1.29 or newer is required for the native sidecar lifecycle used by replication.