1. Configuration

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 charset and collation defaults, connection behavior, and the cost of an empty effective charset, see Character Sets and Collations.

Sample 1: Default server

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

$wpdb->add_database( array(
	'host'     => DB_HOST,     // If port is other than 3306, use host:port.
	'user'     => DB_USER,
	'password' => DB_PASSWORD,
	'name'     => DB_NAME,
) );

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.

$wpdb->add_database( array(
	'host'     => DB_HOST,     // If port is other than 3306, use host:port.
	'user'     => DB_USER,
	'password' => DB_PASSWORD,
	'name'     => DB_NAME,
	'write'    => 0,
	'read'     => 1,
	'dataset'  => 'global',
	'timeout'  => 0.2,
) );

Sample 2: Partitioning

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

$wpdb->add_database( array(
	'host'     => 'global.db.example.com',
	'user'     => 'globaluser',
	'password' => 'globalpassword',
	'name'     => 'globaldb',
) );

$wpdb->add_database( array(
	'host'     => 'blog.db.example.com',
	'user'     => 'bloguser',
	'password' => 'blogpassword',
	'name'     => 'blogdb',
	'dataset'  => 'blog',
) );

$wpdb->add_callback( 'my_db_callback' );

// Multisite blog tables are "{$base_prefix}{$blog_id}_*"
function my_db_callback( $query, $wpdb ) {
	$pattern = '/^' . preg_quote( $wpdb->base_prefix, '/' ) . '\d+_/i';

	if ( preg_match( $pattern, $wpdb->table ) ) {
		return 'blog';
	}

	return null;
}

Functions

add_database()

$wpdb->add_database( $database );

$database is an associative array with these parameters:

host          (required) Hostname with optional :port. Default port is 3306.
user          (required) MySQL user name.
password      (required) MySQL user password.
name          (required) MySQL database name.
read          (optional) Whether server is readable. Default is 1 (readable).
                         Also used to assign preference. See "Network topology".
write         (optional) Whether server is writable. Default is 1 (writable).
                         Also used to assign preference in multi-primary mode.
dataset       (optional) Name of dataset. Default is 'global'.
timeout       (optional) Seconds to wait for TCP responsiveness. Default is 0.2
lag_threshold (optional) The minimum lag on a replica in seconds before we consider it lagged.
                         Set null to disable. When not set, the value of
                         $wpdb->database_defaults['lag_threshold'] is used.

add_table()

$wpdb->add_table( $dataset, $table );

$dataset and $table are strings.

add_callback()

$wpdb->add_callback( $callback, $callback_group = 'dataset' );

$callback is a callable function or method. $callback_group identifies the callback group. The default group is dataset.

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

Dataset callbacks receive the SQL query and the LudicrousDB instance. They should return a dataset name, an associative array of routing overrides, or null to allow the next callback or the default routing to run.

$dataset = $callback( $query, $wpdb );

Returning an empty or false value causes the query to be aborted. Return null when a callback does not handle the current table.

For more complex setups, a callback may return an associative array containing a dataset value and an optional server override. The dataset must correspond to a database registered with $wpdb->add_database(). Server overrides can vary connection parameters such as the host, user, password, database name, lag threshold, and TCP timeout.

Prefer $wpdb->table when routing by table. It contains the table parsed from the current query and avoids fragile substring searches through raw SQL.