RTFM · Healthchecks

lb.saphira.mysql: does the database speak first?

MySQL servers greet every client before you ever log in: they announce their protocol version and server version in the initial handshake. This check reads that greeting, and leaves politely via COM_QUIT, having authenticated to nobody.

What it proves

A genuine MySQL server on the other end: the 4-byte packet header, protocol version 10, and a readable server version string are all parsed. Optionally the version string must match a regex, which lets you prove not just "a MySQL is listening" but "this node is the version we deployed".

No authentication, no query. The check never touches a database, a table, or a user; it reads the same greeting packet every client sees and says goodbye.

How it works

The probe engine reads exactly the handshake payload length it is told, validates the protocol byte, decodes the version string (latin-1), and sends COM_QUIT so the server sees a clean client departure instead of a dropped socket.

Configuration

Knobs
Variable	Default	Meaning
LB_SAPHIRA_MYSQL_VERSION	-	Regex the server version string must match, e.g. ^8\.4
LB_SAPHIRA_TIMEOUT	3	Handshake deadline
(target port)	$4, else 3306	Any port mysqld or a compatible server listens on

Wiring it up

ldirectord

# ldirectord.cf - read-replica pool
virtual = 203.0.113.10:3306
    protocol = tcp
    scheduler = lc
    real = 192.168.20.101:3306 gate 1
    real = 192.168.20.102:3306 gate 1
    checktype = external
    checkcommand = "/var/lib/lb/saphira/lb.saphira.mysql"

Pin the major version

# /etc/saphira/lb-healthchecks.d/mysql.conf
LB_SAPHIRA_MYSQL_VERSION=^8\.4

Run it by hand

Manual run

/var/lib/lb/saphira/lb.saphira.mysql db-pool 3306 192.168.20.101 3306
echo $?
# 0 = protocol-10 handshake parsed
# 1 = wrong protocol, version regex mismatch, or no handshake

Failure modes

TCP accepted, no handshake; something proxies the port but the database is unreachable behind it
Version regex mismatch: a node rejoined the pool on the wrong release; the balancer can hold it out until you decide
Note honestly: a healthy handshake does not prove the storage engine can serve queries; pair with monitoring for deep health

Did we miss something?

If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.

Send feedback or request a new section →

Prefer not to do it yourself?

Everything needed to do the work yourself is documented here and remains free; we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.

Ask about professional support →