rqlite 6 removes replicated address metadata from request routing

A follower can know who the Raft leader is without knowing the URL to which it should send an HTTP client. Before rqlite 6, nodes solved that second problem with replicated metadata containing their HTTP API addresses. The June 8 release of rqlite 6.0.0 replaces that arrangement. A node now asks the relevant node for its API address when it needs it, using the TCP port already open for Raft communication.

The release-tagged changelog explains the reason. The old metadata required extra replicated state alongside SQLite data. If that metadata disagreed with Raft state, the cluster could operate in a degraded condition. Removing the metadata component removes that particular opportunity for disagreement. It also breaks communication compatibility with earlier nodes that still depend on metadata updates.

I value rqlite's relatively small amount of machinery around replicated relational data. This change is interesting because it reduces the state the system must keep consistent. The cost is a deliberate cluster-upgrade boundary, even though applications keep the same data API.

Two addresses describe different interfaces

The Raft address identifies the cluster communication endpoint. The HTTP API address identifies the endpoint a client uses for queries and writes. They are related to the same node, but they are not interchangeable strings. A follower routing a client needs a way to connect its knowledge of the current leader to the API address that leader advertises.

In the 5.x design, every node wrote address metadata into the Raft log. Followers could use the replicated information to find the leader's HTTP endpoint. That turned address discovery into another piece of state whose correspondence with the consensus system had to remain correct. It also meant that maintaining database state was not the only responsibility of the replicated-state machinery.

Version 6 removes that metadata. Its HTTP service asks the store for the leader's Raft address, then asks the cluster service for the API address at that node. The sequence is visible in LeaderAPIAddr in the tagged HTTP service. A failure in either step returns no API address through that helper.

This sequence does not make leadership immutable while a client follows a redirect. It does remove the old metadata lookup as an independent source of stale mapping. The address request uses the current cluster communication path instead of trusting a second replicated directory to remain aligned with it.

One TCP port carries two kinds of traffic

The cluster service implementation defines separate multiplexing headers for Raft traffic and cluster-state requests. Raft uses the value 1, while the cluster service uses 2. The multiplexing layer can distinguish the purpose of a connection arriving through the shared port.

That is the mechanism behind the release's claim that address lookup does not require another open TCP port. The service adds a request type over an existing inter-node listener. It does not ask deployments to expose an additional address-discovery service with a separate port and reachability policy.

The address request itself uses a Protobuf command identifying a node-API-URL lookup. The caller dials the target node, writes the encoded request length and command, then reads a response containing an address. To build the URL, the server uses its configured API address and whether it serves HTTPS. That keeps the URL scheme part of the response instead of making the caller infer it from the Raft transport.

This is a small protocol with a specific purpose. It discovers an API address. It does not transport arbitrary SQL through the same command, and it does not replace Raft consensus with an address-query mechanism. Keeping that scope clear helps avoid overstating what changed in the cluster communication design.

A live lookup replaces maintained directory state

The new lookup can fail if the caller cannot reach the target node. The release argues that it reuses the same port needed for Raft connections, so it does not introduce another network dependency. That is a narrower and more useful claim than saying a network request cannot fail.

The source reports errors for dialing, command encoding, writing the request, reading the response, and decoding it. Those are observable stages of address lookup. Removing metadata inconsistency does not remove ordinary transport failures. It changes the information source and the state the system needs to maintain.

The HTTP helper's behavior reinforces this distinction. It returns an empty address when lookup fails. It does not silently manufacture a URL from an unrelated local address. A caller higher in the request path must still handle inability to discover the leader endpoint.

I prefer the live lookup for this particular piece of information because it removes replicated configuration that the database does not otherwise need. The operational argument is specific, the service no longer has to maintain a separate address directory whose contents can disagree with Raft's view of the cluster.

Membership reporting also becomes a live observation

The release changes the /nodes API to report real-time status of other cluster nodes. The HTTP implementation initializes their API addresses as unavailable, then issues address requests to the nodes. Successful responses fill in the map. In the source comment, reachable means that a node responds to a simple network request.

That definition matters when consuming the output. A successful response is evidence that this lookup reached a node. It is not a claim that every database operation will succeed, nor is it an enduring promise about the network. The observed status belongs to the request that collected it.

The same release adds .sysdump to the CLI and displays more build information. Those additions support diagnosis around the changed cluster behavior. The changelog also removes the redirect key from HTTP status output. Applications and monitoring tools reading diagnostics therefore have a separate compatibility detail to consider alongside the main data API.

Existing clusters need an explicit migration

The changelog states that earlier software cannot communicate with 6.0 nodes because the new version no longer performs metadata updates. Its documented upgrade procedure is to back up the leader and restore the database dump into a new 6.0 cluster. A mixed-version rolling replacement is not the upgrade method described for this boundary.

This is a substantial distinction from client compatibility. The release says the data and cluster-management APIs remain unchanged, so clients should not need changes for those interfaces. That does not mean an existing cluster's persisted state and inter-node protocol can be upgraded by replacing one executable at a time.

The backup documentation at the 6.0 tag distinguishes a binary SQLite backup from a SQL text dump. Its SQL form uses fmt=sql on the backup endpoint. The restore documentation in the same tag accepts the SQL dump at /db/load with a text/plain content type.

curl -s 'http://old-leader:4001/db/backup?fmt=sql' -o backup.sql
curl -X POST 'http://new-leader:4001/db/load' \
  -H 'Content-type: text/plain' --data-binary @backup.sql

These commands illustrate the documented formats and use placeholder hosts. The restore target must be an empty or new cluster. The tagged restore documentation explicitly says behavior with existing data is undefined and warns that a SQLite binary backup is not the accepted input for this restore path. A dump can also contain a statement disabling foreign-key checks, which the documentation calls out separately.

The format distinction is part of the upgrade design, not a minor command-line preference. The migration moves logical database contents into a newly formed cluster whose nodes agree on the new communication behavior. It does not carry the old metadata mechanism forward merely because the application's relational data remains the same.

The change reduces one consistency obligation

The main benefit of rqlite 6 is therefore specific. A follower still needs to discover where a client should send a leader-dependent request. It now obtains that address through an inter-node query, and the shared listener avoids another exposed port. The project removes the replicated metadata component that previously connected those facts.

That leaves Raft responsible for consensus and SQLite responsible for relational execution, while address lookup has a smaller direct protocol. Existing clients retain their data interface, but existing clusters cross a migration boundary. The release makes those two compatibility decisions separately, which is necessary to understand both the simpler routing model and the work required to adopt it.