Download the PHP package stuttter/ludicrousdb without Composer

LudicrousDB

LudicrousDB is an advanced database interface for WordPress that supports replication, failover, load balancing, and partitioning, based on Automattic's HyperDB drop-in.

LudicrousDB began as a distribution of HyperDB and intentionally retains it as an upstream compatibility source. See HyperDB upstream parity for the audited baseline and the rules used to review later HyperDB changes.

0. Installation

Files

Copy the main ludicrousdb plugin folder and its contents to either:

• wp-content/plugins/ludicrousdb/
• wp-content/mu-plugins/ludicrousdb/

It does not matter which one; LudicrousDB will figure it out. The folder name should be exactly ludicrousdb. Be careful when you use "Download ZIP" from GitHub and unzip it.

Drop-ins

WordPress supports a few "drop-in" style plugins, used for advanced overriding of a few specific pieces of functionality.

LudicrousDB includes 3 basic database drop-ins:

• db.php <-> wp-content/db.php - Bootstrap for replacement $wpdb object
• db-error.php <-> wp-content/db-error.php - Endpoint for fatal database error output to users
• db-config.php <-> ABSPATH/db-config.php - For configuring your database environment

You'll probably want to copy these files to their respective locations, and modify them once you're comfortable with what they do and how they work.

1. Configuration

LudicrousDB can manage connections to a large number of databases. Queries are distributed to appropriate servers by mapping table names to datasets.

A dataset is defined as a group of tables that are located in the same database. There may be similarly-named databases containing different tables on different servers. There may also be many replicas of a database on different servers. The term "dataset" removes any ambiguity. Consider a dataset as a group of tables that can be mirrored on many servers.

Configuring LudicrousDB involves defining databases and datasets. Defining a database involves specifying the server connection details, the dataset it contains, and its capabilities and priorities for reading and writing. Defining a dataset involves specifying its exact table names or registering one or more callback functions that translate table names to datasets.

For the effective charset and collation settings, including when an empty charset causes a one-time connection check and how to avoid that read-back, see the character sets and collations wiki page.

Since 5.3.1, a cached connection adopts later changes to $wpdb->charset or $wpdb->collate the next time it is used. Reuse with unchanged settings sends no charset query. An empty effective charset instead keeps the server default and validates its session charsets once when the link is configured, rejecting unsupported defaults. Set a supported, non-empty effective charset to avoid that read-back query. The wiki page explains the precedence of constants and db-config.php assignments.

Sample Configuration 1: Default Server

This is the most basic way to add a server to LudicrousDB using only the required parameters: host, user, password, name. This adds the DB defined in wp-config.php as a read/write server for the 'global' dataset. (Every table is in 'global' by default.)

This adds the same server again, only this time it is configured as a replica. The last three parameters are set to the defaults but are shown for clarity.

Sample Configuration 2: Partitioning

This example shows a setup where the multisite blog tables have been separated from the global dataset.

Configuration Functions

add_database()

$database is an associative array with these parameters:

add_table()

$dataset and $table are strings.

add_callback()

$callback is a callable function or method. $callback_group is the group of callbacks, this $callback belongs to.

Callbacks are executed in the order in which they are registered until one of them returns something other than null.

The default $callback_group is 'dataset'. Callback in this group will be called with two arguments and expected to compute a dataset or return null.

Anything evaluating to false will cause the query to be aborted.

For more complex setups, the callback may be used to overwrite properties of $wpdb or variables within LudicrousDB::connect_db(). If a callback returns an array, LudicrousDB will extract the array. It should be an associative array and it should include a $dataset value corresponding to a database added with $wpdb->add_database(). It may also include $server, which will be extracted to overwrite the parameters of each randomly selected database server prior to connection. This allows you to dynamically vary parameters such as the host, user, password, database name, lag_threshold and TCP check timeout.

2. Primary & Replica Databases

A database definition can include 'read' and 'write' parameters. These operate as boolean switches but they are typically specified as integers. They allow or disallow use of the database for reading or writing.

A primary database might be configured to allow reading and writing:

while a replica would be allowed only to read:

It might be advantageous to disallow reading from the primary, such as when there are many replicas available and the primary is very busy with writes.

LudicrousDB tracks the tables that it has written since instantiation and sending subsequent read queries to the same server that received the write query. Thus a primary set up this way will still receive read queries, but only subsequent to writes.

3. Network topology / Datacenter awareness

When your databases are located in separate physical locations there is typically an advantage to connecting to a nearby server instead of a more distant one. The read and write parameters can be used to place servers into logical groups of more or less preferred connections. Lower numbers indicate greater preference.

This configuration instructs LudicrousDB to try reading from one of the local replicas at random. If that replica is unreachable or refuses the connection, the other replica will be tried, followed by the primary, and finally the remote replicas in random order.

In the other datacenter, the primary would be remote. We would take that into account while deciding where to send reads. Writes would always be sent to the primary, regardless of proximity.

There are many ways to achieve different configurations in different locations. You can deploy different config files. You can write code to discover the web server's location, such as by inspecting $_SERVER or php_uname(), and compute the read/write parameters accordingly.

4. Replication Lag

LudicrousDB accommodates replica lag by making decisions based on the defined lag threshold. If the lag threshold is not set, it ignores replica lag. Otherwise, it tries to find a non-lagged replica before connecting to a lagged one.

A replica is considered lagged when its lag is greater than the per-database lag_threshold, or the default in $wpdb->database_defaults['lag_threshold']. A dataset callback may also override the threshold by returning $server['lag_threshold'].

LudicrousDB does not impose a particular replication monitor. Register two callbacks to supply lag data:

and

The first callback runs before LudicrousDB connects to a replica. It should return the cached lag in seconds, or false when the lag is unknown. $wpdb->lag_cache_key identifies the replica endpoint.

The second callback runs after the replica connection is established. It should measure and return lag in seconds, or false when the lag is unknown. The active connection is available in $wpdb->dbhs[ $wpdb->dbhname ].

Sample replication lag detection configuration

The following example reads a heartbeat timestamp replicated from the primary. Percona Toolkit's pt-heartbeat can maintain such a table. Change heartbeat.heartbeat to the qualified database and table used by your monitor.

The LudicrousDB database user needs SELECT access to the heartbeat table. The query uses a qualified table name so it does not change the database selected for the WordPress query that follows.

This example uses the WordPress object cache when it is available. With a persistent object-cache drop-in, the value can be shared across requests; otherwise the live check remains authoritative.