Dqlite internals

Dqlite (distributed SQLite) implements a replicated SQLite database by combining the SQLite engine with a Raft-based consensus layer. Each LXD daemon (cluster member) runs a Dqlite node which exposes a SQLite-like API backed by a Raft replicated state machine. A single leader handles writes; followers apply replicated log entries and serve reads depending on configuration.

Raft

Raft is a consensus algorithm that ensures a cluster of nodes can agree on a sequence of state machine commands even in the presence of failures. Raft handles leader election, log replication, safety, and membership changes.

Dqlite Raft implementation

Raft nodes in Dqlite move between four runtime states: RAFT_UNAVAILABLE, RAFT_FOLLOWER, RAFT_CANDIDATE and RAFT_LEADER. Followers are passive: they accept AppendEntries RPCs (remote procedure calls) from an active leader and reset an election timer; when a follower’s randomized election timeout elapses without leader contact it becomes a candidate, increments its term and sends RequestVote RPCs to gather votes. A candidate becomes leader after receiving votes from a majority of voting servers and then starts replicating log entries to followers using AppendEntries (heartbeats are empty AppendEntries used to maintain authority).

The election timeout is randomized, but always shorter than the heartbeat interval. Features such as pre-vote and explicit leadership transfer ensure reliable handover even if all servers cannot vote. Leaders also step down if they lose contact with a majority of voters. The Dqlite raft roles control whether a server participates in quorum and elections.

For more information on the Canonical Dqlite Raft implementation, see dqlite/src/raft.h and Dqlite replication.

Dqlite raft roles

  1. RAFT_VOTER: Replicates the log and participates in quorum/elections.

  2. RAFT_STANDBY: Replicates the log but does not participate in quorum/elections.

  3. RAFT_SPARE: Does not replicate the log and does not participate in quorum/elections.

LXD cluster roles

  1. database: Assigned to cluster members with the RAFT_VOTER role.

  2. database-standby: Assigned to cluster members with the RAFT_STANDBY role.

  3. database-leader: Assigned to the current Raft leader.