Self-hosted service
superfly/litefs avatar
superfly/litefs

LiteFS: a FUSE layer that records SQLite transactions, and the one it cannot do

FUSE-based file system for replicating SQLite databases across a cluster of machines

4,918 stars131 forksGoApache-2.0

At a glance

What is it?
LiteFS sits between SQLite and the disk, detects transaction boundaries by watching writes and records them per transaction in LTX files, which makes it a good fit for replicated SQLite and a poor fit for anything that deletes a database.
Who is it for?
Adopt LiteFS if your workload is many machines reading and writing the same SQLite database and you can accept a beta filesystem that cannot delete one. Do not adopt it for a workload that drops databases, because deletion is unimplemented and the SQLite TCL suite fails at teardown for that reason alone.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 17 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • superfly/litefs4,918 ★ · +39
Star history
Repository2026-09-232026-11-15
superfly/litefs4.9k4.9k

39 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

It works by watching writes, not by reading the SQLite file

LiteFS is a FUSE-based file system for replicating SQLite databases across a cluster of machines, written in Go and licensed Apache-2.0. The mechanism is stated in one sentence: it works as a passthrough file system that intercepts writes to SQLite databases in order to detect transaction boundaries and record changes on a per-transaction level in LTX files.

Two things follow from intercepting writes. The transaction boundary is not parsed out of the database file, it is observed as the sequence of writes SQLite issues, so the unit of replication is a transaction rather than a page. And the output is a separate log format, LTX, maintained by the superfly/ltx repository and pinned in go.mod at v0.3.14.

The container's whole job is mount, and the binary is statically linked

The Dockerfile says what the container is for. The builder stage compiles one binary from ./cmd/litefs, and the runtime stage is Alpine with fuse3 installed:

dockerfile
ENTRYPOINT ["/usr/local/bin/litefs"]
CMD ["mount", "-skip-unmount"]

So the image is not a server to configure and run in the usual sense. It is a mount that takes over the database directory, and -skip-unmount on the way out tells it to leave the mount point rather than tearing it down.

The build itself is worth reading for what it removes. The linker flags strip the binary and pass the version and commit in as ldflags variables, and -extldflags '-static' makes it static, which is what lets it run on Alpine without a matching glibc:

sh
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

Two build args, LITEFS_VERSION and LITEFS_COMMIT, are declared empty. Build without them and the binary reports neither version nor commit, which matters when you are trying to work out which LiteFS a replica is running.

sqlite_omit_load_extension rules out custom SQLite extensions

Three build tags are passed to the compiler: osusergo, netgo and sqlite_omit_load_extension. The first two keep the binary static and independent of the host resolver. The third changes what SQLite inside LiteFS can do.

That tag compiles out SQLite's extension loading interface. Any code path that loads an extension at runtime, which is how a custom FTS tokenizer or a third party function module gets into SQLite, is not compiled into the shipped binary.

So if your plan involves a custom tokenizer for full text search, or any extension you would normally load with a .load directive, the official LiteFS image cannot do it and you need your own build. The tag is in the Dockerfile rather than in a documented option, so it is easy to miss when you read the README, and it is the kind of constraint that surfaces much later, when a query fails to load a module rather than at build time.

The other side of the same decision is a smaller, more predictable binary, which is what makes the static Alpine image work at all.

Consul is a dependency you run, not one LiteFS embeds

Replicating a database across machines needs one node to be the writer at a time, and go.mod shows where that coordination comes from:

text
go 1.21
bazil.org/fuse v0.0.0-20230120002735-62a210ff1fd5
github.com/hashicorp/consul/api v1.11.0
github.com/superfly/ltx v0.3.14
github.com/prometheus/client_golang v1.13.0

The tree agrees: lease.go and lease_test.go at the root, plus a consul/ package. The module requires hashicorp/consul/api at v1.11.0, which is a client library, so a Consul-compatible service is something you operate alongside LiteFS rather than something the binary starts for you.

Two more dependencies describe the operational surface. prometheus/client_golang means the process can be scraped. gopkg.in/natefinch/lumberjack.v2 is in the direct requires, which is a log rotation library, so log files roll on their own.

The indirect block is mostly Consul's own dependency tree, serf and memberlist among them, which is a hint about how much of your deployment is the lock service rather than the filesystem.

Deletion is missing, and that is why the TCL suite fails at teardown

The README names the project's own test standard first: passing the SQLite TCL test suite is a goal, and it is a work in progress. Then it gives the reason.

LiteFS does not have database deletion implemented, and that causes many tests in the suite to fail during teardown. That is a specific, structural gap rather than a list of failing assertions: the suite creates and destroys databases, and the teardown step has nothing to call.

It is worth separating that from a crash or a wrong result. A replica that does not delete still replicates what is written, so applications that never drop a database are unaffected. Anything that does drop one has no supported path.

The README runs a test from the suite in isolation in a container:

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

The two flags in that run command are the price of the test: real FUSE needs /dev/fuse, and SYS_ADMIN is what lets the container mount it. If your CI runs rootless containers, that run command is where the trouble starts.

Three releases on one afternoon, then a year of commits

The release history is compressed into a single day. v0.5.12, v0.5.13 and v0.5.14 were all published on 2025-04-22, within about two hours of each other. The last push to main was on 2026-10-30, and the repository is not archived.

The README describes the project as actively maintained but in beta. Those two statements sit oddly next to a release list that ends in April 2025, which is the kind of tension worth resolving yourself before you depend on it: the code moves, the version numbers do not, so there is no released artifact matching what is on main.

The version is a 0.5 series, which by convention means the interfaces may still move. The Makefile offers almost nothing for a contributor: a default target that does nothing, and a check target that runs errcheck ./... and staticcheck ./.... There is no test target in the Makefile at all.

Feature patches go to your own fork, then a link back to the issue

The contributing rules are unusual enough to read before you write anything. Small bug fixes and typo fixes go straight to a pull request on the repository. Features do not.

For a feature the order is fixed: discuss it in an issue first, create the pull request on your own fork, then post a link to that pull request in the issue for consideration.

The README gives the reason plainly. The project has a roadmap, features are added and tested in a certain order, and a feature implementation will almost certainly need its code style, implementation details and test coverage adjusted, so the maintainer finds it easier to take your work as a starting point than to review a finished branch.

What that means for an adopter is that the roadmap is the schedule. There is no published date for database deletion, and the roadmap plus the open issues are the only place that priority is visible.

Editorial conclusion

Adopt LiteFS if your workload is many machines reading and writing the same SQLite database and you can accept a beta filesystem that cannot delete one. Do not adopt it for a workload that drops databases, because deletion is unimplemented and the SQLite TCL suite fails at teardown for that reason alone. Two things to verify before you plan around it: that your build does not need SQLite extension loading, since the official binary is compiled with sqlite_omit_load_extension, and that you have a Consul-compatible lock service to run alongside it, since the module requires hashicorp/consul/api rather than embedding one.

Frequently asked questions

What is LiteFS?

A FUSE-based file system for replicating SQLite databases across a cluster of machines, written in Go. It works as a passthrough file system that intercepts writes to SQLite databases to detect transaction boundaries and records changes per transaction in LTX files.

Is LiteFS ready for production use?

The README describes the project as actively maintained but currently in beta. The three most recent releases, v0.5.12, v0.5.13 and v0.5.14, were all published on 2025-04-22, while the last push to main was on 2026-10-30.

How do I run a single SQLite TCL test against LiteFS?

Build the test image with docker build -t litefs-test -f Dockerfile.test ., then run one test in isolation with docker run --device /dev/fuse --cap-add SYS_ADMIN -it litefs-test select1.test. The device and capability flags are what let the container mount FUSE.

What does LiteFS not implement yet?

Database deletion. The README states that LiteFS does not have deletion implemented, and that this is what causes many tests in the SQLite TCL suite to fail during teardown. Passing that suite is described as a goal still in progress.

Where is the LiteFS documentation?

The Getting Started guide lives on the documentation site at https://fly.io/docs/litefs/getting-started/, with the rest of the docs under https://fly.io/docs/litefs/. The design document is in the repository at docs/ARCHITECTURE.md, and bugs go to issues on the GitHub repository.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. README
  4. Releases
  5. superfly/litefs on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/superfly-litefs.svg)](https://hysenlabs.com/projects/superfly-litefs)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/superfly-litefs.svg)](https://hysenlabs.com/projects/superfly-litefs)

Was this useful?