Proyectos de Subversion Moodle

<?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 replica connection capability.
 *
 * Trait to wrap connect() method of database driver classes that gives
 * ability to use read only replica instances for SELECT queries. For the
 * databases that support replication and read only connections to the replica.
 * If the replica connection is configured there will be two database handles
 * created, one for the primary and another one for the replica. If there's no
 * replica specified everything uses primary 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 replica 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: primary -> replica sync latency in seconds (will probably
 *   be a fraction of a second). A table being written to is deemed fully synced
 *   after that period and suitable for replica read. Defaults to 1 sec.
 * - 'exclude_tables' option: a list of tables that never go to the replica 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. For those queries primary
 *   write handle is used.
 * - SQL_QUERY_AUX queries will always use the primary write handle because they
 *   are used for transaction start/end, locking etc. In that respect, query_start() and
 *   query_end() *must not* be used during the connection phase.
 * - SQL_QUERY_AUX_READONLY queries will use the primary write handle if in a transaction.
 * - SELECT queries will use the primary 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:
 *      * current microtime() is compared to the write microrime, and if more than
 *        latency time has passed the replica handle is used
 *      * otherwise (not enough time passed) we choose the primary write handle
 *   If none of the above conditions are met the replica 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 primary
 *    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 primary -> replica sync is assumed, so the replica connection is
 *    used again.
 *
 * @package    core
 * @category   dml
 * @copyright  2024 David Woloszyn <david.woloszyn@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
trait moodle_read_replica_trait {

    /** @var resource Primary write database handle. */
    protected $dbhwrite;

    /** @var resource Replica read only database handle. */
    protected $dbhreadonly;

    /** @var bool Connect to replica database for read queries. */
    private $wantreadreplica = false;

    /** @var int The number of reads done by the read only database. */
    private $readsreplica = 0;

    /** @var int Replica letency in seconds. */
    private $replicalatency = 1;

    /** @var bool Structure changed status. */
    private $structurechange = false;

    /** @var array Track tables being written to. */
    private $written = [];

    /** @var array Tables to exclude from using dbhreadonly. */
    private $readexclude = [];

    /** @var string The database host. */
    private $pdbhost;

    /** @var string The database username. */
    private $pdbuser;

    /** @var string The database username's password. */
    private $pdbpass;

    /** @var string The name of the database being connected to. */
    private $pdbname;

    /** @var mixed String means moodle db prefix, false used for external databases where prefix not used. */
    private $pprefix;

    /** @var array|null Driver specific options. */
    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
     */
    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|null $dboptions Driver specific options.
     * @return bool
     * @throws dml_connection_exception
     */
    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 primary write and replica 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|null $dboptions Driver specific options.
     * @return bool
     * @throws dml_connection_exception
     */
    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;

        $logconnection = false;
        if ($dboptions) {
            if (isset($dboptions['readonly'])) {
                $this->wantreadreplica = 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->replicalatency = $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;

                $replicas = $dboptionsro['instance'];
                if (!is_array($replicas) || !isset($replicas[0])) {
                    $replicas = [$replicas];
                }

                if (count($replicas) > 1) {
                    // Don't shuffle for unit tests as order is important for them to pass.
                    if (!PHPUNIT_TEST) {
                        // Randomise things a bit.
                        shuffle($replicas);
                    }
                }

                // Find first connectable readonly replica.
                $rodb = [];
                foreach ($replicas as $replica) {
                    if (!is_array($replica)) {
                        $replica = ['dbhost' => $replica];
                    }
                    foreach (['dbhost', 'dbuser', 'dbpass'] as $dbparam) {
                        $rodb[$dbparam] = isset($replica[$dbparam]) ? $replica[$dbparam] : $$dbparam;
                    }
                    $dboptions['dbport'] = isset($replica['dbport']) ? $replica['dbport'] : $dbport;

                    try {
                        $this->raw_connect($rodb['dbhost'], $rodb['dbuser'], $rodb['dbpass'], $dbname, $prefix, $dboptions);
                        $this->dbhreadonly = $this->get_db_handle();
                        if ($logconnection) {
                            debugging(
                                "Readonly db connection succeeded for host {$rodb['dbhost']}"
                            );
                        }
                        break;
                    } catch (dml_connection_exception $e) {
                        debugging(
                            "Readonly db connection failed for host {$rodb['dbhost']}: {$e->debuginfo}"
                        );
                        $logconnection = true;
                    }
                }
                // ... lock_db queries always go to primary.
                // Since it is a lock and as such marshalls concurrent connections,
                // it is best to leave it out and avoid primary/replica latency.
                $this->readexclude[] = 'lock_db';
                // ... and sessions.
                $this->readexclude[] = 'sessions';
            }
        }
        if (!$this->dbhreadonly) {
            try {
                $this->set_dbhwrite();
            } catch (dml_connection_exception $e) {
                debugging(
                    "Readwrite db connection failed for host {$this->pdbhost}: {$e->debuginfo}"
                );
                throw $e;
            }
            if ($logconnection) {
                debugging(
                    "Readwrite db connection succeeded for host {$this->pdbhost}"
                );
            }
        }

        return true;
    }

    /**
     * Set database handle to readwrite primary.
     *
     * Will connect if required. Calls set_db_handle().
     */
    private function set_dbhwrite(): void {
        // Lazy connect to read/write primary.
        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 replica database for read queries.
     *
     * @return bool Want read only connection.
     */
    public function want_read_replica(): bool {
        return $this->wantreadreplica;
    }

    /**
     * Returns the number of reads done by the read only database.
     *
     * @return int Number of reads.
     */
    public function perf_get_reads_replica(): int {
        return $this->readsreplica;
    }

    /**
     * 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|null $params An array of parameters.
     * @param int $type type of query
     * @param mixed $extrainfo driver specific extra information
     */
    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.
     *
     * @param mixed $result The db specific result obtained from running a query.
     */
    protected function query_end($result) {
        if ($this->written) {
            // Adjust the written time.
            array_walk($this->written, function (&$val) {
                if ($val === true) {
                    $val = microtime(true);
                }
            });
        }

        parent::query_end($result);
    }

    /**
     * Select appropriate db handle - readwrite or readonly.
     *
     * @param int $type Type of query.
     * @param string $sql The sql to use.
     */
    protected function select_db_handle(int $type, string $sql): void {
        if ($this->dbhreadonly && $this->can_use_readonly($type, $sql)) {
            $this->readsreplica++;
            $this->set_db_handle($this->dbhreadonly);
            return;
        }
        $this->set_dbhwrite();
    }

    /**
     * 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 The sql to use.
     * @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_AUX_READONLY:
                // SQL_QUERY_AUX_READONLY may read the structure data.
                // We don't have a way to reliably determine whether it is safe to go to readonly if the structure has changed.
                return !$this->structurechange;
            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])) {
                        $now = $now ?: microtime(true);

                        if ($now - $this->written[$tablename] < $this->replicalatency) {
                            return false;
                        }
                        unset($this->written[$tablename]);
                    }
                }

                return true;
            case SQL_QUERY_INSERT:
            case SQL_QUERY_UPDATE:
                foreach ($this->table_names($sql) as $tablename) {
                    $this->written[$tablename] = true;
                }
                return false;
            case SQL_QUERY_STRUCTURE:
                $this->structurechange = true;
                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.
     * @throws dml_transaction_exception Creates and throws transaction related exceptions.
     */
    public function commit_delegated_transaction(moodle_transaction $transaction) {
        if ($this->written) {
            // Adjust the written time.
            $now = microtime(true);
            foreach ($this->written as $tablename => $when) {
                $this->written[$tablename] = $now;
            }
        }

        parent::commit_delegated_transaction($transaction);
    }

    /**
     * Parse table names from query.
     *
     * @param string $sql The sql to use.
     * @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];
    }
}