Rqlite 10 2 4

rqlite 10.2.4

Overview

rqlite is a lightweight, fault-tolerant, distributed relational database built on SQLite with Raft consensus. It provides full SQL support (including FTS5, JSON1) in a single binary with no external dependencies. The architecture is:

• SQLite — storage engine (WAL mode, SYNCHRONOUS=off; Raft provides durability)
• Raft — consensus via hashicorp/raft for replication and leader election
• HTTP API — RESTful interface on port 4001 (default)
• Raft TCP — inter-node communication on port 4002 (default)

Three binaries are built: rqlited (server), rqlite (CLI client), rqbench (benchmarking).

Data Flow

• Writes: HTTP → Raft consensus → FSM applies to SQLite → response
• Reads: HTTP → consistency check → query SQLite → response

Quorum requires (N/2)+1 nodes: 3-node cluster tolerates 1 failure, 5-node tolerates 2.

Usage

Quick Start (Docker)

# Single node
docker run -d --name rqlite -p 4001:4001 -v rqlite:/rqlite/file rqlite/rqlite

# Query via HTTP
curl -XPOST 'localhost:4001/db/execute?pretty' \
  -H 'Content-Type: application/json' \
  -d '["CREATE TABLE foo (id INTEGER PRIMARY KEY, name TEXT)"]'

curl -G 'localhost:4001/db/query?pretty' --data-urlencode 'q=SELECT * FROM foo'

Quick Start (Binary)

# Download binary from https://github.com/rqlite/rqlite/releases/tag/v10.2.4
mkdir /opt/rqlite && tar xzf rqlite_linux_amd64.tar.gz -C /opt/rqlite
/opt/rqlite/rqlited -http-addr 0.0.0.0:4001 -raft-addr 0.0.0.0:4002 /data/rqlite

CLI Usage

# Connect to local node (default http://127.0.0.1:4001)
rqlite

# Connect to remote node
rqlite -H 10.0.0.1 -p 4001

# HTTPS with insecure skip
rqlite -s https -i -H 10.0.0.1 -p 4001

# With basic auth
rqlite -u admin:password -H 10.0.0.1 -p 4001

# Using RQLITE_HOST env var
RQLITE_HOST=https://10.0.0.1:4001 rqlite -i

Inside the CLI, use dot commands:

HTTP API Endpoints

Execute Request

# Single statement
curl -XPOST 'http://localhost:4001/db/execute' \
  -H 'Content-Type: application/json' \
  -d '{"statements": [{"sql": "CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)"}]}'

# Multiple statements (atomic batch — single Raft entry)
curl -XPOST 'http://localhost:4001/db/execute?pretty' \
  -H 'Content-Type: application/json' \
  -d '[
    "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
    "INSERT INTO users VALUES(1, ''alice'')"
  ]'

# With transaction wrapping
curl -XPOST 'http://localhost:4001/db/execute?transaction' \
  -H 'Content-Type: application/json' -d '["UPDATE t SET v=1", "UPDATE t SET v=2"]'

# Queued writes (returns immediately, batched automatically — much higher throughput)
curl -XPOST 'http://localhost:4001/db/execute?queue' \
  -H 'Content-Type: application/json' -d '["INSERT INTO t VALUES(1)"]'

# With timing info
curl -XPOST 'http://localhost:4001/db/execute?timings' \
  -H 'Content-Type: application/json' -d '["SELECT * FROM t"]'

# Associative JSON output (column names as keys)
curl -XPOST 'http://localhost:4001/db/execute?associative' \
  -H 'Content-Type: application/json' -d '["SELECT * FROM t"]'

# Include Raft index in response
curl -XPOST 'http://localhost:4001/db/execute?raft_index' \
  -H 'Content-Type: application/json' -d '["INSERT INTO t VALUES(1)"]'

Query Request

# Basic query (use GET with url-encoded q parameter)
curl -G 'http://localhost:4001/db/query?pretty' --data-urlencode 'q=SELECT * FROM t'

# With consistency level
curl -G 'http://localhost:4001/db/query?level=linearizable' --data-urlencode 'q=SELECT * FROM t'

# POST with JSON body
curl -XPOST 'http://localhost:4001/db/query' \
  -H 'Content-Type: application/json' \
  -d '{"queries": [{"sql": "SELECT * FROM t"}]}'

# With freshness bound (for level=none)
curl -G 'http://localhost:4001/db/query?level=none&freshness=5s' --data-urlencode 'q=SELECT * FROM t'

# Qualify columns with table names
curl -G 'http://localhost:4001/db/query?qualify_columns' --data-urlencode 'q=SELECT * FROM t JOIN u ON t.id=u.id'

Read Consistency Levels

Set via ?level= query parameter or .consistency CLI command:

For level=none, use ?freshness=DURATION to ensure the node has been leader within that window. Add freshness_strict for strict enforcement.

Queued Writes

Append ?queue to /db/execute. Returns immediately; writes are batched and applied asynchronously. Default queue: capacity 1024, batch size 128, timeout 50ms. Configure with -write-queue-capacity, -write-queue-batch-size, -write-queue-timeout, -write-queue-tx.

Non-deterministic Functions

RANDOM() and datetime('now') are automatically rewritten before Raft log storage to ensure identical results across replicas. Disable rewriting with ?norwrandom or ?norwtime.

Gotchas

• HTTP and Raft addresses must use different ports — binding both to the same port fails validation. Use 4001/4002 convention.
• Advertised addresses must be routable — 0.0.0.0 is valid for bind but not for advertised address. Use -http-adv-addr and -raft-adv-addr in containers/Kubernetes.
• /boot only works on single-node setups — it bypasses Raft. For clusters, use /db/load instead.
• Non-voting nodes cannot use CDC — Change Data Capture requires voting nodes only.
• DNS/dns-srv discovery requires -bootstrap-expect N — voting nodes using DNS discovery must specify expected cluster size.
• -join and -disco-mode are mutually exclusive — choose one clustering method.
• Auto-restore cannot be combined with -join — a node either boots from backup or joins existing cluster.
• SQLite runs with SYNCHRONOUS=off — durability comes from Raft fsync, not SQLite. Do not rely on SQLite-level durability guarantees.
• RANDOM() and time functions are rewritten — results may differ from standalone SQLite. Use ?norwrandom/?norwtime if you need raw SQLite behavior.
• Queued writes trade durability for throughput — data is acknowledged before Raft commitment. A leader crash before commit could lose queued writes.
• Foreign keys are disabled by default — enable with -fk flag on rqlited.
• mTLS requires both cert and key — -http-cert and -http-key must be set together (same for node certs).
• CDC only captures INSERT/UPDATE/DELETE — DDL changes (CREATE, ALTER, DROP) are not captured.
• Backup with ?vacuum triggers VACUUM before backup — this blocks writes during vacuum; use carefully on busy nodes.
• Leader stepdown waits for new election by default (?wait=true) — omit wait for immediate stepdown without waiting.

References

• 01-http-api — Full HTTP API reference with all query parameters and response formats
• 02-server-flags — Complete rqlited configuration flags reference
• 03-clustering — Clustering setup: manual join, DNS, Consul, etcd, Kubernetes
• 04-security — Authentication file format, TLS/mTLS configuration, permissions
• 05-backups — Backup strategies, auto-backup to S3/GCS/MinIO, restore procedures
• 06-cdc — Change Data Capture configuration and event format
• 07-extensions — Loading SQLite extensions (sqlite-vec, sqlean, sqliteai)