Helper class used for automatically marking an IDatabase connection as reusable (once it no longer matters which DB domain is selected) and for deferring the actual network connection. More...

Inheritance diagram for Wikimedia\Rdbms\DBConnRef:

[legend]

Collaboration diagram for Wikimedia\Rdbms\DBConnRef:

[legend]

Public Member Functions
	__call ( $name, array $arguments)

	__construct (ILoadBalancer $lb, $conn, $role)

	__destruct ()
	Clean up the connection when out of scope.

	__toString ()
	Get a debugging string that mentions the database type, the ID of this instance, and the ID of any underlying connection resource or driver object if one is present.

	addIdentifierQuotes ( $s)
	Escape a SQL identifier (e.g.

	addQuotes ( $s)
	Escape and quote a raw value string for use in a SQL query.

	affectedRows ()
	Get the number of rows affected by the last write query.

	aggregateValue ( $valuedata, $valuename='value')
	Return aggregated value alias.

	anyChar ()
	Returns a token for buildLike() that denotes a '_' to be used in a LIKE query.

	anyString ()
	Returns a token for buildLike() that denotes a '' to be used in a LIKE query.

	assertNoOpenTransactions ()
	Assert that all explicit transactions or atomic sections have been closed.

	begin ( $fname=__METHOD__, $mode=IDatabase::TRANSACTION_EXPLICIT)
	Begin a transaction.

	bitAnd ( $fieldLeft, $fieldRight)

	bitNot ( $field)

	bitOr ( $fieldLeft, $fieldRight)

	buildConcat ( $stringList)
	Build a concatenation list to feed into a SQL query.

	buildGreatest ( $fields, $values)
	Build a GREATEST function statement comparing columns/values.

	buildGroupConcatField ( $delim, $table, $field, $conds='', $join_conds=[])
	Build a GROUP_CONCAT or equivalent statement for a query.

	buildIntegerCast ( $field)

	buildLeast ( $fields, $values)
	Build a LEAST function statement comparing columns/values.

	buildLike ( $param,... $params)
	LIKE statement wrapper.

	buildSelectSubquery ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery.

	buildStringCast ( $field)

	buildSubstring ( $input, $startPosition, $length=null)

	cancelAtomic ( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
	Cancel an atomic section of SQL statements.

	clearFlag ( $flag, $remember=self::REMEMBER_NOTHING)
	Clear a flag for this connection.

	close ( $fname=__METHOD__, $owner=null)
	Close the database connection.

	commit ( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
	Commits a transaction previously started using begin()

	conditional ( $cond, $trueVal, $falseVal)
	Returns an SQL expression for a simple conditional.

	databasesAreIndependent ()
	Returns true if DBs are assumed to be on potentially different servers.

	dataSeek ( $res, $row)
	Change the position of the cursor in a result object.

	dbSchema ( $schema=null)
	Get/set the db schema.

	decodeBlob ( $b)
	Some DBMSs return a special placeholder object representing blob fields in result objects.

	decodeExpiry ( $expiry, $format=TS_MW)
	Decode an expiry time into a DBMS independent format.

	delete ( $table, $conds, $fname=__METHOD__)
	Delete all rows in a table that match a condition.

	deleteJoin ( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname=__METHOD__)
	DELETE where the condition is a join.

	doAtomicSection ( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
	Perform an atomic section of reversable SQL statements from a callback.

	encodeBlob ( $b)
	Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strings to be inserted.

	encodeExpiry ( $expiry)
	Encode an expiry time into the DBMS dependent format.

	endAtomic ( $fname=__METHOD__)
	Ends an atomic section of SQL statements.

	estimateRowCount ( $tables, $vars=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Estimate the number of rows in dataset.

	explicitTrxActive ()

	fetchObject ( $res)
	Fetch the next row from the given result object, in object form.

	fetchRow ( $res)
	Fetch the next row from the given result object, in associative array form.

	fieldExists ( $table, $field, $fname=__METHOD__)
	Determines whether a field exists in a table.

	fieldName ( $res, $n)
	Get a field name in a result object.

	flushSnapshot ( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
	Commit any transaction but error out if writes or callbacks are pending.

	freeResult ( $res)
	Free a result object returned by query() or select()

	getDBname ()
	Get the current DB name.

	getDomainID ()
	Return the currently selected domain ID.

	getFlag ( $flag)
	Returns a boolean whether the flag $flag is set for this connection.

	getInfinity ()
	Find out when 'infinity' is.

	getLag ()
	Get the amount of replication lag for this database server.

	getLBInfo ( $name=null)
	Get properties passed down from the server info array of the load balancer.

	getMasterPos ()
	Get the position of this master.

	getProperty ( $name)

	getReferenceRole ()

	getReplicaPos ()
	Get the replication position of this replica DB.

	getScopedLockAndFlush ( $lockKey, $fname, $timeout)
	Acquire a named lock, flush any transaction, and return an RAII style unlocker object.

	getServer ()
	Get the server hostname or IP address.

	getServerInfo ()
	Get a human-readable string describing the current software version.

	getServerUptime ()
	Determines how long the server has been up.

	getServerVersion ()
	A string describing the current software version, like from mysql_get_server_info()

	getSessionLagStatus ()
	Get the replica DB lag when the current transaction started or a general lag estimate if not transaction is active.

	getSoftwareLink ()
	Returns a wikitext style link to the DB's website (e.g.

	getTopologyRole ()
	Get the replication topology role of this server.

	getTopologyRootMaster ()
	Get the host (or address) of the root master server for the replication topology.

	getType ()
	Get the type of the DBMS (e.g.

	implicitOrderby ()
	Returns true if this database does an implicit order by when the column has an index For example: SELECT page_title FROM page LIMIT 1.

	indexExists ( $table, $index, $fname=__METHOD__)
	Determines whether an index exists.

	insert ( $table, $rows, $fname=__METHOD__, $options=[])
	Insert the given row(s) into a table.

	insertId ()
	Get the inserted value of an auto-increment row.

	insertSelect ( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
	INSERT SELECT wrapper.

	isOpen ()

	isReadOnly ()

	lastDoneWrites ()
	Get the last time the connection may have been used for a write query.

	lastErrno ()
	Get the last error number.

	lastError ()
	Get a description of the last error.

	lastQuery ()
	Get the last query that sent on account of IDatabase::query()

	limitResult ( $sql, $limit, $offset=false)
	Construct a LIMIT query with optional offset.

	lock ( $lockName, $method, $timeout=5)
	Acquire a named lock.

	lockForUpdate ( $table, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Lock all rows meeting the given conditions/options FOR UPDATE.

	lockIsFree ( $lockName, $method)
	Check to see if a named lock is not locked by any thread (non-blocking)

	makeList (array $a, $mode=self::LIST_COMMA)
	Makes an encoded list of strings from an array.

	makeWhereFrom2d ( $data, $baseKey, $subKey)
	Build a partial where clause from a 2-d array such as used for LinkBatch.

	masterPosWait (DBMasterPos $pos, $timeout)
	Wait for the replica DB to catch up to a given master position.

	maxListLen ()
	Return the maximum number of items allowed in a list, or 0 for unlimited.

	namedLocksEnqueue ()
	Check to see if a named lock used by lock() use blocking queues.

	newSelectQueryBuilder ()
	Create an empty SelectQueryBuilder which can be used to run queries against this connection.

	nextSequenceValue ( $seqName)
	Deprecated method, calls should be removed.

	numFields ( $res)
	Get the number of fields in a result object.

	numRows ( $res)
	Get the number of rows in a query result.

	onAtomicSectionCancel (callable $callback, $fname=__METHOD__)
	Run a callback when the atomic section is cancelled.

	onTransactionCommitOrIdle (callable $callback, $fname=__METHOD__)
	Run a callback as soon as there is no transaction pending.

	onTransactionIdle (callable $callback, $fname=__METHOD__)
	Alias for onTransactionCommitOrIdle() for backwards-compatibility.

	onTransactionPreCommitOrIdle (callable $callback, $fname=__METHOD__)
	Run a callback before the current transaction commits or now if there is none.

	onTransactionResolution (callable $callback, $fname=__METHOD__)
	Run a callback as soon as the current transaction commits or rolls back.

	pendingWriteCallers ()
	Get the list of method names that did write queries for this transaction.

	pendingWriteQueryDuration ( $type=self::ESTIMATE_TOTAL)
	Get the time spend running write queries for this transaction.

	pendingWriteRowsAffected ()
	Get the number of affected rows from pending write queries.

	ping (&$rtt=null)
	Ping the server and try to reconnect if it there is no connection.

	preCommitCallbacksPending ()

	query ( $sql, $fname=__METHOD__, $flags=0)
	Run an SQL query and return the result.

	replace ( $table, $uniqueKeys, $rows, $fname=__METHOD__)
	Insert row(s) into a table, deleting all conflicting rows beforehand.

	restoreFlags ( $state=self::RESTORE_PRIOR)
	Restore the flags to their prior state before the last setFlag/clearFlag call.

	rollback ( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
	Rollback a transaction previously started using begin()

	select ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Execute a SELECT query constructed using the various parameters provided.

	selectDB ( $db)
	Change the current database.

	selectDomain ( $domain)
	Set the current domain (database, schema, and table prefix)

	selectField ( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
	A SELECT wrapper which returns a single field from a single result row.

	selectFieldValues ( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
	A SELECT wrapper which returns a list of single field values from result rows.

	selectRow ( $table, $vars, $conds, $fname=__METHOD__, $options=[], $join_conds=[])
	Wrapper to IDatabase::select() that only fetches one row (via LIMIT)

	selectRowCount ( $tables, $vars=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Get the number of rows in dataset.

	selectSQLText ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Take the same arguments as IDatabase::select() and return the SQL it would use.

	serverIsReadOnly ()

	setBigSelects ( $value=true)
	Allow or deny "big selects" for this session only.

	setFlag ( $flag, $remember=self::REMEMBER_NOTHING)
	Set a flag for this connection.

	setIndexAliases (array $aliases)
	Convert certain index names to alternative names before querying the DB.

	setLBInfo ( $nameOrArray, $value=null)
	Set the entire array or a particular key of the managing load balancer info array.

	setSchemaVars ( $vars)
	Set schema variables to be used when streaming commands from SQL files or stdin.

	setSessionOptions (array $options)
	Override database's default behavior.

	setTableAliases (array $aliases)
	Make certain table names use their own database, schema, and table prefix when passed into SQL queries pre-escaped and without a qualified database name.

	setTransactionListener ( $name, callable $callback=null)
	Run a callback after each time any transaction commits or rolls back.

	startAtomic ( $fname=__METHOD__, $cancelable=IDatabase::ATOMIC_NOT_CANCELABLE)
	Begin an atomic section of SQL statements.

	strreplace ( $orig, $old, $new)
	Returns a SQL expression for simple string replacement (e.g.

	tableExists ( $table, $fname=__METHOD__)
	Query whether a given table exists.

	tablePrefix ( $prefix=null)
	Get/set the table prefix.

	timestamp ( $ts=0)
	Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for inserting into timestamp fields in this DBMS.

	timestampOrNull ( $ts=null)
	Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for inserting into timestamp fields in this DBMS.

	trxLevel ()
	Gets the current transaction level.

	trxTimestamp ()
	Get the UNIX timestamp of the time that the transaction was established.

	unionConditionPermutations ( $table, $vars, array $permute_conds, $extra_conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Construct a UNION query for permutations of conditions.

	unionQueries ( $sqls, $all)
	Construct a UNION query.

	unionSupportsOrderAndLimit ()
	Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION.

	unlock ( $lockName, $method)
	Release a lock.

	update ( $table, $set, $conds, $fname=__METHOD__, $options=[])
	Update all rows in a table that match a given condition.

	upsert ( $table, array $rows, $uniqueKeys, array $set, $fname=__METHOD__)
	Upsert the given row(s) into a table.

	wasConnectionLoss ()
	Determines if the last query error was due to a dropped connection.

	wasDeadlock ()
	Determines if the last failure was due to a deadlock.

	wasErrorReissuable ()
	Determines if the last query error was due to something outside of the query itself.

	wasLockTimeout ()
	Determines if the last failure was due to a lock timeout.

	wasReadOnlyError ()
	Determines if the last failure was due to the database being read-only.

	writesOrCallbacksPending ()
	Whether there is a transaction open with either possible write queries or unresolved pre-commit/commit/resolution callbacks pending.

	writesPending ()

Public Member Functions inherited from Wikimedia\Rdbms\IDatabase
	buildSubString ( $input, $startPosition, $length=null)
	Build a SUBSTRING function.

Protected Member Functions
	assertRoleAllowsWrites ()
	Error out if the role is not DB_MASTER.

	getDomainChangeException ()

Private Attributes
Database null	$conn
	Live connection handle.

ILoadBalancer	$lb

array	$params
	N-tuple of (server index, group, DatabaseDomain\|string)

int	$role
	One of DB_MASTER/DB_REPLICA.

const	FLD_DOMAIN = 2

const	FLD_FLAGS = 3

const	FLD_GROUP = 1

const	FLD_INDEX = 0

Detailed Description

Helper class used for automatically marking an IDatabase connection as reusable (once it no longer matters which DB domain is selected) and for deferring the actual network connection.

This uses an RAII-style pattern where calling code is expected to keep the returned reference handle as a function variable that falls out of scope when no longer needed. This avoids the need for matching reuseConnection() calls for every "return" statement as well as the tedious use of try/finally.

Example:: function getRowData() {

$conn = $this->lb->getConnectedRef( DB_REPLICA );

$row = $conn->select( ... );

return $row ? (array)$row : false;

// $conn falls out of scope and $this->lb->reuseConnection() gets called

}

DB_REPLICA
const DB_REPLICA
Definition defines.php:25

Since: 1.22

Definition at line 29 of file DBConnRef.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\DBConnRef::__construct	(	ILoadBalancer	$lb,
			$conn,
			$role
	)

Parameters

ILoadBalancer	$lb	Connection manager for $conn
IDatabase \| array	$conn	Database or (server index, query groups, domain, flags)
int	$role	The type of connection asked for; one of DB_MASTER/DB_REPLICA

Definition at line 50 of file DBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\$conn, Wikimedia\Rdbms\DBConnRef\$lb, and Wikimedia\Rdbms\DBConnRef\$role.

◆ __destruct()

Wikimedia\Rdbms\DBConnRef::__destruct ( )

Clean up the connection when out of scope.

Definition at line 801 of file DBConnRef.php.

Member Function Documentation

◆ __call()

Wikimedia\Rdbms\DBConnRef::__call	(		$name,
		array	$arguments
	)

Definition at line 62 of file DBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\$params.

◆ __toString()

Wikimedia\Rdbms\DBConnRef::__toString ( )

Get a debugging string that mentions the database type, the ID of this instance, and the ID of any underlying connection resource or driver object if one is present.

Returns: string "<db type> object #<X>" or "<db type> object #<X> (resource/handle id #<Y>)"

Since: 1.34

Wikimedia\Rdbms\DBConnRef::aggregateValue	(	$valuedata,
		$valuename = `'value'`
	)

Wikimedia\Rdbms\DBConnRef::begin	(	$fname = `__METHOD__`,
		$mode = `IDatabase::TRANSACTION_EXPLICIT`
	)

string	$fname	Calling function name
string	$mode	A situationally valid IDatabase::TRANSACTION_* constant [optional]

Wikimedia\Rdbms\DBConnRef::bitAnd	(	$fieldLeft,
		$fieldRight
	)

Wikimedia\Rdbms\DBConnRef::bitOr	(	$fieldLeft,
		$fieldRight
	)

Wikimedia\Rdbms\DBConnRef::buildGreatest	(	$fields,
		$values
	)

string \| string[]	$fields	Name(s) of column(s) with values to compare
string \| int \| float \| string[] \| int[] \| float[]	$values	Values to compare

Wikimedia\Rdbms\DBConnRef::buildGroupConcatField	(	$delim,
		$table,
		$field,
		$conds = `''`,
		$join_conds = `[]`
	)

string	$delim	Glue to bind the results together
string \| array	$table	Table name
string	$field	Field name
string \| array	$conds	Conditions
string \| array	$join_conds	Join conditions

array[] \| string \| LikeMatch	$param
	string\|LikeMatch	...$params

array	$valuedata
string	$valuename

Wikimedia\Rdbms\DBConnRef::buildSelectSubquery	(	$table,
		$vars,
		$conds = `''`,
		$fname = `__METHOD__`,
		$options = `[]`,
		$join_conds = `[]`
	)

Wikimedia\Rdbms\DBConnRef::buildSubstring	(	$input,
		$startPosition,
		$length = `null`
	)

Wikimedia\Rdbms\DBConnRef::cancelAtomic	(		$fname = `__METHOD__`,
		AtomicSectionIdentifier	$sectionId = `null`
	)

string	$fname
AtomicSectionIdentifier \| null	$sectionId	Section ID from startAtomic(); passing this enables cancellation of unclosed nested sections [optional]

Wikimedia\Rdbms\DBConnRef::clearFlag	(	$flag,
		$remember = `self::REMEMBER_NOTHING`
	)

int	$flag	One of (IDatabase::DBO_DEBUG, IDatabase::DBO_TRX)
string	$remember	IDatabase::REMEMBER_* constant [default: REMEMBER_NOTHING]

Wikimedia\Rdbms\DBConnRef::close	(	$fname = `__METHOD__`,
		$owner = `null`
	)

string	$fname	Caller name
int \| null	$owner	ID of the calling instance (e.g. the LBFactory ID)

Wikimedia\Rdbms\DBConnRef::commit	(	$fname = `__METHOD__`,
		$flush = `self::FLUSHING_ONE`
	)

Wikimedia\Rdbms\DBConnRef::conditional	(	$cond,
		$trueVal,
		$falseVal
	)

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

◆ __destruct()

Member Function Documentation

◆ __call()

◆ __toString()

◆ addIdentifierQuotes()

◆ addQuotes()

◆ affectedRows()

◆ aggregateValue()

◆ anyChar()

◆ anyString()

◆ assertNoOpenTransactions()

◆ assertRoleAllowsWrites()

◆ begin()

◆ bitAnd()

◆ bitNot()

◆ bitOr()

◆ buildConcat()

◆ buildGreatest()

◆ buildGroupConcatField()

◆ buildIntegerCast()

◆ buildLeast()

◆ buildLike()

◆ buildSelectSubquery()

◆ buildStringCast()

◆ buildSubstring()

◆ cancelAtomic()

◆ clearFlag()

◆ close()

◆ commit()

◆ conditional()

◆ databasesAreIndependent()

◆ dataSeek()

◆ dbSchema()

◆ decodeBlob()

◆ decodeExpiry()

◆ delete()

◆ deleteJoin()

◆ doAtomicSection()

◆ encodeBlob()

◆ encodeExpiry()

◆ endAtomic()

◆ estimateRowCount()

◆ explicitTrxActive()

◆ fetchObject()

◆ fetchRow()

◆ fieldExists()

◆ fieldName()

◆ flushSnapshot()

◆ freeResult()

◆ getDBname()

◆ getDomainChangeException()

◆ getDomainID()

◆ getFlag()

◆ getInfinity()

◆ getLag()

◆ getLBInfo()

◆ getMasterPos()

◆ getProperty()

◆ getReferenceRole()

◆ getReplicaPos()

◆ getScopedLockAndFlush()

◆ getServer()

◆ getServerInfo()

◆ getServerUptime()

◆ getServerVersion()

◆ getSessionLagStatus()

◆ getSoftwareLink()

◆ getTopologyRole()

◆ getTopologyRootMaster()

◆ getType()

◆ implicitOrderby()

◆ indexExists()

◆ insert()

◆ insertId()

string \| array	$cond	SQL expression which will result in a boolean value
string	$trueVal	SQL expression to return if true
string	$falseVal	SQL expression to return if false

Wikimedia\Rdbms\DBConnRef::decodeExpiry	(	$expiry,
		$format = `TS_MW`
	)

string	$expiry	DB timestamp field value for expiry
int	$format	TS_* constant, defaults to TS_MW

Wikimedia\Rdbms\DBConnRef::delete	(	$table,
		$conds,
		$fname = `__METHOD__`
	)

Wikimedia\Rdbms\DBConnRef::deleteJoin	(	$delTable,
		$joinTable,
		$delVar,
		$joinVar,
		$conds,
		$fname = `__METHOD__`
	)

string	$delTable	The table to delete from.
string	$joinTable	The other table.
string	$delVar	The variable to join on, in the first table.
string	$joinVar	The variable to join on, in the second table.
array \| string	$conds	Condition array of field names mapped to variables, ANDed together in the WHERE clause
string	$fname	Calling function name (use METHOD) for logs/profiling

Wikimedia\Rdbms\DBConnRef::doAtomicSection	(		$fname,
		callable	$callback,
			$cancelable = `self::ATOMIC_NOT_CANCELABLE`
	)

string	$fname	Caller name (usually METHOD)
callable	$callback	Callback that issues DB updates
string	$cancelable	Pass self::ATOMIC_CANCELABLE to use a savepoint and enable self::cancelAtomic() for this section.

DBError	If an error occurs, see IDatabase::query()
Exception	If an error occurs in the callback

Wikimedia\Rdbms\DBConnRef::estimateRowCount	(	$tables,
		$var = `' *'`,
		$conds = `''`,
		$fname = `__METHOD__`,
		$options = `[]`,
		$join_conds = `[]`
	)