Skip to content

The Database Connection

What is this?

Every model query runs through one Connection object, reachable as db(). It is opened lazily on the first query, kept alive across the request, and re-opened by itself when the server drops it. This page covers the settings that shape it. All of them live in z_config/z_settings.ini (see Booter Settings) and all of them are optional apart from the endpoint and credentials below. For raw access, db()->getDatabaseConnection() returns the mysqli handle (e.g. for affected_rows), and executeMultiQuery() runs several statements without binding, bypassing the debug bar and slow-query log. It throws on failure; with $throwOnFailure = false it returns false instead.

Endpoint and credentials

dbhost = database.example.com
dbport = 3306
dbname = app
dbusername = app
dbpassword = secret

dbhost, dbusername, dbpassword and dbname are required. If any of them is missing or empty, the first query throws a RuntimeException (Database connection requires valid configuration. Missing or empty config key(s): ...) naming the offending keys. None of them has a default, and dbpassword in particular must be non-empty: an account without a password is rejected, not connected to.

dbport is optional and has no framework default: when it is unset the driver's own default (3306) applies. It is honoured by the runtime connection and by migrations alike.

dbhost may also carry the port (host:3306), except with db_ssl turned on: the server certificate is matched against dbhost as a whole, and no certificate names a port, so with TLS the port belongs in dbport and a combined value is rejected with an error saying exactly that.

Migrations connect separately (through Doctrine DBAL) but read the same settings, so there is nothing to configure twice.

Migrations, and the seed, status, sync, unlock, repair-collation and hashing-migration commands, log in with dbusername_elevated and dbpassword_elevated when both are set. If either is empty, they use dbusername and dbpassword. The console builds every command, so the elevated login applies to each CLI invocation, run included. The switch happens at CLI startup for every command (including run) and lasts for the whole process, so models use the elevated user too.

Timeouts and retries

db_connection_timeout = 900
db_max_retries = 3
db_wait_attempts = 10
db_wait_delay = 3

db_connection_timeout is the number of seconds after which an idle connection is checked before being reused (0 checks before every query; a non-numeric value throws an InvalidArgumentException at boot). Manual heartbeat() calls (also on models) are deprecated since 1.2.0 and can be removed.

db_max_retries is how many extra attempts a statement gets when it fails for a reason that is worth retrying: a deadlock, a lock-wait timeout, a Galera certification conflict, or a dropped connection (which is recovered by reconnecting through the endpoint and re-running the statement; each connect attempt times out after 5 seconds). Set it to 0 to disable retries entirely. executeMultiQuery() is never retried.

One statement may be applied twice

If a write reached the server but the acknowledgment was lost with the connection, the retry applies it again. Every exec() auto-commits, so the exposure is a single statement.

db_wait_attempts and db_wait_delay (seconds) bound how long the database commands wait for a database that is still starting; --no-wait fails at once.

Encrypted transport (TLS)

Clusters that reject unencrypted clients (MariaDB's require_secure_transport, or anything reachable over a public network) need this turned on:

db_ssl = true

That is the whole configuration: the server certificate is verified against the trust store your system already uses, which knows every publicly issued certificate (for example Let's Encrypt). A private or self-signed authority is added to that same store (on Debian: drop it into /usr/local/share/ca-certificates/ and run update-ca-certificates), or handed to PHP via openssl.cafile.

The certificate is always verified. That is worth a sentence, because mysqli itself is lax here: given no authority it encrypts without verifying, and it never consults the system trust store on its own. The framework resolves that store for you so that db_ssl = true means verified, and raises an error rather than connecting unverified when no trust store can be found.

Persistent connections

db_persistent = true

A persistent connection is kept open by the PHP worker after the request ends and handed to the next request, which skips the TCP, TLS and authentication handshake (measured against the e2e cluster: about 2.2 ms per encrypted connect versus 0.2 ms per reuse). It is safe to reuse: mysqli resets the session before handing it over and replaces a connection that no longer answers, so a node that died does not poison the pool.

It is off by default because of placement: a worker stays on whichever node it first reached, so a load-balanced cluster only rebalances as workers recycle. Turn it on where the handshake actually costs you, an encrypted or remote database being the typical case.

Restart your PHP workers after changing db_ssl

mysqli pools connections by host, port, user, password and database, not by transport, so a worker still holding a plaintext connection keeps using it after you turn db_ssl on. Reload PHP-FPM (or your web server) when you change the transport.