# Rqlite 10 2 4

> Operate rqlite 10.2.4 — distributed SQLite database with Raft consensus. Use for deploying, configuring, querying, backing up, and managing rqlite clusters. Covers rqlited server flags, HTTP API (/db/execute, /db/query, /db/request), CLI (.status, .backup, .nodes), clustering (join, DNS, Consul, etcd, Kubernetes), TLS/mTLS auth, queued writes, CDC, consistency levels, and SQLite extensions. Use whenever the user mentions rqlite, distributed SQLite, Raft database, or needs a lightweight fault-tolerant relational store.

- Skill: `tangledgroup/rqlite-10-2-4` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add tangledgroup/rqlite-10-2-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tangledgroup/rqlite-10-2-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tangledgroup (https://skillmd.com/u/tangledgroup)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tangledgroup/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)

```bash
# 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)

```bash
# 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

```bash
# 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:

| Command | Description |
|---|---|
| `.help` | List all commands |
| `.status` | Node status and diagnostics |
| `.nodes [all]` | Cluster topology; `all` includes non-voters |
| `.leader` | Current Raft leader |
| `.tables` / `.indexes` / `.schema` | Database introspection |
| `.backup FILE` | Hot backup to file |
| `.restore FILE` | Restore from SQLite file or SQL dump |
| `.boot FILE` | Boot node with SQLite file (single-node only) |
| `.dump FILE [TABLES]` | SQL text dump, optionally per-table |
| `.read FILE` | Execute SQL statements from file |
| `.consistency [level]` | Set/read consistency: none, weak, linearizable, strong |
| `.mode [column\|csv\|json\|line]` | Output format |
| `.timer [on\|off]` | Show query timing |
| `.remove NODEID` | Remove node from cluster |
| `.snapshot [TRAILING_LOGS]` | Trigger Raft snapshot |
| `.reap` | Reap old snapshots and checkpoint WALs |
| `.stepdown [NODEID]` | Leader stepdown, optionally to specific node |
| `.extensions` | Loaded SQLite extensions |

### HTTP API Endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/db/execute` | POST | Write operations (INSERT, UPDATE, DELETE, CREATE) |
| `/db/query` | GET/POST | Read operations (SELECT) |
| `/db/request` | POST | Unified endpoint for reads and writes |
| `/db/backup` | GET | Hot backup (SQLite binary or SQL dump) |
| `/db/load` | POST | Load SQLite file or SQL dump into cluster |
| `/boot` | POST | Boot single node with SQLite file |
| `/status` | GET | Node status; use `?key=X` to filter |
| `/readyz` | GET | Readiness probe (200 = ready) |
| `/nodes` | GET | Cluster topology (`?nonvoters` includes read-only) |
| `/leader` | GET/POST | Get leader info or trigger stepdown |
| `/snapshot` | POST | Trigger Raft snapshot (`?trailing_logs=N`) |
| `/reap` | POST | Reap old snapshots |
| `/db/sql` | POST | SQL analysis (EXPLAIN QUERY PLAN) |

### Execute Request

```bash
# 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

```bash
# 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:

| Level | Behavior | Use Case |
|---|---|---|
| `weak` (default) | Checks local leadership state; ~1s staleness possible | General purpose, best performance |
| `linearizable` | Verifies leadership via quorum heartbeat before read | When reads must be up-to-date |
| `none` | Direct local read, no leader check; use `?freshness=5s` to bound staleness | Maximum read throughput |
| `strong` | Read goes through Raft log (slowest) | Testing and debugging |

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