Distributed SQLite with Raft

High Availability Patterns Using Raft Consensus, Quorum Commits, and Failover

SQLite is single-node by design. It does not include replication, leader election, or failover. If you need high availability with strong consistency, you must add an external coordination layer. Raft is the correct consensus algorithm for this job. It provides leader election, log replication, quorum commits, and split-brain prevention.

In this article, you will deploy a real 3-node distributed SQLite cluster using rqlite, observe leader election, and understand how high availability is achieved in practice.

For a refresher on how SQLite handles locking and transactions first, read Mastering Transactions and Concurrency

What “Distributed SQLite with Raft” Means

A correct distributed SQLite design follows these rules:

1. Only one node accepts writes at a time

2. Writes are appended to a replicated Raft log

3. A write is committed only after a quorum acknowledges it

4. All nodes apply log entries in the same order

5. Nodes without quorum cannot accept writes

This is how split-brain is prevented.

rqlite implements this model using SQLite as the storage engine and Raft as the consensus layer.

Why rqlite

rqlite is a production-proven distributed database built on SQLite and Raft.

What it provides:

• Automatic leader election

• Strongly consistent writes

• Log replication and snapshotting

  • Simple HTTP API

What it does not provide:

• Multi-leader writes

• Native ANN indexes

• Infinite horizontal scaling

Project documentation:
https://rqlite.io/docs/

Cluster Requirements

Minimum recommended setup:

• 3 nodes

• Stable network between nodes

• Odd number of voters

Never deploy a 2-node cluster. It cannot form a quorum during failures.

Step 1: Install rqlite

On each node:

curl -L https://github.com/rqlite/rqlite/releases/latest/download/rqlited-linux-amd64 \
  -o rqlited
chmod +x rqlited
sudo mv rqlited /usr/local/bin/

Verify:

rqlited --version

Step 2: Start the First Node (Bootstrap Leader)

On node1:

rqlited \
  -node-id node1 \
  -http-addr 0.0.0.0:4001 \
  -raft-addr 0.0.0.0:4002 \
  -bootstrap-expect 3 \
  /var/lib/rqlite

This node waits until two more nodes join before forming a cluster.

Step 3: Start the Remaining Nodes

On node2:

rqlited \
  -node-id node2 \
  -http-addr 0.0.0.0:4001 \
  -raft-addr 0.0.0.0:4002 \
  -join http://node1:4001 \
  /var/lib/rqlite

On node3:

rqlited \
  -node-id node3 \
  -http-addr 0.0.0.0:4001 \
  -raft-addr 0.0.0.0:4002 \
  -join http://node1:4001 \
  /var/lib/rqlite

Once all nodes are up, Raft elects a leader automatically.

Step 4: Verify Cluster State

Run on any node:

curl http://localhost:4001/status

Look for:

• leader

• peers

• commit_index

Only the leader accepts writes.

Step 5: Execute Writes Safely

Create a table:

curl -X POST http://localhost:4001/db/execute \
  -H "Content-Type: application/json" \
  -d '{
    "statements": [
      "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
    ]
  }'

Insert data:

curl -X POST http://localhost:4001/db/execute \
  -H "Content-Type: application/json" \
  -d '{
    "statements": [
      "INSERT INTO users (name) VALUES (\"Alice\")"
    ]
  }'

The write is committed only after a quorum confirms it.

Step 6: Read Data from Any Node

curl http://localhost:4001/db/query?q=SELECT+*+FROM+users

Reads can be served by followers, depending on consistency settings.

Leader Failure Test

Stop the leader process.

Within seconds:

• A new leader is elected

• Writes resume automatically

• No data is lost

This behavior is the direct result of Raft quorum rules.

Design reference:
https://rqlite.io/docs/design/

How Split-Brain Is Prevented

Split-brain is prevented by quorum enforcement.

Rules:

• Majority must acknowledge commits

• Minority partitions cannot commit

• Old leaders step down if quorum is lost

This guarantees a single source of truth.

Deep dive:
https://philipotoole.com/replicating-sqlite-using-raft-consensus/

Snapshotting and Log Growth

Raft logs grow over time. rqlite periodically:

• Creates SQLite snapshots

• Truncates old log entries

This keeps disk usage bounded and recovery fast.

Operational Best Practices

• Use 3 or 5 nodes only

• Monitor leader changes

• Back up snapshots regularly

• Treat replication as availability, not backup

• Do not bypass rqlite to write directly to SQLite files

What This Architecture Is Not

This does not turn SQLite into:

• A multi-writer system

• A global-scale distributed database

It turns SQLite into:

• A strongly consistent, highly available datastore

• With clear operational boundaries

Subscribe Now

If you found this useful and want more real, execution-focused SQLite content, subscribe to SQLite Forum.

Upcoming topics include:

• Failure testing distributed SQLite clusters

• Backup and restore strategies for HA SQLite

• Integrating distributed SQLite with web applications

• When to stop scaling SQLite and move on

Subscribe to get new articles delivered directly, without noise.