Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
  • Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Trait that adds read-only slave connection capability
 *
 * @package    core
 * @category   dml
 * @copyright  2018 Srdjan Janković, Catalyst IT
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die();

/**
 * Trait to wrap connect() method of database driver classes that gives
 * ability to use read only slave instances for SELECT queries. For the
 * databases that support replication and read only connections to the slave.
 * If the slave connection is configured there will be two database handles
 * created, one for the master and another one for the slave. If there's no
 * slave specified everything uses master handle.
 *
 * Classes that use this trait need to rename existing connect() method to
 * raw_connect(). In addition, they need to provide get_db_handle() and
 * set_db_handle() methods, due to dbhandle attributes not being named
 * consistently across the database driver classes.
 *
 * Read only slave connection is configured in the $CFG->dboptions['readonly']
 * array.
 * - It supports multiple 'instance' entries, in case one is not accessible,
 *   but only one (first connectable) instance is used.
 * - 'latency' option: master -> slave sync latency in seconds (will probably
< * be a fraction of a second). If specified, a table being written to is < * deemed fully synced and suitable for slave read.
> * be a fraction of a second). A table being written to is deemed fully synced > * after that period and suitable for slave read. Defaults to 1 sec.
* - 'exclude_tables' option: a list of tables that never go to the slave for * querying. The feature is meant to be used in emergency only, so the * readonly feature can still be used in case there is a rogue query that * does not go through the standard dml interface or some other unaccounted * situation. It should not be used under normal circumstances, and its use * indicates a problem in the system that needs addressig. * * Choice of the database handle is based on following: * - SQL_QUERY_INSERT, UPDATE and STRUCTURE record table from the query
< * in the $written array and microtime() the event if the 'latency' option < * is set. For those queries master write handle is used.
> * in the $written array and microtime() the event. For those queries master > * write handle is used.
* - SQL_QUERY_AUX queries will always use the master write handle because they * are used for transactionstart/end, locking etc. In that respect, query_start() and * query_end() *must not* be used during the connection phase. * - SELECT queries will use the master write handle if: * -- any of the tables involved is a temp table * -- any of the tables involved is listed in the 'exclude_tables' option * -- any of the tables involved is in the $written array:
< * * If the 'latency' option is set then the microtime() is compared to < * the write microrime, and if more then latency time has passed the slave < * handle is used. < * * Otherwise (not enough time passed or 'latency' option not set) < * we choose the master write handle
> * * current microtime() is compared to the write microrime, and if more than > * latency time has passed the slave handle is used > * * otherwise (not enough time passed) we choose the master write handle
* If none of the above conditions are met the slave instance is used. * * A 'latency' example: * - we have set $CFG->dboptions['readonly']['latency'] to 0.2. * - a SQL_QUERY_UPDATE to table tbl_x happens, and it is recorded in * the $written array * - 0.15 seconds later SQL_QUERY_SELECT with tbl_x is requested - the master * connection is used * - 0.10 seconds later (0.25 seconds after SQL_QUERY_UPDATE) another * SQL_QUERY_SELECT with tbl_x is requested - this time more than 0.2 secs * has gone and master -> slave sync is assumed, so the slave connection is * used again */ trait moodle_read_slave_trait { /** @var resource master write database handle */ protected $dbhwrite; /** @var resource slave read only database handle */ protected $dbhreadonly; private $wantreadslave = false; private $readsslave = 0;
< private $slavelatency = 0;
> private $slavelatency = 1;
private $written = []; // Track tables being written to. private $readexclude = []; // Tables to exclude from using dbhreadonly. // Store original params. private $pdbhost; private $pdbuser; private $pdbpass; private $pdbname; private $pprefix; private $pdboptions; /** * Gets db handle currently used with queries * @return resource */ abstract protected function get_db_handle(); /** * Sets db handle to be used with subsequent queries * @param resource $dbh * @return void */ abstract protected function set_db_handle($dbh): void; /** * Connect to db * The real connection establisment, called from connect() and set_dbhwrite() * @param string $dbhost The database host. * @param string $dbuser The database username. * @param string $dbpass The database username's password. * @param string $dbname The name of the database being connected to. * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used * @param array $dboptions driver specific options * @return bool true * @throws dml_connection_exception if error */ abstract protected function raw_connect(string $dbhost, string $dbuser, string $dbpass, string $dbname, $prefix, array $dboptions = null): bool; /** * Connect to db * The connection parameters processor that sets up stage for master write and slave readonly handles. * Must be called before other methods. * @param string $dbhost The database host. * @param string $dbuser The database username. * @param string $dbpass The database username's password. * @param string $dbname The name of the database being connected to. * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used * @param array $dboptions driver specific options * @return bool true * @throws dml_connection_exception if error */ public function connect($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions = null) { $this->pdbhost = $dbhost; $this->pdbuser = $dbuser; $this->pdbpass = $dbpass; $this->pdbname = $dbname; $this->pprefix = $prefix; $this->pdboptions = $dboptions; if ($dboptions) { if (isset($dboptions['readonly'])) { $this->wantreadslave = true; $dboptionsro = $dboptions['readonly']; if (isset($dboptionsro['connecttimeout'])) { $dboptions['connecttimeout'] = $dboptionsro['connecttimeout']; } else if (!isset($dboptions['connecttimeout'])) { $dboptions['connecttimeout'] = 2; // Default readonly connection timeout. } if (isset($dboptionsro['latency'])) { $this->slavelatency = $dboptionsro['latency']; } if (isset($dboptionsro['exclude_tables'])) { $this->readexclude = $dboptionsro['exclude_tables']; if (!is_array($this->readexclude)) { throw new configuration_exception('exclude_tables must be an array'); } } $dbport = isset($dboptions['dbport']) ? $dboptions['dbport'] : null; $slaves = $dboptionsro['instance']; if (!is_array($slaves) || !isset($slaves[0])) { $slaves = [$slaves]; } if (count($slaves) > 1) { // Randomise things a bit. shuffle($slaves); } // Find first connectable readonly slave. $rodb = []; foreach ($slaves as $slave) { if (!is_array($slave)) { $slave = ['dbhost' => $slave]; } foreach (['dbhost', 'dbuser', 'dbpass'] as $dbparam) { $rodb[$dbparam] = isset($slave[$dbparam]) ? $slave[$dbparam] : $$dbparam; } $dboptions['dbport'] = isset($slave['dbport']) ? $slave['dbport'] : $dbport;
< // @codingStandardsIgnoreStart
try { $this->raw_connect($rodb['dbhost'], $rodb['dbuser'], $rodb['dbpass'], $dbname, $prefix, $dboptions); $this->dbhreadonly = $this->get_db_handle(); break;
< } catch (dml_connection_exception $e) {
> } catch (dml_connection_exception $e) { // phpcs:ignore
// If readonly slave is not connectable we'll have to do without it. }
< // @codingStandardsIgnoreEnd
} // ... lock_db queries always go to master. // Since it is a lock and as such marshalls concurrent connections, // it is best to leave it out and avoid master/slave latency. $this->readexclude[] = 'lock_db'; // ... and sessions. $this->readexclude[] = 'sessions'; } } if (!$this->dbhreadonly) { $this->set_dbhwrite(); } return true; } /** * Set database handle to readwrite master * Will connect if required. Calls set_db_handle() * @return void */ private function set_dbhwrite(): void { // Lazy connect to read/write master. if (!$this->dbhwrite) { $temptables = $this->temptables; $this->raw_connect($this->pdbhost, $this->pdbuser, $this->pdbpass, $this->pdbname, $this->pprefix, $this->pdboptions); if ($temptables) { $this->temptables = $temptables; // Restore temptables, so we don't get separate sets for rw and ro. } $this->dbhwrite = $this->get_db_handle(); } $this->set_db_handle($this->dbhwrite); } /** * Returns whether we want to connect to slave database for read queries. * @return bool Want read only connection */ public function want_read_slave(): bool { return $this->wantreadslave; } /** * Returns the number of reads done by the read only database. * @return int Number of reads. */ public function perf_get_reads_slave(): int { return $this->readsslave; } /** * On DBs that support it, switch to transaction mode and begin a transaction * @return moodle_transaction */ public function start_delegated_transaction() { $this->set_dbhwrite(); return parent::start_delegated_transaction(); } /** * Called before each db query. * @param string $sql
< * @param array $params array of parameters
> * @param array|null $params An array of parameters.
* @param int $type type of query * @param mixed $extrainfo driver specific extra information * @return void */
< protected function query_start($sql, array $params = null, $type, $extrainfo = null) {
> protected function query_start($sql, ?array $params, $type, $extrainfo = null) {
parent::query_start($sql, $params, $type, $extrainfo); $this->select_db_handle($type, $sql); } /**
> * This should be called immediately after each db query. It does a clean up of resources. * Select appropriate db handle - readwrite or readonly > * * @param int $type type of query > * @param mixed $result The db specific result obtained from running a query. * @param string $sql > * @return void * @return void > */ */ > protected function query_end($result) { protected function select_db_handle(int $type, string $sql): void { > if ($this->written) { if ($this->dbhreadonly && $this->can_use_readonly($type, $sql)) { > // Adjust the written time. $this->readsslave++; > array_walk($this->written, function (&$val) { $this->set_db_handle($this->dbhreadonly); > if ($val === true) { return; > $val = microtime(true); } > } $this->set_dbhwrite(); > }); } > } > /** > parent::query_end($result); * Check if The query qualifies for readonly connection execution > } * Logging queries are exempt, those are write operations that circumvent > * standard query_start/query_end paths. > /**
* @param int $type type of query * @param string $sql * @return bool */ protected function can_use_readonly(int $type, string $sql): bool { if ($this->loggingquery) { return false; } if (during_initial_install()) { return false; } // Transactions are done as AUX, we cannot play with that. switch ($type) { case SQL_QUERY_SELECT: if ($this->transactions) { return false; } $now = null; foreach ($this->table_names($sql) as $tablename) { if (in_array($tablename, $this->readexclude)) { return false; } if ($this->temptables && $this->temptables->is_temptable($tablename)) { return false; } if (isset($this->written[$tablename])) {
< if ($this->slavelatency) {
$now = $now ?: microtime(true);
>
if ($now - $this->written[$tablename] < $this->slavelatency) { return false; } unset($this->written[$tablename]);
< } else { < return false; < }
} } return true; case SQL_QUERY_INSERT: case SQL_QUERY_UPDATE:
< // If we are in transaction we cannot set the written time yet. < $now = $this->slavelatency && !$this->transactions ? microtime(true) : true;
foreach ($this->table_names($sql) as $tablename) {
< $this->written[$tablename] = $now;
> $this->written[$tablename] = true;
} return false; case SQL_QUERY_STRUCTURE: foreach ($this->table_names($sql) as $tablename) { if (!in_array($tablename, $this->readexclude)) { $this->readexclude[] = $tablename; } } return false; } return false; } /** * Indicates delegated transaction finished successfully. * Set written times after outermost transaction finished * @param moodle_transaction $transaction The transaction to commit * @return void * @throws dml_transaction_exception Creates and throws transaction related exceptions. */ public function commit_delegated_transaction(moodle_transaction $transaction) {
< parent::commit_delegated_transaction($transaction); < < if ($this->transactions) { < return; < } < < if (!$this->slavelatency) { < return; < } < < $now = null;
> if ($this->written) { > // Adjust the written time. > $now = microtime(true);
foreach ($this->written as $tablename => $when) {
< if ($when === true) { < $now = $now ?: microtime(true);
$this->written[$tablename] = $now; } }
> } > parent::commit_delegated_transaction($transaction);
/** * Parse table names from query * @param string $sql * @return array */ protected function table_names(string $sql): array { preg_match_all('/\b'.$this->prefix.'([a-z][A-Za-z0-9_]*)/', $sql, $match); return $match[1]; } }