rqlite separates cluster connection timeout configuration

A request forwarded between database nodes can fail before its SQL ever reaches the execution path. Establishing the connection has its own deadline, separate from the work performed once that connection exists. rqlite 7.5.1, released on June 13, makes the cluster connection timeout configurable. The tagged changelog identifies this as the release's change.

The setting applies to initial non-Raft communication between nodes. It does not redefine every timeout in the database. I value rqlite's small set of operational mechanisms, and a setting with a clearly identified phase is useful. It lets an operator adjust connection establishment without assuming that a longer connection wait changes query semantics or consensus timing.

The flag names the initial connection phase

The launch configuration in 7.5.1 defines ClusterConnectTimeout for initial connections to other nodes. The command-line flag is -cluster-connect-timeout, with a default of thirty seconds. Its configuration comment explicitly limits the setting to non-Raft communications.

A node can choose another duration at launch, for example:

rqlited -cluster-connect-timeout=10s data

This changes how long that process allows for establishing the relevant inter-node connection. It is not a statement that every request will complete within ten seconds. A request may have several phases and may reuse a pooled connection rather than establish a new one.

The distinction matters when interpreting a timeout report. Failure during dialing says the caller did not obtain a usable connection through that attempt. Failure after request transmission concerns a different point in the operation. A single generic diagnosis of database slowness conceals which phase consumed the available time.

The client keeps dialing and operation deadlines separate

The cluster client stores the configured timeout when constructed. Its remote methods use that value when obtaining a connection. Individual methods also receive an operation timeout used for subsequent connection deadlines.

For example, the method fetching a node's API address first obtains a connection using the client's timeout. It then serializes a command and sends its length followed by the command body. Before writes and reads, it sets deadlines using the method's timeout argument. The initial dial and later protocol exchange therefore have distinct controls in the implementation.

The execute path follows the same initial pattern. It obtains a connection using the client's configured timeout before constructing and sending the remote execute command. That is the portion of forwarded work affected by the new configuration. The SQL's behavior and the store's execution remain outside the meaning of the connection setting.

The client also has a local-service shortcut when the target address refers to its own registered service. That path can answer without a network exchange. A setting governing remote connection establishment naturally has no role in an operation that uses the local shortcut.

The dialer covers TCP and TLS

The TCP dialer implementation constructs a network dialer with the supplied timeout. It uses that dialer for a plain TCP connection or passes it into TLS dialing, depending on the configured transport. A failure returns before the remote request protocol proceeds.

After connecting, the dialer writes a marker byte identifying the message type. It places a write deadline on that header operation using the same supplied duration. If setup fails after obtaining a connection, the deferred cleanup closes the connection. This makes successful dialing part of a small connection setup sequence, not merely a socket allocation.

These details help explain the setting's practical scope. A slow or unreachable remote endpoint can consume time before a command body is sent. Encryption also belongs to the selected setup path. The configurable duration gives the operator control over waiting in that phase without changing the higher-level request payload.

Choosing a timeout defines waiting behavior

A shorter duration can return setup failures earlier. A longer one permits more time for an endpoint that takes longer to become reachable. Neither choice makes an unreachable address correct or changes the amount of work a valid SQL statement requires. The setting governs the caller's patience for a specific operation.

This is particularly relevant in a distributed service where one node accepts an HTTP request and another performs the authoritative work. The client-facing endpoint can be available while its inter-node path is not. Exposing the connection timeout makes that internal dependency configurable, but it remains a dependency the request must satisfy.

I consider the separate control useful because its implementation matches a distinct failure boundary. The process can configure how long it waits to establish non-Raft cluster communication, while request methods retain their own deadlines for the exchange that follows. That gives an operator a more precise explanation of what a changed duration actually affects.