* @ingroup Database
*/
interface ILoadBalancer {
- /** @var integer Request a replica DB connection */
+ /** @var int Request a replica DB connection */
const DB_REPLICA = -1;
- /** @var integer Request a master DB connection */
+ /** @var int Request a master DB connection */
const DB_MASTER = -2;
/** @var string Domain specifier when no specific database needs to be selected */
const DOMAIN_ANY = '';
+ /** @var int DB handle should have DBO_TRX disabled and the caller will leave it as such */
+ const CONN_TRX_AUTO = 1;
+
/**
* Construct a manager of IDatabase connection objects
*
* - loadMonitor : Name of a class used to fetch server lag and load.
* - readOnlyReason : Reason the master DB is read-only if so [optional]
* - waitTimeout : Maximum time to wait for replicas for consistency [optional]
+ * - maxLag: Avoid replica DB servers with more lag than this [optional]
* - srvCache : BagOStuff object for server cache [optional]
* - wanCache : WANObjectCache object [optional]
* - chronologyProtector: ChronologyProtector object [optional]
public function getAnyOpenConnection( $i );
/**
- * Get a connection by index
+ * Get a connection handle by server index
+ *
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
+ * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+ * call ILoadBalancer::reuseConnection() on the handle when finished using it.
+ * In all other cases, this is not necessary, though not harmful either.
*
* @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
+ * @param int $flags Bitfield of CONN_* class constants
+ *
+ * @note This method throws DBAccessError if ILoadBalancer::disable() was called
*
* @throws DBError
* @return Database
*/
- public function getConnection( $i, $groups = [], $domain = false );
+ public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
/**
* Mark a foreign connection as being available for reuse under a different DB domain
*
* The handle's methods simply wrap those of a Database handle
*
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
* @see ILoadBalancer::getConnection() for parameter information
*
* @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
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTO)
* @return DBConnRef
*/
- public function getConnectionRef( $i, $groups = [], $domain = false );
+ public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
/**
* Get a database connection handle reference without connecting yet
*
* The handle's methods simply wrap those of a Database handle
*
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
* @see ILoadBalancer::getConnection() for parameter information
*
* @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
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTO)
* @return DBConnRef
*/
- public function getLazyConnectionRef( $i, $groups = [], $domain = false );
+ public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
/**
* Get a maintenance database connection handle reference for migrations and schema changes
*
* The handle's methods simply wrap those of a Database handle
*
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
* @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
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTO)
* @return MaintainableDBConnRef
*/
- public function getMaintenanceConnectionRef( $db, $groups = [], $domain = false );
+ public function getMaintenanceConnectionRef( $db, $groups = [], $domain = false, $flags = 0 );
/**
* Open a connection to the server given by the specified index
* The index must be an actual index into the array. If a connection to the server is
* already open and not considered an "in use" foreign connection, this simply returns it.
*
- * @note If disable() was called on this LoadBalancer, this method will throw a DBAccessError.
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
+ * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+ * call ILoadBalancer::reuseConnection() on the handle when finished using it.
+ * In all other cases, this is not necessary, though not harmful either.
+ *
+ * @note This method throws DBAccessError if ILoadBalancer::disable() was called
*
* @param int $i Server index (does not support DB_MASTER/DB_REPLICA)
* @param string|bool $domain Domain ID, or false for the current domain
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTO)
* @return Database|bool Returns false on errors
* @throws DBAccessError
*/
- public function openConnection( $i, $domain = false );
+ public function openConnection( $i, $domain = false, $flags = 0 );
/**
* @return int
/**
* Returns true if the specified index is a valid server index
*
- * @param string $i
+ * @param int $i
* @return bool
*/
public function haveIndex( $i );
/**
* Returns true if the specified index is valid and has non-zero load
*
- * @param string $i
+ * @param int $i
* @return bool
*/
public function isNonZeroLoad( $i );
/**
* Get the host name or IP address of the server with the specified index
- * Prefer a readable name if available.
- * @param string $i
- * @return string
+ *
+ * @param int $i
+ * @return string Readable name if available or IP/host otherwise
*/
public function getServerName( $i );
/**
- * Return the server info structure for a given index, or false if the index is invalid.
- * @param int $i
- * @return array|bool
+ * Get DB type of the server with the specified index
*
- * @deprecated Since 1.30, no alternative
- */
- public function getServerInfo( $i );
-
- /**
- * Sets the server info structure for the given index. Entry at index $i
- * is created if it doesn't exist
* @param int $i
- * @param array $serverInfo
- *
- * @deprecated Since 1.30, construct new object
+ * @return string One of (mysql,postgres,sqlite,...) or "unknown" for bad indexes
+ * @since 1.30
*/
- public function setServerInfo( $i, array $serverInfo );
+ public function getServerType( $i );
/**
* Get the current master position for chronology control purposes
dépôts / lhc / web / wiklou.git / blobdiff