# rqlite — Distributed Database Built on SQLite & Raft

> Lightweight distributed relational database that replicates SQLite across nodes using the Raft consensus protocol.

## Install

Save in your project root:

# rqlite — Distributed Relational Database on SQLite + Raft

## Quick Use
```bash
# Start a single node
rqlited -node-id 1 ~/rqlite/node1

# Start a 3-node cluster on one host for testing
rqlited -node-id 1 -http-addr localhost:4001 -raft-addr localhost:4002 ~/node1 &
rqlited -node-id 2 -http-addr localhost:4003 -raft-addr localhost:4004 -join http://localhost:4001 ~/node2 &
rqlited -node-id 3 -http-addr localhost:4005 -raft-addr localhost:4006 -join http://localhost:4001 ~/node3 &

# Write and read over HTTP
curl -XPOST localhost:4001/db/execute -d '[["CREATE TABLE foo (id INTEGER PRIMARY KEY, name TEXT)"]]'
curl -G localhost:4001/db/query --data-urlencode 'q=SELECT * FROM foo'
```

## Introduction
rqlite turns the tiny, battle-tested SQLite engine into a fault-tolerant distributed database. Each node wraps SQLite with the Raft consensus protocol, replicating writes to a cluster of 3, 5, or 7 nodes. It is ideal when you want relational guarantees and easy operations, without the complexity of running Postgres or MySQL clusters.

## What rqlite Does
- Replicates a SQLite database across nodes with strong consistency via Raft.
- Serves SQL over a simple HTTP/JSON API plus a native command-line shell.
- Supports automatic leader election, node joining, and online snapshots.
- Offers read-consistency levels (none / weak / strong / linearizable) per request.
- Ships tiny single-binary releases with no external dependencies.

## Architecture Overview
Every rqlite node runs an embedded SQLite engine plus a Raft FSM. Writes go through the leader, are appended to a durable Raft log, replicated to followers, and then applied to each local SQLite file. Reads can be served locally for low latency, or routed to the leader for strong reads. Snapshots compact the log by taking consistent SQLite backups, which new nodes stream on join.

## Self-Hosting & Configuration
- Install via release binary, Docker image `rqlite/rqlite`, or Homebrew `brew install rqlite`.
- Typical deployment is an odd-sized cluster (3 or 5) to tolerate node failures.
- TLS is supported end-to-end between clients and between nodes via `-http-cert`, `-node-cert`.
- Authentication uses a JSON credentials file with per-user permissions and roles.
- Backups: `/db/backup` streams a hot SQLite file; `/db/load` reloads a SQL or SQLite dump.

## Key Features
- Single static Go binary with a SQLite database and Raft in one process.
- HTTPS JSON API plus an interactive shell (`rqlite` CLI) that understands transactions.
- Queued writes, batched writes, and parameterized statements reduce round trips.
- Read-after-write and linearizable consistency on demand, per request.
- Works on ARM (Raspberry Pi), cloud VMs, and Kubernetes StatefulSets alike.

## Comparison with Similar Tools
- **Raw SQLite** — Single-node only; rqlite adds Raft replication and HA.
- **Litestream** — Streams WAL to object storage for backup; rqlite provides live multi-node writes.
- **etcd** — Key-value; rqlite is full SQL with indexes, joins, and transactions.
- **CockroachDB** — Distributed SQL at massive scale; rqlite is much lighter for small-to-medium fleets.
- **dqlite** (Canonical) — Embedded library; rqlite is a ready-to-run service plus HTTP API.

## FAQ
**Q:** How many nodes should I run?
A: Odd numbers — 3 nodes tolerate 1 failure, 5 tolerate 2. More than 7 is rarely useful.

**Q:** Is it fast enough for production writes?
A: Writes are bounded by Raft round-trips; 1–5 ms LAN latency typically yields thousands of TX/s when batched.

**Q:** Can I use existing SQLite tooling?
A: Yes. You can take hot backups with `/db/backup` and open them with any SQLite client.

**Q:** What happens during a leader failure?
A: A new leader is elected automatically in a few hundred milliseconds; clients transparently retry via the HTTP API.

## Sources
- https://github.com/rqlite/rqlite
- https://rqlite.io

---
Source: https://tokrepo.com/en/workflows/44ddef49-3931-11f1-9bc6-00163e2b0d79
Author: AI Open Source