diff options
author | Yaco <franco@reevo.org> | 2020-06-04 11:01:00 -0300 |
---|---|---|
committer | Yaco <franco@reevo.org> | 2020-06-04 11:01:00 -0300 |
commit | fc7369835258467bf97eb64f184b93691f9a9fd5 (patch) | |
tree | daabd60089d2dd76d9f5fb416b005fbe159c799d /www/wiki/includes/dao |
first commit
Diffstat (limited to 'www/wiki/includes/dao')
-rw-r--r-- | www/wiki/includes/dao/DBAccessBase.php | 95 | ||||
-rw-r--r-- | www/wiki/includes/dao/DBAccessObjectUtils.php | 81 | ||||
-rw-r--r-- | www/wiki/includes/dao/IDBAccessObject.php | 71 |
3 files changed, 247 insertions, 0 deletions
diff --git a/www/wiki/includes/dao/DBAccessBase.php b/www/wiki/includes/dao/DBAccessBase.php new file mode 100644 index 00000000..3947f4b1 --- /dev/null +++ b/www/wiki/includes/dao/DBAccessBase.php @@ -0,0 +1,95 @@ +<?php + +use Wikimedia\Rdbms\IDatabase; +use Wikimedia\Rdbms\LoadBalancer; + +/** + * Base class for objects that allow access to other wiki's databases using + * the foreign database access mechanism implemented by LBFactoryMulti. + * + * This program 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 2 of the License, or + * (at your option) any later version. + * + * This program 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 this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @since 1.21 + * + * @file + * @ingroup Database + * + * @license GNU GPL v2+ + * @author Daniel Kinzler + */ +abstract class DBAccessBase implements IDBAccessObject { + /** + * @var string|bool $wiki The target wiki's name. This must be an ID + * that LBFactory can understand. + */ + protected $wiki = false; + + /** + * @param string|bool $wiki The target wiki's name. This must be an ID + * that LBFactory can understand. + */ + public function __construct( $wiki = false ) { + $this->wiki = $wiki; + } + + /** + * Returns a database connection. + * + * @see wfGetDB() + * @see LoadBalancer::getConnection() + * + * @since 1.21 + * + * @param int $id Which connection to use + * @param array $groups Query groups + * + * @return IDatabase + */ + protected function getConnection( $id, $groups = [] ) { + $loadBalancer = wfGetLB( $this->wiki ); + + return $loadBalancer->getConnection( $id, $groups, $this->wiki ); + } + + /** + * Releases a database connection and makes it available for recycling. + * + * @see LoadBalancer::reuseConnection() + * + * @since 1.21 + * + * @param IDatabase $db The database connection to release. + */ + protected function releaseConnection( IDatabase $db ) { + if ( $this->wiki !== false ) { + $loadBalancer = $this->getLoadBalancer(); + $loadBalancer->reuseConnection( $db ); + } + } + + /** + * Get the database type used for read operations. + * + * @see wfGetLB + * + * @since 1.21 + * + * @return LoadBalancer The database load balancer object + */ + public function getLoadBalancer() { + return wfGetLB( $this->wiki ); + } +} diff --git a/www/wiki/includes/dao/DBAccessObjectUtils.php b/www/wiki/includes/dao/DBAccessObjectUtils.php new file mode 100644 index 00000000..ee103685 --- /dev/null +++ b/www/wiki/includes/dao/DBAccessObjectUtils.php @@ -0,0 +1,81 @@ +<?php +/** + * This file contains database access object related constants. + * + * This program 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 2 of the License, or + * (at your option) any later version. + * + * This program 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 this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @ingroup Database + */ + +/** + * Helper class for DAO classes + * + * @since 1.26 + */ +class DBAccessObjectUtils implements IDBAccessObject { + /** + * @param int $bitfield + * @param int $flags IDBAccessObject::READ_* constant + * @return bool Bitfield has flag $flag set + */ + public static function hasFlags( $bitfield, $flags ) { + return ( $bitfield & $flags ) == $flags; + } + + /** + * Get an appropriate DB index, options, and fallback DB index for a query + * + * The fallback DB index and options are to be used if the entity is not found + * with the initial DB index, typically querying the master DB to avoid lag + * + * @param int $bitfield Bitfield of IDBAccessObject::READ_* constants + * @return array List of DB indexes and options in this order: + * - DB_MASTER or DB_REPLICA constant for the initial query + * - SELECT options array for the initial query + * - DB_MASTER constant for the fallback query; null if no fallback should happen + * - SELECT options array for the fallback query; empty if no fallback should happen + */ + public static function getDBOptions( $bitfield ) { + if ( self::hasFlags( $bitfield, self::READ_LATEST_IMMUTABLE ) ) { + $index = DB_REPLICA; // override READ_LATEST if set + $fallbackIndex = DB_MASTER; + } elseif ( self::hasFlags( $bitfield, self::READ_LATEST ) ) { + $index = DB_MASTER; + $fallbackIndex = null; + } else { + $index = DB_REPLICA; + $fallbackIndex = null; + } + + $lockingOptions = []; + if ( self::hasFlags( $bitfield, self::READ_EXCLUSIVE ) ) { + $lockingOptions[] = 'FOR UPDATE'; + } elseif ( self::hasFlags( $bitfield, self::READ_LOCKING ) ) { + $lockingOptions[] = 'LOCK IN SHARE MODE'; + } + + if ( $fallbackIndex !== null ) { + $options = []; // locks on DB_REPLICA make no sense + $fallbackOptions = $lockingOptions; + } else { + $options = $lockingOptions; + $fallbackOptions = []; // no fallback + } + + return [ $index, $options, $fallbackIndex, $fallbackOptions ]; + } +} diff --git a/www/wiki/includes/dao/IDBAccessObject.php b/www/wiki/includes/dao/IDBAccessObject.php new file mode 100644 index 00000000..e18a090b --- /dev/null +++ b/www/wiki/includes/dao/IDBAccessObject.php @@ -0,0 +1,71 @@ +<?php +/** + * This file contains database access object related constants. + * + * This program 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 2 of the License, or + * (at your option) any later version. + * + * This program 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 this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @ingroup Database + */ + +/** + * Interface for database access objects. + * + * Classes using this support a set of constants in a bitfield argument to their data loading + * functions. In general, objects should assume READ_NORMAL if no flags are explicitly given, + * though certain objects may assume READ_LATEST for common use case or legacy reasons. + * + * There are four types of reads: + * - READ_NORMAL : Potentially cached read of data (e.g. from a replica DB or stale replica) + * - READ_LATEST : Up-to-date read as of transaction start (e.g. from master or a quorum read) + * - READ_LOCKING : Up-to-date read as of now, that locks (shared) the records + * - READ_EXCLUSIVE : Up-to-date read as of now, that locks (exclusive) the records + * All record locks persist for the duration of the transaction. + * + * A special constant READ_LATEST_IMMUTABLE can be used for fetching append-only data. Such + * data is either (a) on a replica DB and up-to-date or (b) not yet there, but on the master/quorum. + * Because the data is append-only, it can never be stale on a replica DB if present. + * + * Callers should use READ_NORMAL (or pass in no flags) unless the read determines a write. + * In theory, such cases may require READ_LOCKING, though to avoid contention, READ_LATEST is + * often good enough. If UPDATE race condition checks are required on a row and expensive code + * must run after the row is fetched to determine the UPDATE, it may help to do something like: + * - a) Start transaction + * - b) Read the current row with READ_LATEST + * - c) Determine the new row (expensive, so we don't want to hold locks now) + * - d) Re-read the current row with READ_LOCKING; if it changed then bail out + * - e) otherwise, do the updates + * - f) Commit transaction + * + * @since 1.20 + */ +interface IDBAccessObject { + /** Constants for object loading bitfield flags (higher => higher QoS) */ + /** @var int Read from a replica DB/non-quorum */ + const READ_NORMAL = 0; + /** @var int Read from the master/quorum */ + const READ_LATEST = 1; + /* @var int Read from the master/quorum and lock out other writers */ + const READ_LOCKING = 3; // READ_LATEST (1) and "LOCK IN SHARE MODE" (2) + /** @var int Read from the master/quorum and lock out other writers and locking readers */ + const READ_EXCLUSIVE = 7; // READ_LOCKING (3) and "FOR UPDATE" (4) + + /** @var int Read from a replica DB or without a quorum, using the master/quorum on miss */ + const READ_LATEST_IMMUTABLE = 8; + + // Convenience constant for tracking how data was loaded (higher => higher QoS) + const READ_NONE = -1; // not loaded yet (or the object was cleared) +} |