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.