LiteFS — Distributed SQLite Replication with FUSE

Introduction

LiteFS is a distributed file system built specifically for replicating SQLite databases across multiple servers. Created by the team at Fly.io, it works by mounting a FUSE filesystem that intercepts SQLite writes and streams them to replica nodes in real time. This lets applications use SQLite as their database while gaining the availability benefits of multi-node replication, without changing application code.

What LiteFS Does

• Replicates SQLite databases across multiple nodes using a FUSE filesystem layer
• Streams write-ahead log (WAL) frames from the primary to replicas in near real time
• Provides automatic primary election and failover using a configurable lease system
• Proxies write requests from replicas to the primary node transparently
• Supports point-in-time backup and restore through continuous WAL archiving

Architecture Overview

LiteFS sits between your application and the SQLite database file as a FUSE mount. When the application writes to the database, LiteFS intercepts the WAL frames at the filesystem level and forwards them to replica nodes over HTTP. Each node maintains its own copy of the database file. A lease-based system determines which node is the primary (the only one accepting writes). Replicas can serve read queries directly from their local copy, providing read scaling. The primary election can be managed by Consul, a static config, or Fly.io's built-in lease system.

Self-Hosting & Configuration

• Download the LiteFS binary and place it in your PATH; no compilation required
• Create a litefs.yml config specifying the FUSE mount point, data directory, and lease settings
• Run litefs mount to start the FUSE filesystem; your application reads/writes SQLite files from the mount point
• Configure Consul as the lease backend for automatic failover in production clusters
• Use litefs import and litefs export for backup and migration workflows

Key Features

• Zero application changes: any app that uses SQLite works with LiteFS out of the box
• Near real-time replication with sub-second lag from primary to replicas
• Read scaling by directing read traffic to any replica in the cluster
• Automatic failover when the primary becomes unavailable (with Consul lease backend)
• Small operational footprint: a single static binary with no additional dependencies

Comparison with Similar Tools

• Litestream — continuously backs up SQLite to S3 but does not provide live replicas; LiteFS provides real-time multi-node replication
• rqlite — distributed SQLite using Raft consensus; LiteFS uses primary-replica replication which is simpler and lower latency
• DQLite — embeds Raft into the SQLite VFS; LiteFS uses FUSE and works with unmodified SQLite
• PostgreSQL streaming replication — requires switching from SQLite; LiteFS lets you keep SQLite
• CockroachDB / TiDB — distributed SQL databases for large-scale workloads; LiteFS is for applications that prefer SQLite's simplicity

FAQ

Q: Does LiteFS work with any SQLite library or ORM? A: Yes. LiteFS operates at the filesystem level, so any application or library that reads and writes standard SQLite database files works without modification.

Q: Can replicas accept write queries? A: Replicas can optionally proxy write requests to the primary node using the built-in HTTP proxy, making writes transparent from the application's perspective.

Q: How much replication lag should I expect? A: Typically under 100 milliseconds for nodes in the same region. Cross-region replication lag depends on network latency between nodes.

Q: Does LiteFS handle concurrent writers? A: SQLite allows only one writer at a time, and LiteFS enforces this by designating a single primary node for writes. Read concurrency is unlimited across all nodes.

Sources

• https://github.com/superfly/litefs
• https://fly.io/docs/litefs/