rqlite 5.0 requires a new cluster for the Raft upgrade

A stable database API does not guarantee that two database versions can participate in the same replicated cluster. rqlite 5.0.0 preserves its HTTP query and insert interface while moving to HashiCorp Raft v1.1.1. Its Raft system is incompatible with the 4.x series. The documented upgrade exports the old leader's database and restores the SQL dump into a new 5.0 cluster.

That boundary is the main operational fact of this release. The client-facing request can remain familiar while the machinery agreeing on its execution changes incompatibly. Replacing binaries one node at a time inside the old cluster is not the migration described by the release. The relational data must move into a newly formed cluster running the new consensus implementation.

I value rqlite's use of SQLite because it gives that migration a conventional data representation. The transfer does not need to preserve every internal consensus record to retain the application's tables. A SQL dump can express the relational state, while the destination establishes its own cluster membership and replicated history.

The dependency change reaches durable state

The 5.0.0 changelog states the incompatibility explicitly and directs operators to back up the 4.x leader. The module requirements identify HashiCorp Raft v1.1.1 as the selected direct requirement. This is a change to a central database dependency, not merely a client library update.

The distinction is important because rqlite's local SQLite database is only part of a node's state. The release-pinned store implementation describes rebuilding an on-disk database from a snapshot and committed log entries. When opening that local database, it removes the previous SQLite file before reconstruction. Installing an arbitrary SQLite file beneath the process would therefore not establish the intended new replicated state.

The durable consensus records have their own lifecycle. The design document at this release explains that rqlite snapshots SQLite after a configurable number of changes and truncates the Raft log. A snapshot and subsequent log entries together support continued operation. That internal compaction mechanism is different from the SQL export used to migrate between incompatible cluster versions.

The migration consequently crosses a clear representation boundary. Export retains database content in a form the receiving service can load. A new cluster creates the consensus state appropriate to its own implementation. Copying the old node's whole data directory would carry precisely the internal state that the incompatibility prevents treating as an ordinary in-place upgrade.

Select the export format deliberately

The changelog says to restore a database dump into the new cluster. The 5.0 restoration documentation clarifies that the load interface accepts SQL statements, not a binary SQLite backup. Its examples convert a SQLite file using the SQLite command-line program's .dump operation before posting the resulting text.

For a binary backup already obtained from the old leader, that conversion can be written as a single shell command.

sqlite3 old-leader.sqlite3 '.dump' > migration.sql

The resulting file contains SQL text. A filename suffix alone does not provide the conversion. The new service needs the sequence of schema and data statements, rather than bytes that it would have to interpret as an installed SQLite file. This distinction remains necessary even though both artifacts can represent the same tables.

The destination documentation demonstrates loading that SQL through the CLI or by posting to /db/load with a text/plain content type. It also restricts the operation to a new or empty cluster because behavior with existing data is undefined. The migration's new-cluster requirement therefore agrees with the assumptions of the restore operation itself.

.restore migration.sql

This is an interactive rqlite CLI command directed at the destination. It does not register the destination as a replica of the source cluster. It submits the exported SQL to the new service. That leaves source and destination as different database histories, even when their restored relational contents initially agree.

The transfer needs an application boundary

An export captures data for transfer, but it does not create continuous replication between the incompatible versions. Writes accepted by the old service after the chosen export are not included merely because the SQL restore later succeeds. An application's cutover procedure needs to decide which writes belong in the transferred state. This follows from the export-and-load mechanism rather than from any claim of an automated migration coordinator.

The release does not promise a period in which old and new nodes form one mixed cluster. Its instruction is to build a new cluster. Likewise, unchanged query and insert APIs do not establish a shared transaction history between the two services. API compatibility lets a client retain its request format when it changes destinations, but it does not move unexported data.

Foreign key settings are another property of the import representation. The restore documentation notes that SQLite dumps normally contain a command disabling foreign key constraints. Its discussion directs attention to re-enabling them after loading where required. A relational export includes executable statements, so operational settings influenced by those statements need to be understood as part of the import.

I prefer this explicit migration contract to treating a major dependency change as an invisible implementation detail. It identifies the old leader as the export source and a new cluster as the destination. The remaining application cutover decisions follow from transferring a finite artifact between those two services.

Node identity becomes explicit

The release also supports setting a node ID independently of its network address. Its changelog recommends doing so for production clusters. According to the cluster management documentation, IDs can be arbitrary values as long as every node has a unique one.

A first node can therefore start with a deliberate identity and explicit API and Raft addresses. A second node uses a different identity and joins through the first node's HTTP endpoint.

rqlited -node-id node-a -http-addr host1:4001 -raft-addr host1:4002 ./node-a
rqlited -node-id node-b -http-addr host2:4001 -raft-addr host2:4002 -join http://host1:4001 ./node-b

These commands illustrate the documented topology on separate hosts. They are not a complete fault-tolerant deployment. The cluster guide explains that three nodes can tolerate one failure because agreement requires a majority. Starting two nodes establishes membership but does not provide that three-node failure allowance.

The store's join code passes both a server ID and a server address to Raft's AddVoter operation. It checks existing membership using both values. If the ID and address already match, the join returns without adding a duplicate. The code therefore treats identity and contact location as distinct information even when the default identity derives from an address.

The cluster guide also documents address changes between restarts. A node with changed addresses must explicitly join again so the leader can update its record. An explicit ID makes the intended identity visible across such changes, while the join procedure updates where other nodes should contact it. Choosing a stable name does not remove the need to maintain current addressing information.

Application compatibility remains useful

Keeping the HTTP query and insert API unchanged limits the work a consuming application needs to perform. The application can continue expressing its requests through the same interface after reaching the destination service. That is a meaningful compatibility guarantee, even though cluster migration is required beneath it.

The changelog also records improvements to join error handling and leader identification. Those changes concern how the service reports and manages its consensus relationships. They belong alongside the new node ID support, but they should not be read as making the old and new Raft systems interoperable. The explicit incompatibility remains the governing upgrade rule.

The release's status changes include a features list and adjustments to key naming. Status output is therefore another interface to inspect independently of the preserved query and insert endpoints. A tool consuming diagnostic JSON may depend on details outside that narrower compatibility promise. The changelog names those diagnostic changes separately, which helps distinguish application data operations from software that interprets node metadata.

The resulting migration retains the relational representation while replacing the consensus environment around it. A dump from the old leader supplies SQL to a new, empty 5.0 cluster. Its nodes have their own identities and membership, and clients can continue using the documented query and insert API after the application directs them to that destination.