LiteFS — FUSE-Based SQLite Replication Across a Cluster

Introduction

LiteFS lets you run SQLite in production across multiple servers. It works as a FUSE file system that intercepts SQLite write-ahead log (WAL) transactions and replicates them to other nodes in real time. Applications read and write to SQLite normally while LiteFS handles distribution transparently.

What LiteFS Does

• Replicates SQLite databases across multiple nodes using FUSE interception
• Provides a single primary writer with multiple read replicas
• Supports automatic failover via Consul-based lease management
• Handles transaction-level replication for consistency guarantees
• Works transparently with any SQLite-based application

Architecture Overview

LiteFS runs as a FUSE file system that mounts over the directory containing your SQLite databases. When the application writes to SQLite, LiteFS intercepts the WAL frames and ships them to replica nodes over HTTP. One node holds the primary lease (managed via Consul or a static configuration), and only the primary accepts writes. Replicas apply received transactions to stay in sync. The application connects to the SQLite file on the FUSE mount and requires no code changes.

Self-Hosting & Configuration

• Install the litefs binary on each node in your cluster
• Create a litefs.yml configuration specifying the mount directory and lease settings
• Configure Consul or use static leases for primary election
• Run litefs mount as a background service (typically via systemd or as a Docker entrypoint)
• Point your application at the SQLite database inside the FUSE mount directory

Key Features

• Transparent replication requires zero application code changes
• Transaction-level consistency ensures replicas see complete transactions
• FUSE-based approach works with any language or framework that uses SQLite
• Built-in HTTP API for monitoring replication lag and cluster health
• Supports backup and restore through point-in-time recovery snapshots

Comparison with Similar Tools

• Litestream — Streams WAL to S3 for backup; LiteFS provides live multi-node replication
• rqlite — Raft-based distributed SQLite; LiteFS uses primary-replica model with FUSE
• libSQL/Turso — SQLite fork with built-in replication; LiteFS works with standard SQLite
• Marmot — SQLite replication via NATS; LiteFS uses direct HTTP streaming
• dqlite — Canonical's replicated SQLite library; requires code changes, LiteFS is transparent

FAQ

Q: Does LiteFS support multi-writer? A: No. LiteFS uses a single-primary model. One node accepts writes while others serve as read replicas. Write requests to replicas are forwarded to the primary.

Q: How fast is replication? A: Replication happens at the transaction level and is typically sub-second. Replicas receive and apply WAL frames as they are committed on the primary.

Q: Do I need to change my application code? A: No. LiteFS is transparent. Your application reads and writes to a normal SQLite file path. LiteFS handles replication at the filesystem level.

Q: Can I use LiteFS outside of Fly.io? A: Yes. LiteFS is open source and works on any Linux system with FUSE support. It was designed at Fly.io but is not tied to their platform.

Sources

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