Litestream: streaming replication for SQLite, and when it is the wrong tool

The problem Litestream solves, and who it is for

SQLite gives you a database in a single file. That file is easy to back up badly and hard to back up continuously. A cron job that copies the file can capture a torn write or a database mid-checkpoint, and it captures nothing that happened between runs. Litestream's answer is to sit next to the database as a separate process and ship changes as they are written. The README describes it as a standalone disaster recovery tool for SQLite that runs as a background process and safely replicates changes incrementally to another file or S3.

The target user is the operator of a single-node application: a small service, an edge deployment, a desktop or appliance product where the database is one file on one machine. Litestream is not a distributed database layer. It does not coordinate multiple writers, and it does not turn SQLite into a shared service. If your problem is that one machine's disk can disappear, Litestream is aimed at you. If your problem is that one machine cannot keep up with writes, it is not.

The project is at version 0.5.17, released on 2026-08-31, and the README carries a beta status badge. The last push to the main branch was on 2026-09-14. The release cadence visible in the repository is roughly monthly.

How replication works: the SQLite API, the WAL, and the lock table

Litestream does not read the database file directly. The README states that it only communicates with SQLite through the SQLite API, which is the reason given for why it will not corrupt your database. That constraint shapes everything else: because it goes through the API, it sees the database the way SQLite sees it, including write-ahead log state.

When replication starts, Litestream creates an internal table named `_litestream_lock` inside the source database. It uses that table to acquire SQLite's write lock while coordinating synchronization around WAL checkpoints. The writes happen in transactions that are rolled back, so no rows are left behind. The README is explicit that this changes the source schema and can change the database's page count or bytes, so a database under Litestream should not be expected to remain byte-identical to its pre-Litestream state. That is a real operational detail: checksums and file-size comparisons taken before and after enabling Litestream will differ, and that difference is not corruption.

Because the lock table lives in the source schema, it is also carried into backups, so restored databases contain it too. The README warns against dropping `_litestream_lock` while Litestream is running: synchronization around a checkpoint can fail until Litestream reinitializes the database, and restarting Litestream recreates the missing table automatically. The replica destinations visible in the repository layout include `s3/`, `gs/`, `abs/`, `oss/`, `file/`, `nats/`, and an SFTP dependency in go.mod, so the destination is pluggable rather than S3-only.

Building Litestream and pointing it at a replica destination

The README points to the Litestream web site for installation instructions and documentation rather than listing package commands itself, so the exact install method depends on your platform. What the repository does provide is a Makefile and a Dockerfile. The Makefile builds the binary into `dist/litestream` with the version stamped in through a linker flag, and it also has a `docker` target that builds an image tagged `litestream`.

make build

make docker

The Dockerfile defines two final stages. One is a hardened image based on `scratch` that runs as the `nonroot` user with the binary at `/usr/local/bin/litestream`. The other is a default image based on `debian:bookworm-slim` that additionally installs `ca-certificates` and `sqlite3`. Pick the default image if you want a shell and the sqlite3 CLI inside the container; pick the scratch image if you want the smallest surface and do not need either.

For a first real use, the shape is a source database path plus a replica URL pointing at a destination. The README does not print a full command or configuration example, so there is no snippet here to copy: the repository's `_examples/` and `docs/` directories are where the project keeps configuration and platform guides, and the web site carries the installation instructions. Restoring is a separate operation from replicating, and the related searches around the project treat restore as its own topic, which matches the design.

The replica is a recovery target, not a standby

The most common misreading of Litestream is to treat the replica as a second database you can query. Nothing in the README describes that. It describes disaster recovery: a copy you restore from. The replica is written in the project's own format, and the restore command is what turns it back into a usable SQLite file. If your architecture assumes a read replica you can point an analytics query at, Litestream does not offer that, and you will discover it after you have built on the assumption.

The second limitation is single-node by construction. There is no leader election, no fencing, no way for two Litestream processes to coordinate writers on the same database. The `_litestream_lock` table is a coordination point between Litestream and SQLite on one machine, not a distributed lock. Running two replicators against one database is outside what the documentation describes.

The third is the schema mutation. Because `_litestream_lock` is created in the source database, any tooling that asserts on schema, page count, or file bytes needs to be told about it. That includes migration diffing and integrity checks that compare against a known-good file.

Litestream compared with LiteFS

The comparison people search for is Litestream against LiteFS, and the difference is architectural rather than a feature list. Litestream is a process that reads a local SQLite database through the SQLite API and ships changes outward to object storage or a file. It assumes one writer on one machine and does not change how your application opens the database.

LiteFS takes a different route: it interposes at the filesystem level, presenting a FUSE filesystem so that SQLite on multiple machines sees what looks like a local database file while writes are coordinated across nodes. That is a fundamentally different deployment: you change how the database is mounted and you accept a filesystem dependency, in exchange for multi-node writes that Litestream does not attempt.

Go.mod lists a dependency on `github.com/psanford/sqlite3vfs`, and the Makefile and Dockerfile build a loadable extension from `./cmd/litestream-vfs` with the build tags `vfs,SQLITE3VFS_LOADABLE_EXT`, producing `litestream-vfs.so` and `litestream-vfs.a` for linux/amd64 and linux/arm64. So Litestream does have a VFS component, but the README's own framing of the tool remains disaster recovery. Do not read the presence of a VFS build as Litestream becoming a LiteFS replacement; the README does not make that claim.

Maintenance, upgrade cost, and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-14. Releases arrive at a steady pace: v0.5.15 on 2026-07-21, v0.5.16 on 2026-08-05, v0.5.17 on 2026-08-31. That is a project that is still being worked on, but the version number is still 0.x and the README labels the status beta, so upgrades should be treated as upgrades, not as patch-level no-ops. Read the release notes for each version rather than assuming compatibility.

The upgrade cost that stands out is the lock table. Because `_litestream_lock` is part of the source schema and is carried into backups, any change to how Litestream manages that table touches both your live database and your restore path. The README already tells you the recovery behaviour: dropping the table while Litestream runs can break checkpoint synchronization until the process reinitializes, and restarting recreates it. That is a documented escape hatch, and it is also a hint that schema-level assumptions are the fragile part of this design.

Licensing is Apache-2.0, as stated in the repository and shown by the licence badge in the README. Apache-2.0 is a permissive licence with an explicit patent grant. This is not legal advice; if you redistribute Litestream inside a product, read the LICENSE file and take your own counsel on notice and attribution obligations.

Editorial conclusion

Adopt Litestream if you run a single-node SQLite application and want a continuously updated replica in S3 or on another disk, and you accept that the replica is a recovery target rather than a live secondary. Do not adopt it if you need multiple writers, a standby that serves queries, or point-in-time recovery guarantees the project does not document. Before you commit, verify two things yourself: that the S3 bucket and credentials you plan to use work with the replica URL syntax, and that your restore path has been exercised at least once against a copy of the database.

Frequently asked questions

Official sources

1. benbjohnson/litestream on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases