* @ingroup Database
* @author Aaron Schulz
*/
+namespace Wikimedia\Rdbms;
+
+use IDatabase;
+use Database;
+use DBConnRef;
+use MaintainableDBConnRef;
+use DBError;
+use DBAccessError;
+use DBTransactionError;
+use DBExpectedError;
+use Exception;
+use InvalidArgumentException;
/**
* Database cluster connection, tracking, load balancing, and transaction manager interface
/**
* Get the index of the reader connection, which may be a replica DB
+ *
* This takes into account load ratios and lag times. It should
- * always return a consistent index during a given invocation
+ * always return a consistent index during a given invocation.
*
* Side effect: opens connections to databases
* @param string|bool $group Query group, or false for the generic reader
/**
* Set the master wait position
- * If a DB_REPLICA connection has been opened already, waits
- * Otherwise sets a variable telling it to wait if such a connection is opened
+ *
+ * If a DB_REPLICA connection has been opened already, then wait immediately.
+ * Otherwise sets a variable telling it to wait if such a connection is opened.
+ *
* @param DBMasterPos $pos
*/
public function waitFor( $pos );
/**
* Set the master wait position and wait for ALL replica DBs to catch up to it
+ *
* @param DBMasterPos $pos
* @param int $timeout Max seconds to wait; default is mWaitTimeout
* @return bool Success (able to connect and no timeouts reached)
/**
* Get any open connection to a given server index, local or foreign
- * Returns false if there is no connection open
*
- * @param int $i Server index
- * @return IDatabase|bool False on failure
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
+ * @return Database|bool False if no such connection is open
*/
public function getAnyOpenConnection( $i );
/**
* Get a connection by index
- * This is the main entry point for this class.
*
- * @param int $i Server index
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
* @param array|string|bool $groups Query group(s), or false for the generic reader
* @param string|bool $domain Domain ID, or false for the current domain
*
* @throws DBError
- * @return IDatabase
+ * @return Database
*/
public function getConnection( $i, $groups = [], $domain = false );
/**
- * Mark a foreign connection as being available for reuse under a different
- * DB name or prefix. This mechanism is reference-counted, and must be called
- * the same number of times as getConnection() to work.
+ * Mark a foreign connection as being available for reuse under a different DB domain
+ *
+ * This mechanism is reference-counted, and must be called the same number of times
+ * as getConnection() to work.
*
* @param IDatabase $conn
* @throws InvalidArgumentException
/**
* Get a database connection handle reference
*
- * The handle's methods wrap simply wrap those of a IDatabase handle
+ * The handle's methods simply wrap those of a Database handle
*
- * @see LoadBalancer::getConnection() for parameter information
+ * @see ILoadBalancer::getConnection() for parameter information
*
- * @param int $db
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
* @param array|string|bool $groups Query group(s), or false for the generic reader
* @param string|bool $domain Domain ID, or false for the current domain
* @return DBConnRef
*/
- public function getConnectionRef( $db, $groups = [], $domain = false );
+ public function getConnectionRef( $i, $groups = [], $domain = false );
/**
* Get a database connection handle reference without connecting yet
*
- * The handle's methods wrap simply wrap those of a IDatabase handle
+ * The handle's methods simply wrap those of a Database handle
*
- * @see LoadBalancer::getConnection() for parameter information
+ * @see ILoadBalancer::getConnection() for parameter information
*
- * @param int $db
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
* @param array|string|bool $groups Query group(s), or false for the generic reader
* @param string|bool $domain Domain ID, or false for the current domain
* @return DBConnRef
*/
- public function getLazyConnectionRef( $db, $groups = [], $domain = false );
+ public function getLazyConnectionRef( $i, $groups = [], $domain = false );
+
+ /**
+ * Get a maintenance database connection handle reference for migrations and schema changes
+ *
+ * The handle's methods simply wrap those of a Database handle
+ *
+ * @see ILoadBalancer::getConnection() for parameter information
+ *
+ * @param int $db Server index or DB_MASTER/DB_REPLICA
+ * @param array|string|bool $groups Query group(s), or false for the generic reader
+ * @param string|bool $domain Domain ID, or false for the current domain
+ * @return MaintainableDBConnRef
+ */
+ public function getMaintenanceConnectionRef( $db, $groups = [], $domain = false );
/**
* Open a connection to the server given by the specified index
* Index must be an actual index into the array.
* If the server is already open, returns it.
*
- * On error, returns false, and the connection which caused the
- * error will be available via $this->mErrorConnection.
- *
* @note If disable() was called on this LoadBalancer, this method will throw a DBAccessError.
*
- * @param int $i Server index
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
* @param string|bool $domain Domain ID, or false for the current domain
- * @return IDatabase|bool Returns false on errors
+ * @return Database|bool Returns false on errors
* @throws DBAccessError
*/
public function openConnection( $i, $domain = false );
*
* Use this only for mutli-database commits
*
- * @param integer $type IDatabase::TRIGGER_* constant
+ * @param int $type IDatabase::TRIGGER_* constant
* @return Exception|null The first exception or null if there were none
*/
public function runMasterPostTrxCallbacks( $type );
/**
* @note This method may trigger a DB connection if not yet done
* @param string|bool $domain Domain ID, or false for the current domain
- * @param IDatabase|null DB master connection; used to avoid loops [optional]
+ * @param IDatabase|null $conn DB master connection; used to avoid loops [optional]
* @return string|bool Reason the master is read-only or false if it is not
*/
public function getReadOnlyReason( $domain = false, IDatabase $conn = null );
*
* @param IDatabase $conn Replica DB
* @param DBMasterPos|bool $pos Master position; default: current position
- * @param integer|null $timeout Timeout in seconds [optional]
+ * @param int $timeout Timeout in seconds [optional]
* @return bool Success
*/
- public function safeWaitForMasterPos( IDatabase $conn, $pos = false, $timeout = null );
+ public function safeWaitForMasterPos( IDatabase $conn, $pos = false, $timeout = 10 );
/**
* Set a callback via IDatabase::setTransactionListener() on
* @param array[] $aliases Map of (table => (dbname, schema, prefix) map)
*/
public function setTableAliases( array $aliases );
-
- /**
- * Mark the beginning of a new section to track database usage information for
- *
- * This returns an ID which can be passed to declareUsageSectionEnd() to indicate
- * the end of the section. If $id is provided, the returned ID equals $id.
- * @param string|integer Section ID to use instead of auto-generated ID [optional]
- * @return string|integer
- */
- public function declareUsageSectionStart( $id = null );
-
- /**
- * End a section started by declareUsageSectionStart() and return the information map
- *
- * The map includes information about activity during the section:
- * - readQueries: number of read queries issued.
- * - writeQueries: number of write queries issued.
- * - cacheSetOptions: result of pessimistically merging the result of getCacheSetOptions()
- * on each DB handle before the first query of the respective handle. This is null if
- * no actual queries took place in the section interval.
- *
- * This can be called before cache value generation functions commence queries
- * and then passed the caching storage layer to detect and avoid lag race conditions.
- *
- * @param integer|string $id Section ID passed to declareUsageSectionStart() earlier
- * @return array
- */
- public function declareUsageSectionEnd( $id );
}
dépôts / lhc / web / wiklou.git / blobdiff