LiteFS Documentation

LiteFS is composed of three primary components that enable asynchronous replication for SQLite databases:

1. FUSE file system: Intercepts file system calls to record transactions. On the primary node, it intercepts write transactions transparently. On replica nodes, it prevents writes and provides information about the current primary via a .primary file.
2. Leader election: Uses Consul sessions and a time-based lease system to ensure only one node acts as the primary at any given time. This is designed for ephemeral environments like Fly.io or Kubernetes.
3. HTTP server: An API used by replica nodes to communicate with the primary node. Replicas provide their current transaction ID and a rolling checksum to request missing transaction data.

LiteFS provides asynchronous replication, which means there is a sub-second window where transactions are only durable on the primary node. A catastrophic crash of the primary during this window may result in data loss.

Split-Brain Protection

To prevent database corruption during a network partition (split-brain) where an old primary reconnects to a new leader:

• LiteFS uses a rolling checksum representing the entire database state at every transaction.
• If an old primary reconnects and detects that its checksum differs from the new leader (even if the TXIDs match), it will automatically resnapshot the database from the new primary to ensure consistency.

Replica nodes synchronize with the primary node using an HTTP-based protocol:

1. Connection: The replica connects to the primary and specifies its current replication position using its transaction ID and a rolling checksum of its entire database.
2. Incremental Sync: The primary sends transaction data starting from the replica's reported position.
3. Snapshot Fallback: If the primary no longer has the requested transaction data available, it will send a full snapshot of the current database to the replica, and replication will resume from that point.

LiteFS is configured using a YAML file (typically litefs.yml). The configuration supports environment variable expansion, including boolean expressions for conditional logic.

LiteFS searches for the configuration file in the following order:

1. The current working directory (./litefs.yml)
2. The current user's home directory (~/litefs.yml)
3. The system configuration directory (/etc/litefs.yml)

You can also specify an explicit path to a configuration file when running the LiteFS process.

The litefs mount command mounts a LiteFS directory via FUSE and begins communicating with the LiteFS cluster. The mount becomes accessible once the node becomes the primary or connects and syncs with the primary.

LiteFS searches for a litefs.yml configuration file in the following order:

1. The present working directory
2. The current user's home directory
3. /etc/litefs.yml

You can also specify an exec command (the application you want to run) by using a double dash -- to separate LiteFS arguments from the command arguments.

LiteFS supports environment variable expansion within the YAML configuration file. It supports standard expansion as well as equality (==) and inequality (!=) expressions for conditional logic.

Supported formats:

• ${VAR}: Standard expansion.
• ${VAR} == 'value': Returns true if VAR equals 'value'.
• ${VAR} != 'value': Returns true if VAR does not equal 'value'.
• ${VAR1} == ${VAR2}: Returns true if both variables are equal.

The Server struct provides an HTTP API for LiteFS node communication, including replication streaming, database management, and cluster coordination.

To use the server:

1. Create a new server instance using NewServer with a *litefs.Store and an address string.
2. Call Listen() to start the TCP listener.
3. Call Serve() to begin handling requests.
4. Call Close() to gracefully shut down the server and its listener.

You can configure SnapshotTimeout on the Server instance to prevent slow snapshot downloads from backing up the primary node.

The http section defines settings for the LiteFS HTTP API server, which is used for node-to-node communication.

Key options:

• addr: The bind address for the HTTP API server (e.g., :20202).

http:
  addr: ":20202"

The fuse section configures the FUSE file system layer used to intercept SQLite transactions.

Key options:

• dir: (Required) The mount directory where applications access their SQLite databases.
• allow-other: If true, allows non-root users to access the mount. Note: You must first enable user_allow_other in /etc/fuse.conf on the host system.
• debug: Enables debug logging for all FUSE API calls. This produces high log volume and is not recommended for production.

fuse:
  dir: "/litefs"
  allow-other: false
  debug: false