LiteFS: a FUSE passthrough that replicates SQLite across a cluster

The problem LiteFS solves for SQLite deployments

SQLite is a single-file database. That is its strength on one machine and its ceiling on several. LiteFS is built for the case where an application already speaks SQLite and the operator wants the same database readable from more than one node. It presents a passthrough file system, so the application keeps opening a normal path and keeps using a normal SQLite driver. The project description states the goal directly: replicate SQLite databases across a cluster of machines.

The audience is narrow and worth stating plainly. It is for teams running read-heavy workloads where one node accepts writes and the rest serve reads. It is not a drop-in replacement for a client-server database, and the README does not present it as one. If your application needs concurrent writers on multiple nodes, the architecture below is the reason LiteFS is the wrong tool.

How the passthrough file system records transactions

LiteFS mounts over a directory and sits between the application and the underlying files. Writes to SQLite databases pass through it. Because it sees those writes, it can detect transaction boundaries rather than parsing SQL or hooking the driver. The README describes the mechanism as intercepting writes in order to detect transaction boundaries and record changes on a per-transaction level in LTX files, linking to the separate superfly/ltx repository. LTX is the unit of replication.

The repository layout matches that description. There is a fuse/ directory for the file system layer, a store.go at the top level, lease.go for the write lease, and ltx as an external dependency in go.mod. The architecture is not a database protocol proxy: it is a file system plus a change log plus a lease. The docs/ directory contains an ARCHITECTURE.md design document that the README points to for details, and that document is the right place to read before committing to a deployment.

The lease is the part that decides who may write. lease.go and lease_test.go exist at the top level, and the repository also carries a consul/ directory and a Consul API dependency in go.mod, which indicates that lease coordination can go through Consul. The README itself does not document the lease configuration in the excerpt available, so treat the Consul integration as something to confirm against the documentation site rather than assume.

Installing LiteFS and running a first mount

The README does not give a package manager install. It points to a Getting Started guide on the LiteFS documentation site at fly.io/docs/litefs/. The repository does ship a Dockerfile, and that is the most concrete installation path visible in the README. It builds the binary from source with Go 1.21.5 and produces an Alpine image with fuse3 installed.

FROM golang:1.21.5 AS builder
WORKDIR /src/litefs
COPY . .
RUN go build -ldflags "-s -w -X 'main.Version=${LITEFS_VERSION}' -X 'main.Commit=${LITEFS_COMMIT}' -extldflags '-static'" -tags osusergo,netgo,sqlite_omit_load_extension -o /usr/local/bin/litefs ./cmd/litefs

The second stage installs the fuse3 package and sets the entrypoint. Note the default command, because it tells you what the image expects at runtime:

FROM alpine
RUN apk add --no-cache fuse3
COPY --from=builder /usr/local/bin/litefs /usr/local/bin/litefs
ENTRYPOINT ["/usr/local/bin/litefs"]
CMD ["mount", "-skip-unmount"]

So a container started from this image runs litefs mount -skip-unmount by default. The README does not document the rest of the mount flags, the config file format, or the environment variables in the excerpt available, and go.mod shows gopkg.in/yaml.v3 is a direct dependency, which suggests YAML configuration exists but does not tell you its keys. Get those from the documentation site.

The repository also carries a Dockerfile.test for running the SQLite TCL test suite against LiteFS. The README gives these two commands. They are useful for checking whether a specific SQLite behaviour is supported before you build on it:

docker build -t litefs-test -f Dockerfile.test .
docker run --device /dev/fuse --cap-add SYS_ADMIN -it litefs-test select1.test

The --device /dev/fuse and --cap-add SYS_ADMIN flags are the part to notice. Any container running LiteFS needs access to the FUSE device and the capability to mount. That constraint applies to your own deployment, not only to the test image.

The beta label, the missing deletion support and other limits

The README states the project is in a beta state and asks that bugs be reported as GitHub issues. That is the project's own assessment, and it is the first thing to weigh.

The second is more specific. The README says LiteFS does not have database deletion implemented yet, and that this causes many SQLite TCL test suite tests to fail during teardown. The project also states that passing the TCL test suite is a goal that remains a work in progress. For an operator, the practical reading is that the SQLite surface LiteFS covers is not the whole of SQLite, and the project says so rather than leaving it to be discovered.

There is a third constraint implied by the design rather than stated as a limitation. A FUSE passthrough is in the write path of every SQLite transaction on the writer node. That is the cost of detecting transaction boundaries without driver changes. Whether that cost is acceptable depends on your write volume, and the README contains no benchmark figures, so it is something to measure on your own workload rather than take on faith.

Finally, the repository layout suggests a Fly.io-shaped deployment. There is a fly/ directory at the top level alongside consul/, http/ and cmd/. The README does not describe a Kubernetes operator or a Helm chart, and a search for Kubernetes guidance is not answered by anything in the README. If you are not on Fly.io and not on Consul, you are assembling the coordination yourself.

LiteFS compared with Litestream, and with moving off SQLite

The closest comparison is with Litestream, and the difference in approach is the useful part. Litestream is a replication tool for SQLite: it streams the write-ahead log to object storage so you can restore a database. LiteFS is a file system. It mounts over the database directory, intercepts writes to detect transaction boundaries, and records changes as LTX files that replicate to other machines in the cluster. One is a backup and restore path; the other puts a live, readable copy of the database on another node and coordinates which node may write. If what you want is durability and point-in-time restore, the Litestream model is a better fit for that job. If what you want is a read replica on a second machine, that is the problem LiteFS was built for.

The other comparison worth drawing is LiteFS against PostgreSQL. The difference is not a feature list. PostgreSQL is a client-server database with its own protocol, and concurrent writers are part of its design. LiteFS keeps SQLite as a library linked into your process and adds replication and a write lease around it. Choosing between them is choosing between a single-writer file-based database with replicas and a multi-writer server. The lease in lease.go is the clearest expression of that boundary.

Maintenance, releases and what the licence allows

The repository is not archived. The last push was on 2026-05-11. The most recent releases listed are v0.5.14, v0.5.13 and v0.5.12, all dated 2025-04-22, which means the release line has been quiet for a while even though the branch has seen commits since. The README describes the project as actively maintained but in a beta state, and the release history is consistent with a project that is maintained at a low cadence rather than one shipping frequently. Plan upgrades around that cadence rather than assuming a steady stream of patch releases.

Upgrade cost is hard to estimate from the README. LiteFS depends on the external superfly/ltx module at v0.3.14 for its change format, so an LTX format change is the kind of thing that would affect compatibility between versions, but the README does not document a rollback procedure or a version compatibility matrix. Verify that before you need it, not after.

On licensing: LiteFS is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It does not impose copyleft obligations on your application, but this is a description of the licence text, not legal advice, and the LICENSE file in the repository is the authoritative document. If you redistribute the binary, read it.

Editorial conclusion

Adopt LiteFS if you run a read-heavy SQLite application and want replicas on several machines without moving to a client-server database; the beta label and the missing database deletion support are the two things to weigh first. Do not adopt it if your workload is write-heavy, or if you need an out-of-the-box Kubernetes story, because the repository ships a fly/ directory and a Consul client rather than a maintained operator. Before deploying, verify on your own hardware that FUSE is available to the container, that the lease holder and replica roles behave as the documentation describes, and that your upgrade path from the current v0.5.x releases is one you can roll back.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. superfly/litefs on GitHub