const DOMAIN_ANY = '';
/** @var int DB handle should have DBO_TRX disabled and the caller will leave it as such */
+ const CONN_TRX_AUTOCOMMIT = 1;
+ /** @var int Alias for CONN_TRX_AUTOCOMMIT for b/c; deprecated since 1.31 */
const CONN_TRX_AUTO = 1;
/**
* - 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]
+ * - chronologyCallback: Callback to run before the first connection attempt [optional]
* - hostname : The name of the current server [optional]
* - cliMode: Whether the execution context is a CLI script. [optional]
* - profiler : Class name or instance with profileIn()/profileOut() methods. [optional]
* - queryLogger: PSR-3 logger instance. [optional]
* - perfLogger: PSR-3 logger instance. [optional]
* - errorLogger : Callback that takes an Exception and logs it. [optional]
+ * - deprecationLogger: Callback to log a deprecation warning. [optional]
* @throws InvalidArgumentException
*/
public function __construct( array $params );
/**
* Get any open connection to a given server index, local or foreign
*
+ * Use CONN_TRX_AUTOCOMMIT to only look for connections opened with that flag
+ *
* @param int $i Server index or DB_MASTER/DB_REPLICA
+ * @param int $flags Bitfield of CONN_* class constants
* @return Database|bool False if no such connection is open
*/
- public function getAnyOpenConnection( $i );
+ public function getAnyOpenConnection( $i, $flags = 0 );
/**
* Get a connection handle by server index
*
- * The CONN_TRX_AUTO flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
+ * The CONN_TRX_AUTOCOMMIT flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
* (e.g. sqlite) in order to avoid deadlocks. ILoadBalancer::getServerAttributes()
* can be used to check such flags beforehand.
*
- * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+ * If the caller uses $domain or sets CONN_TRX_AUTOCOMMIT 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 int $i Server index (overrides $groups) 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
*
* The handle's methods simply wrap those of a Database handle
*
- * The CONN_TRX_AUTO flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
+ * The CONN_TRX_AUTOCOMMIT flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
* (e.g. sqlite) in order to avoid deadlocks. ILoadBalancer::getServerAttributes()
* can be used to check such flags beforehand.
*
* @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)
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return DBConnRef
*/
public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
*
* The handle's methods simply wrap those of a Database handle
*
- * The CONN_TRX_AUTO flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
+ * The CONN_TRX_AUTOCOMMIT flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
* (e.g. sqlite) in order to avoid deadlocks. ILoadBalancer::getServerAttributes()
* can be used to check such flags beforehand.
*
* @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)
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return DBConnRef
*/
public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
*
* The handle's methods simply wrap those of a Database handle
*
- * The CONN_TRX_AUTO flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
+ * The CONN_TRX_AUTOCOMMIT flag is ignored for databases with ATTR_DB_LEVEL_LOCKING
* (e.g. sqlite) in order to avoid deadlocks. ILoadBalancer::getServerAttributes()
* can be used to check such flags beforehand.
*
* @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)
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return MaintainableDBConnRef
*/
public function getMaintenanceConnectionRef( $db, $groups = [], $domain = false, $flags = 0 );
* 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 for databases with ATTR_DB_LEVEL_LOCKING (e.g. sqlite) in
+ * Avoid using CONN_TRX_AUTOCOMMIT for databases with ATTR_DB_LEVEL_LOCKING (e.g. sqlite) in
* order to avoid deadlocks. ILoadBalancer::getServerAttributes() can be used to check
* such flags beforehand.
*
- * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+ * If the caller uses $domain or sets CONN_TRX_AUTOCOMMIT 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 (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)
+ * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return Database|bool Returns false on errors
* @throws DBAccessError
*/
* @param array[] $aliases Map of (table => (dbname, schema, prefix) map)
*/
public function setTableAliases( array $aliases );
+
+ /**
+ * Convert certain index names to alternative names before querying the DB
+ *
+ * Note that this applies to indexes regardless of the table they belong to.
+ *
+ * This can be employed when an index was renamed X => Y in code, but the new Y-named
+ * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA,
+ * the aliases can be removed, and then the old X-named indexes dropped.
+ *
+ * @param string[] $aliases
+ * @return mixed
+ * @since 1.31
+ */
+ public function setIndexAliases( array $aliases );
}