*
* @file
* @ingroup Database
- * @author Aaron Schulz
*/
namespace Wikimedia\Rdbms;
* @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
*
* - readOnlyReason : Reason the master DB is read-only if so [optional]
* - waitTimeout : Maximum time to wait for replicas for consistency [optional]
* - srvCache : BagOStuff object for server cache [optional]
- * - memCache : BagOStuff object for cluster memory cache [optional]
* - wanCache : WANObjectCache object [optional]
* - chronologyProtector: ChronologyProtector object [optional]
* - hostname : The name of the current server [optional]
/**
* Get a connection by index
*
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
+ *
* @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
*
* @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
- * Index must be an actual index into the array.
- * If the server is already open, returns it.
+ *
+ * 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.
+ *
+ * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
*
* @note If disable() was called on this LoadBalancer, this method will throw a DBAccessError.
*
- * @param int $i Server index or DB_MASTER/DB_REPLICA
+ * @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 );
+ /**
+ * Get DB type of the server with the specified index
+ *
+ * @param int $i
+ * @return string One of (mysql,postgres,sqlite,...) or "unknown" for bad indexes
+ * @since 1.30
+ */
+ public function getServerType( $i );
+
/**
* Return the server info structure for a given index, or false if the index is invalid.
* @param int $i