Read replicas
This page is for database administrators in public bodies whose Exponential site runs on MySQL or MariaDB and who want to move read load off the primary server. It answers how Exponential uses replicas, which settings switch it on, what replication lag means for editors and visitors, and when replicas are worth it. The source is 9.3 MySQL and MariaDB, Replicas.
Contents
What Exponential does with replicas
With UseSlaveServer=enabled, Exponential sends read queries to a replica chosen at random per request; writes go to
Server. This is the only engine with built-in read splitting (Database support).
PostgreSQL, Oracle, MongoDB and SQLite sites do not use replicas for reads through this setting.
Replicas are a performance feature, not a failover: if the primary fails, writes fail. For availability see Database high availability.
The settings
In settings/override/site.ini.append.php, block [DatabaseSettings]. The keys really are spelled Slaver... for
user, password and database:
[DatabaseSettings]
UseSlaveServer=enabled
SlaveServerArray[]
SlaveServerArray[]=db-replica-1.example.gov
SlaveServerPort[]
SlaveServerPort[]=3306
SlaverServerUser[]
SlaverServerUser[]=<read user>
SlaverServerPassword[]
SlaverServerPassword[]=<password>
SlaverServerDatabase[]
SlaverServerDatabase[]=<database>The host name and placeholders are examples. The shipped settings/site.ini lists these keys commented out, with
UseSlaveServer=disabled. After the change clear the INI cache and make the engine read it:
php bin/php/ezcache.php --clear-tag=ini --allow-root-user
./console exp:velocity deploy --allow-root-userGive the replica user read rights only; it never needs to write. Keep the password out of version control (Configuration under version control).
Replication lag
"Replication lag means a page may show content a few seconds old" (9.3). Tell editors what to expect: right after publishing, a page read from a replica can still show the old version for a moment. Monitor the lag with your database's tools, and treat a growing lag as an incident, because visitors then see old information, which matters for notices with legal or safety weight.
When replicas help
| Situation | Replicas help? |
|---|---|
| Many anonymous visitors | usually not much: Velocity's response cache and the HTTP cache answer them without the database (Velocity response cache and HTTP cache) |
| Many signed-in users, searches, uncached pages | yes, if the database is the bottleneck |
| The primary is slow because of writes | no; replicas only take reads |
| You need a standby for continuity | not by themselves; see Database high availability |
Measure before you add a replica: exp:benchmark and the slow query output
([DatabaseSettings] SlowQueriesOutput with SQLOutput=enabled) show where time goes
(Capacity planning).
Checklist
- To do: The site runs on MySQL or MariaDB.
- To do: The replica user has read rights only; its password is not in version control.
- To do: Settings are in
settings/override, the INI cache cleared and the engine reloaded. - To do: Replication lag is monitored, and editors know about the short delay.
- To do: A measurement shows the database was the bottleneck.
Related pages
- Availability index of this folder
- MySQL for hosts, MariaDB for hosts
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.