Wikimedia\Rdbms\Database Class Reference

Relational database abstraction object. More...

Inheritance diagram for Wikimedia\Rdbms\Database:

Collaboration diagram for Wikimedia\Rdbms\Database:

Public Member Functions
	__clone ()
	Make sure that copies do not share the same client binding handle.
	__construct (array $params)
	__destruct ()
	Run a few simple sanity checks and close dangling connections.
	__sleep ()
	Called by serialize.
	__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.table, column, database) for use in a SQL queryDepending on the database this will either be backticks or "double quotes" Parameters string $s Returns string Since 1.33
	addQuotes ( $s)
	Escape and quote a raw value string for use in a SQL query. Parameters string | int | float | null | bool | Blob $s Returns string
	affectedRows ()
	Get the number of rows affected by the last write query.
	aggregateValue ( $valuedata, $valuename='value')
	Return aggregated value alias. Parameters array $valuedata string $valuename Returns array|string Deprecated: Since 1.33
	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=self::TRANSACTION_EXPLICIT)
	Begin a transaction.
	bitAnd ( $fieldLeft, $fieldRight)
	Parameters string | int $fieldLeft string | int $fieldRight Returns string
	bitNot ( $field)
	Parameters string | int $field Returns string
	bitOr ( $fieldLeft, $fieldRight)
	Parameters string | int $fieldLeft string | int $fieldRight Returns string
	buildConcat ( $stringList)
	Build a concatenation list to feed into a SQL query. Parameters string[] $stringList Raw SQL expression list; caller is responsible for escaping Returns string
	buildGreatest ( $fields, $values)
	Build a GREATEST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases. Parameters string | string[] $fields Name(s) of column(s) with values to compare string | int | float | string[] | int[] | float[] $values Values to compare Returns mixed Since 1.35
	buildGroupConcatField ( $delim, $table, $field, $conds='', $join_conds=[])
	Build a GROUP_CONCAT or equivalent statement for a query.This is useful for combining a field for several rows into a single string. NULL values will not appear in the output, duplicated values will appear, and the resulting delimiter-separated values have no defined sort order. Code using the results may need to use the PHP unique() or sort() methods. Parameters 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 Returns string SQL text Since 1.23
	buildIntegerCast ( $field)
	Parameters string $field Field or column to cast Returns string Since 1.31
	buildLeast ( $fields, $values)
	Build a LEAST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases. Parameters string | string[] $fields Name(s) of column(s) with values to compare string | int | float | string[] | int[] | float[] $values Values to compare Returns mixed Since 1.35
	buildLike ( $param,... $params)
	LIKE statement wrapper.This takes a variable-length argument list with parts of pattern to match containing either string literals that will be escaped or tokens returned by anyChar() or anyString(). Alternatively, the function could be provided with an array of aforementioned parameters.Example: $dbr->buildLike( 'My_page_title/', $dbr->anyString() ) returns a LIKE clause that searches for subpages of 'My page title'. Alternatively: $pattern = [ 'My_page_title/', $dbr->anyString() ]; $query .= $dbr->buildLike( $pattern ); Since 1.16 Parameters array[] | string | LikeMatch $param string|LikeMatch ...$params Returns string Fully built LIKE statement
	buildSelectSubquery ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery.
	buildStringCast ( $field)
	Parameters string $field Field or column to cast Returns string Since 1.28
	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, $caseTrueExpression, $caseFalseExpression)
	Returns an SQL expression for a simple conditional.This doesn't need to be overridden unless CASE isn't supported in the RDBMS. Parameters string | array $cond SQL condition expression (yields a boolean) string $caseTrueExpression SQL expression to return when the condition is true string $caseFalseExpression SQL expression to return when the condition is false Returns string SQL fragment
	connectionErrorLogger ( $errno, $errstr)
	Error handler for logging errors during database connection.
	databasesAreIndependent ()
	Returns true if DBs are assumed to be on potentially different servers.In systems like mysql/mariadb, different databases can easily be referenced on a single connection merely by name, even in a single query via JOIN. On the other hand, Postgres treats databases as logically separate, with different database users, requiring special mechanisms like postgres_fdw to "mount" foreign DBs. This is true even among DBs on the same server. Changing the selected database via selectDomain() requires a new connection. Returns bool Since 1.29
	dataSeek (IResultWrapper $res, $pos)
	Change the position of the cursor in a result object.
	dbSchema ( $schema=null)
	Get/set the db schema.
	deadlockLoop (... $args)
	Perform a deadlock-prone transaction.This function invokes a callback function to perform a set of write queries. If a deadlock occurs during the processing, the transaction will be rolled back and the callback function will be called again.Avoid using this method outside of Job or Maintenance classes.Usage: $dbw->deadlockLoop( callback, ... );Extra arguments are passed through to the specified callback function. This method requires that no transactions are already active to avoid causing premature commits or exceptions.Returns whatever the callback function returned on its successful, iteration, or false on error, for example if the retry limit was reached. Parameters mixed ...$args Returns mixed Exceptions DBUnexpectedError Exception
	decodeBlob ( $b)
	Some DBMSs return a special placeholder object representing blob fields in result objects.Pass the object through this function to return the original string. Parameters string | Blob $b Returns string Exceptions DBError
	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.MySQL overrides this to use a multi-table DELETE syntax, in other databases we use sub-selectsFor safety, an empty $conds will not delete everything. If you want to delete all rows where the join condition matches, set $conds=IDatabase::ALL_ROWS.DO NOT put the join condition in $conds. Parameters 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 Exceptions DBError If an error occurs, { See also query}
	doAtomicSection ( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
	Perform an atomic section of reversable SQL statements from a callback.
	dropTable ( $table, $fname=__METHOD__)
	Delete a table.
	duplicateTableStructure ( $oldName, $newName, $temporary=false, $fname=__METHOD__)
	Creates a new table with structure copied from existing table.Note that unlike most database abstraction functions, this function does not automatically append database prefix, because it works at a lower abstraction level. The table names passed to this function shall not be quoted (this function calls addIdentifierQuotes() when needed). Parameters string $oldName Name of table whose structure should be copied string $newName Name of table to be created bool $temporary Whether the new table should be temporary string $fname Calling function name Returns bool True if operation was successful Exceptions RuntimeException
	encodeBlob ( $b)
	Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strings to be inserted.To insert into such a field, pass the data through this function before passing it to IDatabase::insert(). Parameters string $b Returns string|Blob Exceptions DBError
	encodeExpiry ( $expiry)
	Encode an expiry time into the DBMS dependent format.
	endAtomic ( $fname=__METHOD__)
	Ends an atomic section of SQL statements.
	estimateRowCount ( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
	Estimate the number of rows in dataset.MySQL allows you to estimate the number of rows that would be returned by a SELECT query, using EXPLAIN SELECT. The estimate is provided using index cardinality statistics, and is notoriously inaccurate, especially when large numbers of rows have recently been added or deleted.For DBMSs that don't support fast result size estimation, this function will actually perform the SELECT COUNT(*).Takes the same arguments as IDatabase::select(). Parameters string | string[] $tables Table name(s) string $var Column for which NULL values are not counted [default "*"] array | string $conds Filters on the table string $fname Function name for profiling array $options Options for select array | string $join_conds Join conditions Returns int Row count Exceptions DBError If an error occurs, { See also query}
	explicitTrxActive ()
	fetchObject (IResultWrapper $res)
	Fetch the next row from the given result object, in object form.
	fetchRow (IResultWrapper $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 (IResultWrapper $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 (IResultWrapper $res)
	Free a result object returned by query() or select()
	getDBname ()
	Get the current database name; null if there isn't one.
	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.Most DBMSes support this. This is a special keyword for timestamps in PostgreSQL, and works with CHAR(14) as well because "i" sorts after all numbers. Returns string
	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 ()
	getPrimaryPos ()
	Get the position of this primary DB. Returns DBPrimaryPos|bool False if this is not a primary DB Exceptions DBError If an error occurs, { See also query} Since 1.37
	getReplicaPos ()
	Get the replication position of this replica DB. Returns DBPrimaryPos|bool False if this is not a replica DB Exceptions DBError If an error occurs, { See also query}
	getScopedLockAndFlush ( $lockKey, $fname, $timeout)
	Acquire a named lock, flush any transaction, and return an RAII style unlocker object.
	getServer ()
	Get the hostname or IP address of the server.
	getServerInfo ()
	Get a human-readable string describing the current software version.
	getServerName ()
	Get the readable name for the server.
	getServerUptime ()
	Determines how long the server has been up. Returns int Exceptions DBError
	getSessionLagStatus ()
	Get the replica DB lag when the current transaction started or a general lag estimate if not transaction is active.
	getTopologyBasedServerId ()
	Get a non-recycled ID that uniquely identifies this server within the replication topology.
	getTopologyRole ()
	Get the replication topology role of this server.
	getTopologyRootMaster ()
	getTopologyRootPrimary ()
	Get the readable name of the sole root primary DB server for the replication topology.
	ignoreIndexClause ( $index)
	IGNORE INDEX clause.
	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. Returns bool
	indexExists ( $table, $index, $fname=__METHOD__)
	Determines whether an index exists.
	indexInfo ( $table, $index, $fname=__METHOD__)
	Get information about an index into an object.
	indexUnique ( $table, $index, $fname=__METHOD__)
	Determines if a given index is unique. Parameters string $table string $index string $fname Calling function name Returns bool
	initConnection ()
	Initialize the connection to the database over the wire (or to local files)
	insert ( $table, $rows, $fname=__METHOD__, $options=[])
	Insert the given row(s) into a table.
	insertSelect ( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
	INSERT SELECT wrapper.
	isOpen ()
	isQuotedIdentifier ( $name)
	Returns if the given identifier looks quoted or not according to the database convention for quoting identifiers.
	isReadOnly ()
	lastDoneWrites ()
	Get the last time the connection may have been used for a write query.
	lastQuery ()
	Get the last query that sent on account of IDatabase::query()
	limitResult ( $sql, $limit, $offset=false)
	Construct a LIMIT query with optional offset.The SQL should be adjusted so that only the first $limit rows are returned. If $offset is provided as well, then the first $offset rows should be discarded, and the next $limit rows should be returned. If the result of the query is not ordered, then the rows to be returned are theoretically arbitrary.$sql is expected to be a SELECT, if that makes a difference. Parameters string $sql SQL query we will append the limit too int $limit The SQL limit int | bool $offset The SQL offset (default false) Returns string Since 1.34
	listTables ( $prefix=null, $fname=__METHOD__)
	List all tables on the database. Parameters string | null $prefix Only show tables with this prefix, e.g. mw_ string $fname Calling function name Exceptions DBError Returns array
	listViews ( $prefix=null, $fname=__METHOD__)
	Lists all the VIEWs in the database. Parameters string | null $prefix Only show VIEWs with this prefix, eg. unit_test_ string $fname Name of calling function Exceptions RuntimeException Returns array
	lock ( $lockName, $method, $timeout=5, $flags=0)
	Acquire a named lock.Named locks are not related to transactions Parameters string $lockName Name of lock to aquire string $method Name of the calling method int $timeout Acquisition timeout in seconds (0 means non-blocking) int $flags Bit field of IDatabase::LOCK_* constants Returns bool Success Exceptions DBError If an error occurs, { See also query}
	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) Parameters string $lockName Name of lock to poll string $method Name of method calling us Returns bool Exceptions DBError If an error occurs, { See also query} Since 1.20
	lockTables (array $read, array $write, $method)
	Lock specific tables.
	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 (DBPrimaryPos $pos, $timeout)
	Deprecated: since 1.37; use primaryPosWait() instead. Parameters DBPrimaryPos $pos int $timeout The maximum number of seconds to wait for synchronisation Returns int|null Zero if the replica DB was past that position already, greater than zero if we waited for some period of time, less than zero if it timed out, and null on error Exceptions DBError If an error occurs, { See also query}
	maxListLen ()
	Return the maximum number of items allowed in a list, or 0 for unlimited. Returns int
	namedLocksEnqueue ()
	Check to see if a named lock used by lock() use blocking queues. Returns bool Since 1.26
	newSelectQueryBuilder ()
	Create an empty SelectQueryBuilder which can be used to run queries against this connection. Returns SelectQueryBuilder
	nextSequenceValue ( $seqName)
	Deprecated method, calls should be removed.
	numFields (IResultWrapper $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 when the current transaction commits or now if there is none.
	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 when the current transaction commits or rolls back.
	pendingWriteAndCallbackCallers ()
	List the methods that have write queries or callbacks for the current transaction.
	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 ()
	primaryPosWait (DBPrimaryPos $pos, $timeout)
	Wait for the replica DB to catch up to a given primary DB position.Note that this does not start any new transactions. If any existing transaction is flushed, and this is called, then queries will reflect the point the DB was synced up to (on success) without interference from REPEATABLE-READ snapshots. Parameters DBPrimaryPos $pos int $timeout The maximum number of seconds to wait for synchronisation Returns int|null Zero if the replica DB was past that position already, greater than zero if we waited for some period of time, less than zero if it timed out, and null on error Exceptions DBError If an error occurs, { See also query} Since 1.37
	query ( $sql, $fname=__METHOD__, $flags=self::QUERY_NORMAL)
	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.
	reportQueryError ( $error, $errno, $sql, $fname, $ignore=false)
	Report a query error.
	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()
	runOnTransactionIdleCallbacks ( $trigger, array &$errors=[])
	Consume and run any "on transaction idle/resolution" callbacks.
	runOnTransactionPreCommitCallbacks ()
	Consume and run any "on transaction pre-commit" callbacks.
	runTransactionListenerCallbacks ( $trigger, array &$errors=[])
	Actually run any "transaction listener" callbacks.
	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, $var=' *', $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.This can be useful for making UNION queries, where the SQL text of each query is needed. In general, however, callers outside of Database classes should just use select(). See also IDatabase::select() Parameters string | array $table Table name string | array $vars Field names string | array $conds Conditions string $fname Caller function name string | array $options Query options string | array $join_conds Join conditions Returns string SQL query string
	serverIsReadOnly ()
	Returns bool Whether the DB is marked as read-only server-side Exceptions DBError If an error occurs, { See also query} Since 1.28
	setBigSelects ( $value=true)
	Allow or deny "big selects" for this session only.This is done by setting the sql_big_selects session variable.This is a MySQL-specific feature. Parameters bool | string $value True for allow, false for deny, or "default" to restore the initial value
	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.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. Parameters string[] $aliases Since 1.31
	setLBInfo ( $nameOrArray, $value=null)
	Set the entire array or a particular key of the managing load balancer info array.
	setLogger (LoggerInterface $logger)
	Set the PSR-3 logger interface to use for query logging.
	setSchemaVars ( $vars)
	Set schema variables to be used when streaming commands from SQL files or stdin.
	setSessionOptions (array $options)
	Override database's default behavior.$options include: 'connTimeout' : Set the connection timeout value in seconds. May be useful for very long batch queries such as full-wiki dumps, where a single query reads out over hours or days. Parameters array $options Returns void Exceptions DBError If an error occurs, { See also query}
	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.For example, "user" can be converted to "myschema.mydbname.user" for convenience. Appearances like user, somedb.user, somedb.someschema.user will used literally.Calling this twice will completely clear any old table aliases. Also, note that callers are responsible for making sure the schemas and databases actually exist. Parameters array[] $aliases Map of (table => (dbname, schema, prefix) map) Since 1.28
	setTransactionListener ( $name, callable $callback=null)
	Run a callback after each time any transaction commits or rolls back.
	setTrxEndCallbackSuppression ( $suppress)
	Whether to disable running of post-COMMIT/ROLLBACK callbacks.
	sourceFile ( $filename, callable $lineCallback=null, callable $resultCallback=null, $fname=false, callable $inputCallback=null)
	Read and execute SQL commands from a file.
	sourceStream ( $fp, callable $lineCallback=null, callable $resultCallback=null, $fname=__METHOD__, callable $inputCallback=null)
	Read and execute commands from an open file handle.
	startAtomic ( $fname=__METHOD__, $cancelable=self::ATOMIC_NOT_CANCELABLE)
	Begin an atomic section of SQL statements.
	streamStatementEnd (&$sql, &$newLine)
	Called by sourceStream() to check if we've reached a statement end.
	strencode ( $s)
	Wrapper for addslashes()
	strreplace ( $orig, $old, $new)
	Returns a SQL expression for simple string replacement (e.g.REPLACE() in mysql) Parameters string $orig Column to modify string $old Column to seek string $new Column to replace with Returns string
	tableExists ( $table, $fname=__METHOD__)
	Query whether a given table exists.
	tableLocksHaveTransactionScope ()
	Checks if table locks acquired by lockTables() are transaction-bound in their scope.
	tableName ( $name, $format='quoted')
	Format a table name ready for use in constructing an SQL query.This does two important things: it quotes the table names to clean them up, and it adds a table prefix if only given a table name with no quotes.All functions of this object which require a table name call this function themselves. Pass the canonical name to such functions. This is only needed when calling query() directly. Note This function does not sanitize user input. It is not safe to use this function to escape user input. Parameters string $name Database table name string $format One of: quoted - Automatically pass the table name through addIdentifierQuotes() so that it can be used in a query. raw - Do not add identifier quotes to the table name Returns string Full database name
	tableNames (... $tables)
	Fetch a number of table names into an array This is handy when you need to construct SQL for joins.
	tableNamesN (... $tables)
	Fetch a number of table names into an zero-indexed numerical array This is handy when you need to construct SQL for joins.
	tablePrefix ( $prefix=null)
	Get/set the table prefix.
	textFieldSize ( $table, $field)
	Returns the size of a text field, or -1 for "unlimited". Parameters string $table string $field Returns int
	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.The result is unquoted, and needs to be passed through addQuotes() before it can be included in raw SQL. Parameters string | int $ts Returns string
	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.
	truncate ( $tables, $fname=__METHOD__)
	Delete all data in a table(s) and reset any sequences owned by that table(s)
	trxLevel ()
	Gets the current transaction level.
	trxStatus ()
	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.This is used for providing overload point for other DB abstractions not compatible with the MySQL syntax. Parameters array $sqls SQL statements to combine bool $all Either IDatabase::UNION_ALL or IDatabase::UNION_DISTINCT Returns string SQL fragment
	unionSupportsOrderAndLimit ()
	Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION. Returns bool
	unlock ( $lockName, $method)
	Release a lock.Named locks are not related to transactions Parameters string $lockName Name of lock to release string $method Name of the calling method Returns bool Success Exceptions DBError If an error occurs, { See also query}
	unlockTables ( $method)
	Unlock all tables locked via lockTables()
	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.
	useIndexClause ( $index)
	USE INDEX clause.
	wasConnectionError ( $errno)
	Do not use this method outside of Database/DBError classes.
	wasConnectionLoss ()
	Determines if the last query error was due to a dropped connection.Note that during a connection loss, the prior transaction will have been lost Returns bool Since 1.31
	wasDeadlock ()
	Determines if the last failure was due to a deadlock.Note that during a deadlock, the prior transaction will have been lost Returns bool
	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.Note that during a lock wait timeout, the prior transaction will have been lost Returns bool
	wasReadOnlyError ()
	Determines if the last failure was due to the database being read-only. Returns bool
	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.
	getServerVersion ()
	A string describing the current software version, like from mysql_get_server_info()
	getSoftwareLink ()
	Returns a wikitext style link to the DB's website (e.g.
	getType ()
	Get the RDBMS type of the server (e.g.
	insertId ()
	Get the inserted value of an auto-increment row.
	lastErrno ()
	Get the last error number.
	lastError ()
	Get a description of the last error.
Public Member Functions inherited from Wikimedia\Rdbms\IMaintainableDatabase
	fieldInfo ( $table, $field)
	Get information about a field Returns false if the field doesn't exist.

Static Public Member Functions
static	attributesFromType ( $dbType, $driver=null)
static	factory ( $type, $params=[], $connect=self::NEW_CONNECTED)
	Construct a Database subclass instance given a database type and parameters.
static	getCacheSetOptions (?IDatabase ... $dbs)
	Merge the result of getSessionLagStatus() for several DBs using the most pessimistic values to estimate the lag of any data derived from them in combination.

Protected Member Functions
	assertBuildSubstringParams ( $startPosition, $length)
	Check type and bounds for parameters to self::buildSubstring()
	assertConditionIsNotEmpty ( $conds, string $fname, bool $deprecate)
	Check type and bounds conditions parameters for update.
	assertHasConnectionHandle ()
	Make sure there is an open connection handle (alive or not) as a sanity check.
	assertIsWritableMaster ()
	assertIsWritablePrimary ()
	Make sure that this server is not marked as a replica nor read-only as a sanity check.
	assertValidUpsertRowArray (array $rows, array $identityKey)
	assertValidUpsertSetArray (array $set, array $identityKey, array $rows)
	buildSuperlative ( $sqlfunc, $fields, $values)
	Build a superlative function statement comparing columns/values.
	closeConnection ()
	Closes underlying database connection.
	commenceCriticalSection (string $fname)
	Demark the start of a critical section of session/transaction state changes.
	completeCriticalSection (string $fname, ?CriticalSectionScope $csm, Throwable $trxError=null)
	Demark the completion of a critical section of session/transaction state changes.
	doBegin ( $fname)
	Issues the BEGIN command to the database server.
	doCommit ( $fname)
	Issues the COMMIT command to the database server.
	doDropTable ( $table, $fname)
	doGetLag ()
	Get the amount of replication lag for this database server.
	doHandleSessionLossPreconnect ()
	Reset any additional subclass trx* and session* fields.
	doInitConnection ()
	Actually connect to the database over the wire (or to local files)
	doInsert ( $table, array $rows, $fname)
	doInsertNonConflicting ( $table, array $rows, $fname)
	doInsertSelectGeneric ( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds)
	Implementation of insertSelect() based on select() and insert()
	doInsertSelectNative ( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds)
	Native server-side implementation of insertSelect() for situations where we don't want to select everything into memory.
	doLock (string $lockName, string $method, int $timeout)
	doLockIsFree (string $lockName, string $method)
	doLockTables (array $read, array $write, $method)
	Helper function for lockTables() that handles the actual table locking.
	doQuery ( $sql)
	Run a query and return a DBMS-dependent wrapper or boolean.
	doReleaseSavepoint ( $identifier, $fname)
	Release a savepoint.
	doReplace ( $table, array $identityKey, array $rows, $fname)
	doRollback ( $fname)
	Issues the ROLLBACK command to the database server.
	doRollbackToSavepoint ( $identifier, $fname)
	Rollback to a savepoint.
	doSavepoint ( $identifier, $fname)
	Create a savepoint.
	doSelectDomain (DatabaseDomain $domain)
	doTruncate (array $tables, $fname)
	doUnlock (string $lockName, string $method)
	doUnlockTables ( $method)
	Helper function for unlockTables() that handles the actual table unlocking.
	doUpsert (string $table, array $rows, array $identityKey, array $set, string $fname)
	escapeLikeInternal ( $s, $escapeChar='`')
	executeQuery ( $sql, $fname, $flags)
	Execute a query, retrying it if there is a recoverable connection loss.
	extractSingleFieldFromList ( $var)
	fetchAffectedRowCount ()
	fieldHasBit (int $flags, int $bit)
	fieldNamesWithAlias ( $fields)
	Gets an array of aliased field names.
	fieldNameWithAlias ( $name, $alias=false)
	Get an aliased field name e.g.
	getApproximateLagStatus ()
	Get a replica DB lag estimate for this server at the start of a transaction.
	getBindingHandle ()
	Get the underlying binding connection handle.
	getDefaultSchemaVars ()
	Get schema variables to use if none have been set via setSchemaVars().
	getLastPHPError ()
	getLazyMasterHandle ()
	Get a handle to the primary DB server of the cluster to which this server belongs.
	getLogContext (array $extras=[])
	Create a log context to pass to PSR-3 logger functions.
	getQueryVerb ( $sql)
	getReadOnlyReason ()
	getRecordedTransactionLagStatus ()
	Get the replica DB lag when the current transaction started.
	getSchemaVars ()
	Get schema variables.
	getTempTableWrites ( $sql, $pseudoPermanent)
	getTransactionRoundId ()
	indexName ( $index)
	Allows for index remapping in queries where this is not consistent across DBMS.
	installErrorHandler ()
	Set a custom error handler for logging errors during database connection.
	isFlagInOptions ( $option, array $options)
	isInsertSelectSafe (array $insertOptions, array $selectOptions)
	isPristineTemporaryTable ( $table)
	Check if the table is both a TEMPORARY table and has not yet received CRUD operations.
	isTransactableQuery ( $sql)
	Determine whether a SQL statement is sensitive to isolation level.
	isWriteQuery ( $sql, $flags)
	Determine whether a query writes to the DB.
	makeGroupByWithHaving ( $options)
	Returns an optional GROUP BY with an optional HAVING.
	makeInsertLists (array $rows)
	Make SQL lists of columns, row tuples for INSERT/VALUES expressions.
	makeInsertNonConflictingVerbAndOptions ()
	makeOrderBy ( $options)
	Returns an optional ORDER BY.
	makeSelectOptions (array $options)
	Returns an optional USE INDEX clause to go after the table, and a string to go at the end of the query.
	makeUpdateOptions ( $options)
	Make UPDATE options for the Database::update function.
	makeUpdateOptionsArray ( $options)
	Make UPDATE options array for Database::makeUpdateOptions.
	newExceptionAfterConnectError ( $error)
	normalizeConditions ( $conds, $fname)
	normalizeOptions ( $options)
	normalizeRowArray (array $rowOrRows)
	normalizeUpsertParams ( $uniqueKeys, &$rows)
	Validate and normalize parameters to upsert() or replace()
	open ( $server, $user, $password, $db, $schema, $tablePrefix)
	Open a new connection to the database (closing any existing one)
	qualifiedTableComponents ( $name)
	Get the table components needed for a query given the currently selected database.
	registerTempWrites ( $ret, array $changes)
	relationSchemaQualifier ()
	replaceLostConnection ( $fname)
	Close any existing (dead) database connection and open a new connection.
	replaceVars ( $ins)
	Database-independent variable replacement.
	restoreErrorHandler ()
	Restore the previous error handler and return the last PHP error for this DB.
	tableNamesWithIndexClauseOrJOIN ( $tables, $use_index=[], $ignore_index=[], $join_conds=[])
	Get the aliased table name clause for a FROM clause which might have a JOIN and/or USE INDEX or IGNORE INDEX clause.
	tableNameWithAlias ( $table, $alias=false)
	Get an aliased table name.
	wasKnownStatementRollbackError ()
	wasQueryTimeout ( $error, $errno)
	Checks whether the cause of the error is detected to be a timeout.

Static Protected Member Functions
static	getAttributes ()

Protected Attributes
int null	$affectedRowCount
	Rows affected by the last query to query() or its CRUD wrappers.
string	$agent
	Agent name for query profiling.
bool	$cliMode
	Whether this PHP instance is for a CLI script.
object resource null	$conn
	Database connection.
array< string, mixed >	$connectionParams
	Connection parameters used by initConnection() and open()
string[] int[] float[]	$connectionVariables
	SQL variables values to use for all new connections.
LoggerInterface	$connLogger
CriticalSectionProvider null	$csProvider
DatabaseDomain	$currentDomain
string	$delimiter = ';'
	Current SQL query delimiter.
callable	$deprecationLogger
	Deprecation logging callback.
callable	$errorLogger
	Error logging callback.
int	$flags
	Current bit field of class DBO_* constants.
string[]	$indexAliases = []
	Current map of (index alias => index)
array	$lbInfo = []
	Current LoadBalancer tracking information.
int	$nonNativeInsertSelectBatchSize
	Row batch size to use for emulated INSERT SELECT queries.
string null	$password
	Password used to establish the current connection.
callable null	$profiler
LoggerInterface	$queryLogger
LoggerInterface	$replLogger
array null	$schemaVars
	Current variables use for schema element placeholders.
string null	$server
	Server that this instance is currently connected to.
string null	$serverName
	Readible name or host/IP of the database server.
array	$sessionDirtyTempTables = []
	Map of (table name => 1) for current TEMPORARY tables.
array< string, float >	$sessionNamedLocks = []
	Map of (name => UNIX timestamp) for locks obtained via lock()
array	$sessionTempTables = []
	Map of (table name => 1) for current TEMPORARY tables.
BagOStuff	$srvCache
	APC cache.
array[]	$tableAliases = []
	Current map of (table => (dbname, schema, prefix) map)
string	$topologyRole
	Replication topology role of the server; one of the class ROLE_* constants.
string null	$topologyRootMaster
	Host (or address) of the root primary server for the replication topology.
TransactionProfiler	$trxProfiler
string null	$user
	User that this instance is currently connected under the name of.
const	CONN_HOST = 'host'
	Hostname or IP address to use on all connections.
const	CONN_INITIAL_DB = 'dbname'
	Database name to use on initial connection.
const	CONN_INITIAL_SCHEMA = 'schema'
	Schema name to use on initial connection.
const	CONN_INITIAL_TABLE_PREFIX = 'tablePrefix'
	Table prefix to use on initial connection.
const	CONN_PASSWORD = 'password'
	Database server password to use on all connections.
const	CONN_USER = 'user'
	Database server username to use on all connections.

Static Protected Attributes
static int	$DBO_MUTABLE
	Bit field of all DBO_* flags that can be changed after connection.
static string[]	$MUTABLE_FLAGS
	List of DBO_* flags that can be changed after connection.

Private Member Functions
	assertQueryIsCurrentlyAllowed ( $sql, $fname)
	Error out if the DB is not in a valid state for a query via query()
	beginIfImplied ( $sql, $fname)
	Start an implicit transaction if DBO_TRX is enabled and no transaction is active.
	canRecoverFromDisconnect ( $sql, $priorWritesPending)
	Determine whether it is safe to retry queries after a database connection is lost.
	consumeTrxShortId ()
	Reset the transaction ID and return the old one.
	currentAtomicSectionId ()
	executeQueryAttempt ( $sql, $commentedSql, $isPermWrite, $fname, $flags)
	Wrapper for doQuery() that handles DBO_TRX, profiling, logging, affected row count tracking, and reconnects (without retry) on query failure due to connection loss.
	flatAtomicSectionList ()
	getQueryException ( $error, $errno, $sql, $fname)
	getQueryExceptionAndLog ( $error, $errno, $sql, $fname)
	handleSessionLossPostconnect ()
	Clean things up after session (and thus transaction) loss after reconnect.
	handleSessionLossPreconnect ()
	Clean things up after session (and thus transaction) loss before reconnect.
	makeKeyCollisionCondition (array $rows, array $uniqueKey)
	Build an SQL condition to find rows with matching key values to those in $rows.
	modifyCallbacksForCancel (array $sectionIds, AtomicSectionIdentifier $newSectionId=null)
	Update callbacks that were owned by cancelled atomic sections.
	nextSavepointId ( $fname)
	normalizeUpsertKeys ( $uniqueKeys)
	pingAndCalculateLastTrxApplyTime ()
	prependDatabaseOrSchema ( $namespace, $relation, $format)
	reassignCallbacksForSection (AtomicSectionIdentifier $old, AtomicSectionIdentifier $new)
	Hoist callback ownership for callbacks in a section to a parent section.
	runOnAtomicSectionCancelCallbacks ( $trigger, array $sectionIds)
	Consume and run any relevant "on atomic section cancel" callbacks for the active transaction.
	runTransactionPostCommitCallbacks ()
	Handle "on transaction idle/resolution" and "transaction listener" callbacks post-COMMIT.
	runTransactionPostRollbackCallbacks ()
	Handle "on transaction idle/resolution" and "transaction listener" callbacks post-ROLLBACK.
	selectFieldsOrOptionsAggregate ( $fields, $options)
	selectOptionsIncludeLocking ( $options)
	setTransactionError (Throwable $trxError)
	Mark the transaction as requiring rollback (STATUS_TRX_ERROR) due to an error.
	updateTrxWriteQueryTime ( $sql, $runtime, $affected)
	Update the estimated run-time of a query, not counting large row lock times.

Static Private Member Functions
static	getClass ( $dbType, $driver=null)

Private Attributes
DBUnexpectedError null	$csmError
	Last unresolved critical section error.
string null	$csmFname
	Last critical section caller name.
int null	$csmId
	Current critical section numeric ID.
string bool null	$htmlErrors
	Stashed value of html_errors INI setting.
string bool	$lastPhpError = false
float	$lastPing = 0.0
	UNIX timestamp.
string	$lastQuery = ''
	The last SQL query attempted.
float	$lastRoundTripEstimate = 0.0
	Query round trip time estimate.
float bool	$lastWriteTime = false
	UNIX timestamp of last write query.
IDatabase null	$lazyMasterHandle
	Lazy handle to the primary DB this server replicates from.
int null	$ownerId
	Integer ID of the managing LBFactory instance or null if none.
int[]	$priorFlags = []
	Prior flags member variable values.
int	$trxAtomicCounter = 0
	Counter for atomic savepoint identifiers (reset with each transaction)
array	$trxAtomicLevels = []
	List of (name, unique ID, savepoint ID) for each active atomic section level.
bool	$trxAutomatic = false
	Whether the current transaction was started implicitly due to DBO_TRX.
bool	$trxAutomaticAtomic = false
	Whether the current transaction was started implicitly by startAtomic()
bool	$trxDoneWrites = false
	Whether possible write queries were done in the last transaction started.
array[]	$trxEndCallbacks = []
	List of (callable, method name, atomic section id)
bool	$trxEndCallbacksSuppressed = false
	Whether to suppress triggering of transaction end callbacks.
string null	$trxFname = null
	Name of the function that start the last transaction.
array[]	$trxPostCommitOrIdleCallbacks = []
	List of (callable, method name, atomic section id)
array[]	$trxPreCommitOrIdleCallbacks = []
	List of (callable, method name, atomic section id)
callable[]	$trxRecurringCallbacks = []
	Map of (name => callable)
array null	$trxReplicaLagStatus = null
	Replication lag estimate at the time of BEGIN for the last transaction.
array[]	$trxSectionCancelCallbacks = []
	List of (callable, method name, atomic section id)
string	$trxShortId = ''
	ID of the active transaction or the empty string otherwise.
int	$trxStatus = self::STATUS_TRX_NONE
	Transaction status.
Throwable null	$trxStatusCause
	The last error that caused the status to become STATUS_TRX_ERROR.
array null	$trxStatusIgnoredCause
	Error details of the last statement-only rollback.
float null	$trxTimestamp = null
	UNIX timestamp at the time of BEGIN for the last transaction.
float	$trxWriteAdjDuration = 0.0
	Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries.
int	$trxWriteAdjQueryCount = 0
	Number of write queries counted in trxWriteAdjDuration.
int	$trxWriteAffectedRows = 0
	Number of rows affected by write queries for the current transaction.
string[]	$trxWriteCallers = []
	Write query callers of the current transaction.
float	$trxWriteDuration = 0.0
	Seconds spent in write queries for the current transaction.
int	$trxWriteQueryCount = 0
	Number of write queries for the current transaction.

Static Private Attributes
static int	$DEADLOCK_DELAY_MAX = 1500000
	Maximum time to wait before retry.
static int	$DEADLOCK_DELAY_MIN = 500000
	Minimum time to wait before retry, in microseconds.
static int	$DEADLOCK_TRIES = 4
	Number of times to re-try an operation in case of deadlock.
static string	$NOT_APPLICABLE = 'n/a'
	Idiom used when a cancelable atomic section started the transaction.
static string	$PING_QUERY = 'SELECT 1 AS ping'
	Dummy SQL query.
static float	$PING_TTL = 1.0
	How long before it is worth doing a dummy query to test the connection.
static string	$SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic'
	Prefix to the atomic section counter used to make savepoint IDs.
static float	$SLOW_WRITE_SEC = 0.500
	Consider a write slow if it took more than this many seconds.
static int	$SMALL_WRITE_ROWS = 100
	Assume an insert of this many rows or less should be fast to replicate.
static int	$TEMP_NORMAL = 1
	Writes to this temporary table do not affect lastDoneWrites()
static int	$TEMP_PSEUDO_PERMANENT = 2
	Writes to this temporary table effect lastDoneWrites()
static float	$TINY_WRITE_SEC = 0.010
	Guess of how many seconds it takes to replicate a small insert.

Additional Inherited Members
Public Attributes inherited from Wikimedia\Rdbms\IDatabase
const	LOCK_TIMESTAMP = 1
	Flag to return the lock acquision timestamp (null if not acquired)

Detailed Description

Relational database abstraction object.

Stability: stable

to extend

Since

1.28

Definition at line 52 of file Database.php.

Constructor & Destructor Documentation

__construct()

Wikimedia\Rdbms\Database::__construct

(

array

$params

)

Note

exceptions for missing libraries/drivers should be thrown in initConnection()

Stability: stable

to call

Parameters

array

$params

Parameters passed from Database::factory()

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 284 of file Database.php.

__destruct()

Wikimedia\Rdbms\Database::__destruct

(

)

Run a few simple sanity checks and close dangling connections.

Definition at line 6048 of file Database.php.

Member Function Documentation

__clone()

Wikimedia\Rdbms\Database::__clone

(

)

Make sure that copies do not share the same client binding handle.

Exceptions

DBConnectionError

Definition at line 6010 of file Database.php.

__sleep()

Wikimedia\Rdbms\Database::__sleep

(

)

Called by serialize.

Throw an exception when DB connection is serialized. This causes problems on some database engines because the connection is not restored on unserialize.

Returns

never

Definition at line 6040 of file Database.php.

__toString()

Wikimedia\Rdbms\Database::__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

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5985 of file Database.php.

addIdentifierQuotes()

Wikimedia\Rdbms\Database::addIdentifierQuotes

(

$s

)

Escape a SQL identifier (e.g.table, column, database) for use in a SQL queryDepending on the database this will either be backticks or "double quotes"

Parameters

string

$s

Returns

string

Since

1.33

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3348 of file Database.php.

References $s.

Referenced by Wikimedia\Rdbms\DatabasePostgres\determineCoreSchema(), Wikimedia\Rdbms\DatabaseSqlite\doTruncate(), Wikimedia\Rdbms\DatabasePostgres\duplicateTableStructure(), Wikimedia\Rdbms\DatabaseSqlite\duplicateTableStructure(), Wikimedia\Rdbms\DatabasePostgres\open(), and Wikimedia\Rdbms\DatabasePostgres\selectSQLText().

addQuotes()

Wikimedia\Rdbms\Database::addQuotes

(

$s

)

Escape and quote a raw value string for use in a SQL query.

Parameters

string | int | float | null | bool | Blob

$s

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3329 of file Database.php.

References $s.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\doLock(), Wikimedia\Rdbms\DatabaseMysqlBase\doLockIsFree(), Wikimedia\Rdbms\DatabaseMysqlBase\doUnlock(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabaseMysqlBase\primaryPosWait().

affectedRows()

Wikimedia\Rdbms\Database::affectedRows

(

)

Get the number of rows affected by the last write query.

Similar to https://www.php.net/mysql_affected_rows but includes rows matched but not changed (ie. an UPDATE which sets all fields to the same value they already have). To get the old mysql_affected_rows behavior, include non-equality of the fields in WHERE.

Returns

int

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5103 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt(), and Wikimedia\Rdbms\Database\updateTrxWriteQueryTime().

aggregateValue()

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

Return aggregated value alias.

Parameters

array	$valuedata
string	$valuename

Returns

array|string

Deprecated:

Since 1.33

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 2759 of file Database.php.

anyChar()

Wikimedia\Rdbms\Database::anyChar

(

)

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

Returns

LikeMatch

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3411 of file Database.php.

anyString()

Wikimedia\Rdbms\Database::anyString

(

)

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

Returns

LikeMatch

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3415 of file Database.php.

assertBuildSubstringParams()

Wikimedia\Rdbms\Database::assertBuildSubstringParams (   $startPosition,   $length  )

protected

Check type and bounds for parameters to self::buildSubstring()

All supported databases have substring functions that behave the same for positive $startPosition and non-negative $length, but behaviors differ when given negative $startPosition or negative $length. The simplest solution to that is to just forbid those values.

Parameters

int	$startPosition
int | null	$length

Since

1.31

Definition at line 2891 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseSqlite\buildSubstring().

assertConditionIsNotEmpty()

Wikimedia\Rdbms\Database::assertConditionIsNotEmpty (   $conds, string  $fname, bool  $deprecate  )

protected

Check type and bounds conditions parameters for update.

In order to prevent possible performance or replication issues, empty condition for 'update' and 'delete' queries isn't allowed

Parameters

array | string	$conds	conditions to be validated on emptiness
string	$fname	caller's function name to be passed to exception
bool	$deprecate	define the assertion type. If true then wfDeprecated will be called, otherwise DBUnexpectedError will be raised.

Since

1.35

Definition at line 2921 of file Database.php.

References wfDeprecated().

assertHasConnectionHandle()

Wikimedia\Rdbms\Database::assertHasConnectionHandle ( )

finalprotected

Make sure there is an open connection handle (alive or not) as a sanity check.

This guards against fatal errors to the binding handle not being defined in cases where open() was never called or close() was already called.

Exceptions

DBUnexpectedError

Definition at line 1069 of file Database.php.

References Wikimedia\Rdbms\Database\isOpen().

Referenced by Wikimedia\Rdbms\Database\executeQuery(), and Wikimedia\Rdbms\DatabaseSqlite\serverIsReadOnly().

assertIsWritableMaster()

Wikimedia\Rdbms\Database::assertIsWritableMaster ( )

protected

Deprecated:

since 1.37; please use assertIsWritablePrimary() instead.

Exceptions

DBReadOnlyError

Definition at line 1097 of file Database.php.

References Wikimedia\Rdbms\Database\assertIsWritablePrimary(), and wfDeprecated().

assertIsWritablePrimary()

Wikimedia\Rdbms\Database::assertIsWritablePrimary ( )

protected

Make sure that this server is not marked as a replica nor read-only as a sanity check.

Exceptions

DBReadOnlyError

Since

1.37

Definition at line 1081 of file Database.php.

References $source, and Wikimedia\Rdbms\Database\getReadOnlyReason().

Referenced by Wikimedia\Rdbms\Database\assertIsWritableMaster(), and Wikimedia\Rdbms\Database\executeQuery().

assertNoOpenTransactions()

Wikimedia\Rdbms\Database::assertNoOpenTransactions

(

)

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

Exceptions

DBTransactionError

Since

1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 1635 of file Database.php.

References Wikimedia\Rdbms\Database\explicitTrxActive(), and Wikimedia\Rdbms\Database\flatAtomicSectionList().

assertQueryIsCurrentlyAllowed()

Wikimedia\Rdbms\Database::assertQueryIsCurrentlyAllowed (   $sql,   $fname  )

private

Error out if the DB is not in a valid state for a query via query()

Parameters

string	$sql
string	$fname

Exceptions

DBUnexpectedError
DBTransactionStateError

Definition at line 1599 of file Database.php.

References Wikimedia\Rdbms\Database\$trxStatusIgnoredCause, Wikimedia\Rdbms\Database\getQueryVerb(), and Wikimedia\Rdbms\Database\trxStatus().

Referenced by Wikimedia\Rdbms\Database\query().

assertValidUpsertRowArray()

Wikimedia\Rdbms\Database::assertValidUpsertRowArray ( array  $rows, array  $identityKey  )

finalprotected

Parameters

	array<int,array>	$rows Normalized list of rows to insert
string[]	$identityKey	Columns of the (unique) identity key to UPSERT upon

Returns

bool Whether all the rows have NULL/absent values for all identity key columns

Since

1.37

Definition at line 2357 of file Database.php.

assertValidUpsertSetArray()

Wikimedia\Rdbms\Database::assertValidUpsertSetArray ( array  $set, array  $identityKey, array  $rows  )

finalprotected

Parameters

array	$set	Combined column/literal assignment map and SQL assignment list
string[]	$identityKey	Columns of the (unique) identity key to UPSERT upon
	array<int,array>	$rows List of rows to upsert

Since

1.37

Definition at line 2384 of file Database.php.

attributesFromType()

static Wikimedia\Rdbms\Database::attributesFromType (   $dbType,   $driver = null  )

staticfinal

Parameters

string	$dbType	A possible DB type (sqlite, mysql, postgres,...)
string | null	$driver	Optional name of a specific DB client driver

Returns

array Map of (Database::ATTR_* constant => value) for all such constants

Exceptions

InvalidArgumentException

Since

1.31

Definition at line 492 of file Database.php.

References Wikimedia\Rdbms\Database\getClass().

begin()

Wikimedia\Rdbms\Database::begin (   $fname = __METHOD__,   $mode = self::TRANSACTION_EXPLICIT  )

final

Begin a transaction.

Only call this from code with outer transaction scope. See https://www.mediawiki.org/wiki/Database_transactions for details. Nesting of transactions is not supported.

Note that when the DBO_TRX flag is set (which is usually the case for web requests, but not for maintenance scripts), any previous database query will have started a transaction automatically.

Nesting of transactions is not supported. Attempts to nest transactions will cause a warning, unless the current transaction was started automatically because of the DBO_TRX flag.

Parameters

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

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4796 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\beginIfImplied().

beginIfImplied()

Wikimedia\Rdbms\Database::beginIfImplied (   $sql,   $fname  )

private

Start an implicit transaction if DBO_TRX is enabled and no transaction is active.

Parameters

string	$sql
string	$fname

Definition at line 1546 of file Database.php.

References Wikimedia\Rdbms\Database\begin(), Wikimedia\Rdbms\Database\getFlag(), Wikimedia\Rdbms\Database\isTransactableQuery(), and Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

bitAnd()

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

Parameters

string | int	$fieldLeft
string | int	$fieldRight

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2775 of file Database.php.

bitNot()

Wikimedia\Rdbms\Database::bitNot

(

$field

)

Parameters

string | int

$field

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2767 of file Database.php.

bitOr()

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

Parameters

string | int	$fieldLeft
string | int	$fieldRight

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2783 of file Database.php.

buildConcat()

Wikimedia\Rdbms\Database::buildConcat

(

$stringList

)

Build a concatenation list to feed into a SQL query.

Parameters

string[]

$stringList

Raw SQL expression list; caller is responsible for escaping

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2791 of file Database.php.

buildGreatest()

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

Build a GREATEST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Parameters

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

Returns

mixed

Since

1.35

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2811 of file Database.php.

buildGroupConcatField()

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

Build a GROUP_CONCAT or equivalent statement for a query.This is useful for combining a field for several rows into a single string. NULL values will not appear in the output, duplicated values will appear, and the resulting delimiter-separated values have no defined sort order. Code using the results may need to use the PHP unique() or sort() methods.

Parameters

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

Returns

string SQL text

Since

1.23

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2799 of file Database.php.

buildIntegerCast()

Wikimedia\Rdbms\Database::buildIntegerCast

(

$field

)

Parameters

string

$field

Field or column to cast

Returns

string

Since

1.31

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 2946 of file Database.php.

buildLeast()

Wikimedia\Rdbms\Database::buildLeast	(		$fields,
			$values
	)

Build a LEAST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Parameters

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

Returns

mixed

Since

1.35

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2819 of file Database.php.

buildLike()

Wikimedia\Rdbms\Database::buildLike	(		$param,
			$params
	)

LIKE statement wrapper.This takes a variable-length argument list with parts of pattern to match containing either string literals that will be escaped or tokens returned by anyChar() or anyString(). Alternatively, the function could be provided with an array of aforementioned parameters.Example: $dbr->buildLike( 'My_page_title/', $dbr->anyString() ) returns a LIKE clause that searches for subpages of 'My page title'. Alternatively: $pattern = [ 'My_page_title/', $dbr->anyString() ]; $query .= $dbr->buildLike( $pattern );

Since

1.16

Parameters

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

Returns

string Fully built LIKE statement

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3384 of file Database.php.

References $s.

buildSelectSubquery()

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

Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery.

See also

IDatabase::selectSQLText()

Parameters

string | array	$table	Table name
string | array	$vars	Field names
string | array	$conds	Conditions
string	$fname	Caller function name
string | array	$options	Query options
string | array	$join_conds	Join conditions

Returns

Subquery

Since

1.31

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2950 of file Database.php.

buildStringCast()

Wikimedia\Rdbms\Database::buildStringCast

(

$field

)

Parameters

string

$field

Field or column to cast

Returns

string

Since

1.28

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2936 of file Database.php.

buildSubstring()

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

Stability: stable

to override

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2870 of file Database.php.

buildSuperlative()

Wikimedia\Rdbms\Database::buildSuperlative (   $sqlfunc,   $fields,   $values  )

protected

Build a superlative function statement comparing columns/values.

Integer and float values in $values will not be quoted

If $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Stability: stable

to override

Parameters

string	$sqlfunc	Name of a SQL function
string | string[]	$fields	Name(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]	$values	Values to compare

Returns

string

Since

1.35

Definition at line 2839 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseSqlite\buildGreatest(), and Wikimedia\Rdbms\DatabaseSqlite\buildLeast().

cancelAtomic()

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

final

Cancel an atomic section of SQL statements.

This will roll back only the statements executed since the start of the most recent atomic section, and close that section. If a transaction was open before the corresponding startAtomic() call, any statements before that call are not rolled back and the transaction remains open. If the corresponding startAtomic() implicitly started a transaction, that transaction is rolled back.

Note

callers must use additional measures for situations involving two or more (peer) transactions (e.g. updating two database servers at once). The transaction and savepoint logic of startAtomic() are bound to specific IDatabase instances.

Note that a call to IDatabase::rollback() will also roll back any open atomic sections.

Note

As a micro-optimization to save a few DB calls, this method may only be called when startAtomic() was called with the ATOMIC_CANCELABLE flag.

Since

1.31

See also

IDatabase::startAtomic

Parameters

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

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4671 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting().

canRecoverFromDisconnect()

Wikimedia\Rdbms\Database::canRecoverFromDisconnect (   $sql,   $priorWritesPending  )

private

Determine whether it is safe to retry queries after a database connection is lost.

Parameters

string	$sql	SQL query
bool	$priorWritesPending	Whether there is a transaction open with possible write queries or transaction pre-commit/idle callbacks waiting on it to finish.

Returns

bool True if it is safe to retry the query, false otherwise

Definition at line 1654 of file Database.php.

References Wikimedia\Rdbms\Database\explicitTrxActive().

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

clearFlag()

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

Clear a flag for this connection.

Parameters

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

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 836 of file Database.php.

References Wikimedia\Rdbms\Database\$flags.

close()

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

final

Close the database connection.

This should only be called after any transactions have been resolved, aside from read-only automatic transactions (assuming no callbacks are registered). If a transaction is still open anyway, it will be rolled back.

Parameters

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

Returns

bool Success

Exceptions

DBError

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 990 of file Database.php.

References Wikimedia\Rdbms\Database\closeConnection(), Wikimedia\Rdbms\Database\flatAtomicSectionList(), Wikimedia\Rdbms\Database\pendingWriteAndCallbackCallers(), Wikimedia\Rdbms\Database\rollback(), Wikimedia\Rdbms\Database\runTransactionPostRollbackCallbacks(), Wikimedia\Rdbms\Database\trxLevel(), and Wikimedia\Rdbms\Database\writesOrCallbacksPending().

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\open(), Wikimedia\Rdbms\DatabasePostgres\open(), and Wikimedia\Rdbms\DatabaseSqlite\open().

closeConnection()

Wikimedia\Rdbms\Database::closeConnection ( )

abstractprotected

Closes underlying database connection.

Returns

bool Whether connection was closed successfully

Since

1.20

Reimplemented in Wikimedia\Rdbms\DatabaseMysqli, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Referenced by Wikimedia\Rdbms\Database\close().

commenceCriticalSection()

Wikimedia\Rdbms\Database::commenceCriticalSection ( string  $fname )

protected

Demark the start of a critical section of session/transaction state changes.

Use this to disable potentially DB handles due to corruption from highly unexpected exceptions (e.g. from zend timers or coding errors) preempting execution of methods.

Callers must demark completion of the critical section with completeCriticalSection(). Callers should handle DBError exceptions that do not cause object state corruption by catching them, calling completeCriticalSection(), and then rethrowing them.

$cs = $this->commenceCriticalSection( __METHOD__ );
try {
    //...send a query that changes the session/transaction state...
} catch ( DBError $e ) {
    // Rely on assertQueryIsCurrentlyAllowed()/canRecoverFromDisconnect() to ensure
    // the rollback of incomplete transactions and the prohibition of reconnections
    // that mask a loss of session state (e.g. named locks and temp tables)
    $this->completeCriticalSection( __METHOD__, $cs );
    throw $expectedException;
}
try {
    //...send another query that changes the session/transaction state...
} catch ( DBError $trxError ) {
    // Inform assertQueryIsCurrentlyAllowed() that the transaction must be rolled
    // back (e.g. even if the error was a pre-query check or normally recoverable)
    $this->completeCriticalSection( __METHOD__, $cs, $trxError );
    throw $expectedException;
}
// ...update session state fields of $this...
$this->completeCriticalSection( __METHOD__, $cs );

See also

Database::completeCriticalSection()

Since

1.36

Parameters

string

$fname

Caller name

Returns

CriticalSectionScope|null RAII-style monitor (topmost sections only)

Exceptions

DBUnexpectedError

If an unresolved critical section error already exists

Definition at line 5919 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery().

commit()

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

final

Commits a transaction previously started using begin()

If no transaction is in progress, a warning is issued.

Only call this from code with outer transaction scope. See https://www.mediawiki.org/wiki/Database_transactions for details. Nesting of transactions is not supported.

Parameters

string	$fname
string	$flush	Flush flag, set to situationally valid IDatabase::FLUSHING_* constant to disable warnings about explicitly committing implicit transactions, or calling commit when no transaction is in progress. This will trigger an exception if there is an ongoing explicit transaction. Only set the flush flag if you are sure that these warnings are not applicable, and no explicit transactions are open.

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4870 of file Database.php.

completeCriticalSection()

Wikimedia\Rdbms\Database::completeCriticalSection ( string  $fname, ?CriticalSectionScope  $csm, Throwable  $trxError = null  )

protected

Demark the completion of a critical section of session/transaction state changes.

See also

Database::commenceCriticalSection()

Since

1.36

Parameters

string	$fname	Caller name
CriticalSectionScope | null	$csm	RAII-style monitor (topmost sections only)
Throwable | null	$trxError	Error that requires setting STATUS_TRX_ERROR (if any)

Definition at line 5962 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery().

conditional()

Wikimedia\Rdbms\Database::conditional	(		$cond,
			$caseTrueExpression,
			$caseFalseExpression
	)

Returns an SQL expression for a simple conditional.This doesn't need to be overridden unless CASE isn't supported in the RDBMS.

Parameters

string | array	$cond	SQL condition expression (yields a boolean)
string	$caseTrueExpression	SQL expression to return when the condition is true
string	$caseFalseExpression	SQL expression to return when the condition is false

Returns

string SQL fragment

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3939 of file Database.php.

connectionErrorLogger()

Wikimedia\Rdbms\Database::connectionErrorLogger	(		$errno,
			$errstr
	)

Error handler for logging errors during database connection.

Access: internal

This method should not be used outside of Database classes

Parameters

int	$errno
string	$errstr

Definition at line 969 of file Database.php.

consumeTrxShortId()

Wikimedia\Rdbms\Database::consumeTrxShortId ( )

private

Reset the transaction ID and return the old one.

Returns

string The old transaction ID or the empty string if there wasn't one

Definition at line 1731 of file Database.php.

References Wikimedia\Rdbms\Database\$trxShortId.

Referenced by Wikimedia\Rdbms\Database\handleSessionLossPreconnect().

currentAtomicSectionId()

Wikimedia\Rdbms\Database::currentAtomicSectionId ( )

private

Returns

AtomicSectionIdentifier|null ID of the topmost atomic section level

Definition at line 4187 of file Database.php.

databasesAreIndependent()

Wikimedia\Rdbms\Database::databasesAreIndependent

(

)

Returns true if DBs are assumed to be on potentially different servers.In systems like mysql/mariadb, different databases can easily be referenced on a single connection merely by name, even in a single query via JOIN. On the other hand, Postgres treats databases as logically separate, with different database users, requiring special mechanisms like postgres_fdw to "mount" foreign DBs. This is true even among DBs on the same server. Changing the selected database via selectDomain() requires a new connection.

Returns

bool

Since

1.29

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2963 of file Database.php.

dataSeek()

Wikimedia\Rdbms\Database::dataSeek	(	IResultWrapper	$res,
			$row
	)

Change the position of the cursor in a result object.

See also

https://www.php.net/mysql_data_seek

Deprecated:

since 1.37 use IResultWrapper::seek()

Parameters

IResultWrapper	$res	A SQL result
int	$row

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 896 of file Database.php.

References $res.

dbSchema()

Wikimedia\Rdbms\Database::dbSchema

(

$schema = null

)

Get/set the db schema.

Parameters

string | null

$schema

The database schema to set, or omitted to leave it unchanged

Returns

string The previous db schema

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 629 of file Database.php.

References Wikimedia\Rdbms\Database\getDBname().

Referenced by Wikimedia\Rdbms\Database\relationSchemaQualifier().

deadlockLoop()

Wikimedia\Rdbms\Database::deadlockLoop

(

$args

)

Perform a deadlock-prone transaction.This function invokes a callback function to perform a set of write queries. If a deadlock occurs during the processing, the transaction will be rolled back and the callback function will be called again.Avoid using this method outside of Job or Maintenance classes.Usage: $dbw->deadlockLoop( callback, ... );Extra arguments are passed through to the specified callback function. This method requires that no transactions are already active to avoid causing premature commits or exceptions.Returns whatever the callback function returned on its successful, iteration, or false on error, for example if the retry limit was reached.

Parameters

mixed

...$args

Returns

mixed

Exceptions

DBUnexpectedError
Exception

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 4029 of file Database.php.

References $args.

decodeBlob()

Wikimedia\Rdbms\Database::decodeBlob

(

$b

)

Some DBMSs return a special placeholder object representing blob fields in result objects.Pass the object through this function to return the original string.

Parameters

string | Blob

$b

Returns

string

Exceptions

DBError

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5305 of file Database.php.

decodeExpiry()

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

Decode an expiry time into a DBMS independent format.

Parameters

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

Returns

string

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5780 of file Database.php.

delete()

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

Delete all rows in a table that match a condition.

Parameters

string	$table	Table name
string | array	$conds	Array of conditions. See $conds in IDatabase::select() In order to prevent possible performance or replication issues or damaging a data accidentally, an empty condition for 'delete' queries isn't allowed. IDatabase::ALL_ROWS should be passed explicitely in order to delete all rows.
string	$fname	Name of the calling function

Returns

bool Return true if no exception was thrown (deprecated since 1.33)

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3642 of file Database.php.

deleteJoin()

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

DELETE where the condition is a join.MySQL overrides this to use a multi-table DELETE syntax, in other databases we use sub-selectsFor safety, an empty $conds will not delete everything. If you want to delete all rows where the join condition matches, set $conds=IDatabase::ALL_ROWS.DO NOT put the join condition in $conds.

Parameters

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

Exceptions

DBError

If an error occurs, {

See also

query}

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3598 of file Database.php.

doAtomicSection()

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

final

Perform an atomic section of reversable SQL statements from a callback.

The $callback takes the following arguments:

• This database object
• The value of $fname

This will execute the callback inside a pair of startAtomic()/endAtomic() calls. If any exception occurs during execution of the callback, it will be handled as follows:

• If $cancelable is ATOMIC_CANCELABLE, cancelAtomic() will be called to back out any (and only) statements executed during the atomic section. If that succeeds, then the exception will be re-thrown; if it fails, then a different exception will be thrown and any further query attempts will fail until rollback() is called.
• If $cancelable is ATOMIC_NOT_CANCELABLE, cancelAtomic() will be called to mark the end of the section and the error will be re-thrown. Any further query attempts will fail until rollback() is called.

This method is convenient for letting calls to the caller of this method be wrapped in a try/catch blocks for exception types that imply that the caller failed but was able to properly discard the changes it made in the transaction. This method can be an alternative to explicit calls to startAtomic()/endAtomic()/cancelAtomic().

Example usage, "RecordStore::save" method:

$dbw->doAtomicSection( __METHOD__, function ( $dbw ) use ( $record ) {
    // Create new record metadata row
    $dbw->insert( 'records', $record->toArray(), __METHOD__ );
    // Figure out where to store the data based on the new row's ID
    $path = $this->recordDirectory . '/' . $dbw->insertId();
    // Write the record data to the storage system;
    // blob store throughs StoreFailureException on failure
    $this->blobStore->create( $path, $record->getJSON() );
    // Try to cleanup files orphaned by transaction rollback
    $dbw->onTransactionResolution(
        function ( $type ) use ( $path ) {
            if ( $type === IDatabase::TRIGGER_ROLLBACK ) {
                $this->blobStore->delete( $path );
            }
        },
        __METHOD__
     );
}, $dbw::ATOMIC_CANCELABLE );

Example usage, caller of the "RecordStore::save" method:

$dbw->startAtomic( __METHOD__ );
// ...various SQL writes happen...
try {
    $recordStore->save( $record );
} catch ( StoreFailureException $e ) {
    // ...various SQL writes happen...
}
// ...various SQL writes happen...
$dbw->endAtomic( __METHOD__ );

See also

Database::startAtomic

Database::endAtomic

Database::cancelAtomic

Parameters

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.

Returns

mixed Result of the callback (since 1.28)

Exceptions

DBError

If an error occurs, {

See also

query}

Exceptions

Exception

If an error occurs in the callback

Since

1.27; prior to 1.31 this did a rollback() instead of cancelAtomic(), and assumed no callers up the stack would ever try to catch the exception.

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4775 of file Database.php.

References $res.

doBegin()

Wikimedia\Rdbms\Database::doBegin (   $fname )

protected

Issues the BEGIN command to the database server.

See also

Database::begin()

Stability: stable

to override

Parameters

string

$fname

Exceptions

DBError

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 4866 of file Database.php.

doCommit()

Wikimedia\Rdbms\Database::doCommit (   $fname )

protected

Issues the COMMIT command to the database server.

Stability: stable

to override

See also

Database::commit()

Parameters

string

$fname

Exceptions

DBError

Definition at line 4949 of file Database.php.

doDropTable()

Wikimedia\Rdbms\Database::doDropTable (   $table,   $fname  )

protected

See also

Database::dropTable()

Stability: stable

to override

Parameters

string	$table
string	$fname

Definition at line 5728 of file Database.php.

doGetLag()

Wikimedia\Rdbms\Database::doGetLag ( )

protected

Get the amount of replication lag for this database server.

Callers should avoid using this method while a transaction is active

See also

getLag()

Stability: stable

to override

Returns

float|int|false Database replication lag in seconds or false on error

Exceptions

DBError

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5281 of file Database.php.

doHandleSessionLossPreconnect()

Wikimedia\Rdbms\Database::doHandleSessionLossPreconnect ( )

protected

Reset any additional subclass trx* and session* fields.

Stability: stable

to override

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 1711 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\handleSessionLossPreconnect().

doInitConnection()

Wikimedia\Rdbms\Database::doInitConnection ( )

protected

Actually connect to the database over the wire (or to local files)

Exceptions

DBConnectionError

Since

1.31

Definition at line 357 of file Database.php.

References Wikimedia\Rdbms\Database\open().

Referenced by Wikimedia\Rdbms\Database\initConnection().

doInsert()

Wikimedia\Rdbms\Database::doInsert (   $table, array  $rows,   $fname  )

protected

See also

Database::insert()

Stability: stable

to override

Parameters

string	$table
array	$rows	Non-empty list of rows
string	$fname

Since

1.35

Definition at line 2534 of file Database.php.

doInsertNonConflicting()

Wikimedia\Rdbms\Database::doInsertNonConflicting (   $table, array  $rows,   $fname  )

protected

See also

Database::insert()

Stability: stable

to override

Parameters

string	$table
array	$rows	Non-empty list of rows
string	$fname

Since

1.35

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 2551 of file Database.php.

doInsertSelectGeneric()

Wikimedia\Rdbms\Database::doInsertSelectGeneric (   $destTable,   $srcTable, array  $varMap,   $conds,   $fname, array  $insertOptions, array  $selectOptions,   $selectJoinConds  )

protected

Implementation of insertSelect() based on select() and insert()

See also

IDatabase::insertSelect()

Parameters

string	$destTable
string | array	$srcTable
array	$varMap
array	$conds
string	$fname
array	$insertOptions
array	$selectOptions
array	$selectJoinConds

Since

1.35

Definition at line 3729 of file Database.php.

References $res.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertSelectNative().

doInsertSelectNative()

Wikimedia\Rdbms\Database::doInsertSelectNative (   $destTable,   $srcTable, array  $varMap,   $conds,   $fname, array  $insertOptions, array  $selectOptions,   $selectJoinConds  )

protected

Native server-side implementation of insertSelect() for situations where we don't want to select everything into memory.

See also

IDatabase::insertSelect()

Parameters

string	$destTable
string | array	$srcTable
array	$varMap
array	$conds
string	$fname
array	$insertOptions
array	$selectOptions
array	$selectJoinConds

Since

1.35

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 3794 of file Database.php.

doLock()

Wikimedia\Rdbms\Database::doLock ( string  $lockName, string  $method, int  $timeout  )

protected

See also

lock()

Parameters

string	$lockName
string	$method
int	$timeout

Returns

float|null UNIX timestamp of lock acquisition; null on failure

Exceptions

DBError

Stability: stable

to override

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5587 of file Database.php.

doLockIsFree()

Wikimedia\Rdbms\Database::doLockIsFree ( string  $lockName, string  $method  )

protected

See also

lockIsFree()

Parameters

string	$lockName
string	$method

Returns

bool Success

Exceptions

DBError

Stability: stable

to override

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5552 of file Database.php.

doLockTables()

Wikimedia\Rdbms\Database::doLockTables ( array  $read, array  $write,   $method  )

protected

Helper function for lockTables() that handles the actual table locking.

Stability: stable

to override

Parameters

array	$read	Array of tables to lock for read access
array	$write	Array of tables to lock for write access
string	$method	Name of caller

Returns

true

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabasePostgres.

Definition at line 5687 of file Database.php.

doQuery()

Wikimedia\Rdbms\Database::doQuery (   $sql )

abstractprotected

Run a query and return a DBMS-dependent wrapper or boolean.

This is meant to handle the basic command of actually sending a query to the server via the driver. No implicit transaction, reconnection, nor retry logic should happen here. The higher level query() method is designed to handle those sorts of concerns. This method should not trigger such higher level methods.

The lastError() and lastErrno() methods should meaningfully reflect what error, if any, occurred during the last call to this method. Methods like executeQuery(), query(), select(), insert(), update(), delete(), and upsert() implement their calls to doQuery() such that an immediately subsequent call to lastError()/lastErrno() meaningfully reflects any error that occurred during that public query method call.

For SELECT queries, this returns either:

• a) An IResultWrapper describing the query results
• b) False, on any query failure

For non-SELECT queries, this returns either:

• a) A driver-specific value/resource, only on success
• b) True, only on success (e.g. no meaningful result other than "OK")
• c) False, on any query failure

Parameters

string

$sql

SQL query

Returns

IResultWrapper|bool An IResultWrapper, or true on success; false on failure

Reimplemented in Wikimedia\Rdbms\DatabaseMysqli, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

doReleaseSavepoint()

Wikimedia\Rdbms\Database::doReleaseSavepoint (   $identifier,   $fname  )

protected

Release a savepoint.

This is used internally to implement atomic sections. It should not be used otherwise.

Stability: stable

to override

Since

1.31

Parameters

string	$identifier	Identifier for the savepoint
string	$fname	Calling function name

Definition at line 4519 of file Database.php.

doReplace()

Wikimedia\Rdbms\Database::doReplace (   $table, array  $identityKey, array  $rows,   $fname  )

protected

Parameters

string	$table
string[]	$identityKey	List of columns defining a unique key
array	$rows	Non-empty list of rows
string	$fname

See also

Database::replace()

Stability: stable

to override

Since

1.35

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3474 of file Database.php.

doRollback()

Wikimedia\Rdbms\Database::doRollback (   $fname )

protected

Issues the ROLLBACK command to the database server.

Stability: stable

to override

See also

Database::rollback()

Parameters

string

$fname

Exceptions

DBError

Definition at line 5013 of file Database.php.

doRollbackToSavepoint()

Wikimedia\Rdbms\Database::doRollbackToSavepoint (   $identifier,   $fname  )

protected

Rollback to a savepoint.

This is used internally to implement atomic sections. It should not be used otherwise.

Stability: stable

to override

Since

1.31

Parameters

string	$identifier	Identifier for the savepoint
string	$fname	Calling function name

Definition at line 4535 of file Database.php.

doSavepoint()

Wikimedia\Rdbms\Database::doSavepoint (   $identifier,   $fname  )

protected

Create a savepoint.

This is used internally to implement atomic sections. It should not be used otherwise.

Stability: stable

to override

Since

1.31

Parameters

string	$identifier	Identifier for the savepoint
string	$fname	Calling function name

Definition at line 4503 of file Database.php.

doSelectDomain()

Wikimedia\Rdbms\Database::doSelectDomain ( DatabaseDomain  $domain )

protected

Stability: stable

to override

Parameters

DatabaseDomain

$domain

Exceptions

DBConnectionError
DBError

Since

1.32

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2997 of file Database.php.

doTruncate()

Wikimedia\Rdbms\Database::doTruncate ( array  $tables,   $fname  )

protected

See also

Database::truncate()

Stability: stable

to override

Parameters

string[]	$tables
string	$fname

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5759 of file Database.php.

doUnlock()

Wikimedia\Rdbms\Database::doUnlock ( string  $lockName, string  $method  )

protected

See also

unlock()

Parameters

string	$lockName
string	$method

Returns

bool Success

Exceptions

DBError

Stability: stable

to override

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5614 of file Database.php.

doUnlockTables()

Wikimedia\Rdbms\Database::doUnlockTables (   $method )

protected

Helper function for unlockTables() that handles the actual table unlocking.

Stability: stable

to override

Parameters

string

$method

Name of caller

Returns

true

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5708 of file Database.php.

doUpsert()

Wikimedia\Rdbms\Database::doUpsert ( string  $table, array  $rows, array  $identityKey, array  $set, string  $fname  )

protected

Parameters

string	$table
array[]	$rows	Non-empty list of rows
string[]	$identityKey	List of columns defining a unique key
string[]	$set	Non-empty combined column/literal map and SQL assignment list
string	$fname

See also

Database::upsert()

Stability: stable

to override

Since

1.35

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3564 of file Database.php.

dropTable()

Wikimedia\Rdbms\Database::dropTable	(		$table,
			$fname = __METHOD__
	)

Delete a table.

Parameters

string	$table
string	$fname

Returns

bool Whether the table already existed

Exceptions

DBError

If an error occurs

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5712 of file Database.php.

duplicateTableStructure()

Wikimedia\Rdbms\Database::duplicateTableStructure	(		$oldName,
			$newName,
			$temporary = false,
			$fname = __METHOD__
	)

Creates a new table with structure copied from existing table.Note that unlike most database abstraction functions, this function does not automatically append database prefix, because it works at a lower abstraction level. The table names passed to this function shall not be quoted (this function calls addIdentifierQuotes() when needed).

Parameters

string	$oldName	Name of table whose structure should be copied
string	$newName	Name of table to be created
bool	$temporary	Whether the new table should be temporary
string	$fname	Calling function name

Returns

bool True if operation was successful

Exceptions

RuntimeException

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5060 of file Database.php.

encodeBlob()

Wikimedia\Rdbms\Database::encodeBlob

(

$b

)

Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strings to be inserted.To insert into such a field, pass the data through this function before passing it to IDatabase::insert().

Parameters

string

$b

Returns

string|Blob

Exceptions

DBError

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5297 of file Database.php.

encodeExpiry()

Wikimedia\Rdbms\Database::encodeExpiry

(

$expiry

)

Encode an expiry time into the DBMS dependent format.

Parameters

string

$expiry

Timestamp for expiry, or the 'infinity' string

Returns

string

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5774 of file Database.php.

endAtomic()

Wikimedia\Rdbms\Database::endAtomic (   $fname = __METHOD__ )

final

Ends an atomic section of SQL statements.

Ends the next section of atomic SQL statements and commits the transaction if necessary.

Since

1.23

See also

IDatabase::startAtomic

Parameters

string

$fname

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4621 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting(), and Wikimedia\Rdbms\DatabaseSqlite\doTruncate().

escapeLikeInternal()

Wikimedia\Rdbms\Database::escapeLikeInternal (   $s,   $escapeChar = '`'  )

protected

Stability: stable

to override

Parameters

string	$s
string	$escapeChar

Returns

string

Definition at line 3372 of file Database.php.

References $s.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\tableExists().

estimateRowCount()

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

Estimate the number of rows in dataset.MySQL allows you to estimate the number of rows that would be returned by a SELECT query, using EXPLAIN SELECT. The estimate is provided using index cardinality statistics, and is notoriously inaccurate, especially when large numbers of rows have recently been added or deleted.For DBMSs that don't support fast result size estimation, this function will actually perform the SELECT COUNT(*).Takes the same arguments as IDatabase::select().

Parameters

string | string[]	$tables	Table name(s)
string	$var	Column for which NULL values are not counted [default "*"]
array | string	$conds	Filters on the table
string	$fname	Function name for profiling
array	$options	Options for select
array | string	$join_conds	Join conditions

Returns

int Row count

Exceptions

DBError

If an error occurs, {

See also

query}

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 2128 of file Database.php.

References $res.

executeQuery()

Wikimedia\Rdbms\Database::executeQuery (   $sql,   $fname,   $flags  )

finalprotected

Execute a query, retrying it if there is a recoverable connection loss.

This is similar to query() except:

• It does not prevent all non-ROLLBACK queries if there is a corrupted transaction
• It does not disallow raw queries that are supposed to use dedicated IDatabase methods
• It does not throw exceptions for common error cases

This is meant for internal use with Database subclasses.

Parameters

string	$sql	Original SQL query
string	$fname	Name of the calling function
int	$flags	Bit field of class QUERY_* constants

Returns

array An n-tuple of:

• mixed|bool: An object, resource, or true on success; false on failure
• string: The result of calling lastError()
• int: The result of calling lastErrno()
• bool: Whether a rollback is needed to allow future non-rollback queries

Exceptions

DBUnexpectedError

Definition at line 1353 of file Database.php.

References Wikimedia\Rdbms\Database\$flags, Wikimedia\Rdbms\Database\$TEMP_NORMAL, Wikimedia\Rdbms\Database\assertHasConnectionHandle(), Wikimedia\Rdbms\Database\assertIsWritablePrimary(), Wikimedia\Rdbms\Database\commenceCriticalSection(), Wikimedia\Rdbms\Database\completeCriticalSection(), Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\Database\fieldHasBit(), Wikimedia\Rdbms\Database\getQueryException(), Wikimedia\Rdbms\Database\getTempTableWrites(), Wikimedia\Rdbms\Database\isWriteQuery(), Wikimedia\Rdbms\Database\registerTempWrites(), Wikimedia\Rdbms\Database\setTransactionError(), and Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\doSelectDomain(), and Wikimedia\Rdbms\Database\query().

executeQueryAttempt()

Wikimedia\Rdbms\Database::executeQueryAttempt (   $sql,   $commentedSql,   $isPermWrite,   $fname,   $flags  )

private

Wrapper for doQuery() that handles DBO_TRX, profiling, logging, affected row count tracking, and reconnects (without retry) on query failure due to connection loss.

Parameters

string	$sql	Original SQL query
string	$commentedSql	SQL query with debugging/trace comment
bool	$isPermWrite	Whether the query is a (non-temporary table) write
string	$fname	Name of the calling function
int	$flags	Bit field of class QUERY_* constants

Returns

array An n-tuple of:

• mixed|bool: An object, resource, or true on success; false on failure
• string: The result of calling lastError()
• int: The result of calling lastErrno()
  • bool: Whether a statement rollback error occurred
• bool: Whether a disconnect both happened and was recoverable
• bool: Whether a reconnection attempt was both made and succeeded

Exceptions

DBUnexpectedError

Definition at line 1451 of file Database.php.

References Wikimedia\Rdbms\Database\$flags, Wikimedia\Rdbms\Database\$profiler, Wikimedia\Rdbms\Database\affectedRows(), Wikimedia\Rdbms\Database\beginIfImplied(), Wikimedia\Rdbms\Database\canRecoverFromDisconnect(), Wikimedia\Rdbms\Database\doQuery(), Wikimedia\Rdbms\Database\getDomainID(), Wikimedia\Rdbms\Database\getFlag(), Wikimedia\Rdbms\Database\getLogContext(), Wikimedia\Rdbms\Database\getServerName(), Wikimedia\Rdbms\IDatabase\lastErrno(), Wikimedia\Rdbms\IDatabase\lastError(), Wikimedia\Rdbms\Database\lastQuery(), Wikimedia\Rdbms\Database\numRows(), Wikimedia\Rdbms\Database\replaceLostConnection(), Wikimedia\Rdbms\Database\trxLevel(), Wikimedia\Rdbms\Database\updateTrxWriteQueryTime(), Wikimedia\Rdbms\Database\wasConnectionError(), Wikimedia\Rdbms\Database\wasKnownStatementRollbackError(), and Wikimedia\Rdbms\Database\writesOrCallbacksPending().

Referenced by Wikimedia\Rdbms\Database\executeQuery().

explicitTrxActive()

Wikimedia\Rdbms\Database::explicitTrxActive

(

)

Returns

bool Whether an explicit transaction or atomic sections are still open

Since

1.28

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5052 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\assertNoOpenTransactions(), and Wikimedia\Rdbms\Database\canRecoverFromDisconnect().

extractSingleFieldFromList()

Wikimedia\Rdbms\Database::extractSingleFieldFromList (   $var )

finalprotected

Parameters

array | string

$var

Field parameter in the style of select()

Returns

string|null Column name or null; ignores aliases

Definition at line 2443 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\estimateRowCount(), and Wikimedia\Rdbms\DatabaseMysqlBase\estimateRowCount().

factory()

static Wikimedia\Rdbms\Database::factory (   $type,   $params = [],   $connect = self::NEW_CONNECTED  )

staticfinal

Construct a Database subclass instance given a database type and parameters.

This also connects to the database immediately upon object construction

Parameters

string	$type	A possible DB type (sqlite, mysql, postgres,...)
array	$params	Parameter map with keys: host : The hostname or IP address of the database server user : The name of the database user the client operates under password : The password for the database user dbname : The name of the database to use where queries do not specify one. The database must exist or an error might be thrown. Setting this to the empty string will avoid any such errors and make the handle have no implicit database scope. This is useful for queries like SHOW STATUS, CREATE DATABASE, or DROP DATABASE. Note that a "database" in Postgres is rougly equivalent to an entire MySQL server. This the domain in which user names and such are defined, e.g. users are database-specific in Postgres. schema : The database schema to use (if supported). A "schema" in Postgres is roughly equivalent to a "database" in MySQL. Note that MySQL and SQLite do not use schemas. tablePrefix : Optional table prefix that is implicitly added on to all table names recognized in queries. This can be used in place of schemas for handle site farms. flags : Optional bit field of DBO_* constants that define connection, protocol, buffering, and transaction behavior. It is STRONGLY adviced to leave the DBO_DEFAULT flag in place UNLESS this database simply acts as a key/value store. driver: Optional name of a specific DB client driver. For MySQL, there is only the 'mysqli' driver; the old one 'mysql' has been removed. variables: Optional map of session variables to set after connecting. This can be used to adjust lock timeouts or encoding modes and the like. serverName : Optional readable name for the database server. topologyRole: Optional IDatabase::ROLE_* constant for the database server. topologicalMaster: Optional name of the primary server within the replication topology. lbInfo: Optional map of field/values for the managing load balancer instance. The "master" and "replica" fields are used to flag the replication role of this database server and whether methods like getLag() should actually issue queries. lazyMasterHandle: lazy-connecting IDatabase handle to the primary DB for the cluster that this database belongs to. This is used for replication status purposes. connLogger: Optional PSR-3 logger interface instance. queryLogger: Optional PSR-3 logger interface instance. profiler : Optional callback that takes a section name argument and returns a ScopedCallback instance that ends the profile section in its destructor. These will be called in query(), using a simplified version of the SQL that also includes the agent as a SQL comment. trxProfiler: Optional TransactionProfiler instance. errorLogger: Optional callback that takes an Exception and logs it. deprecationLogger: Optional callback that takes a string and logs it. cliMode: Whether to consider the execution context that of a CLI script. agent: Optional name used to identify the end-user in query profiling/logging. srvCache: Optional BagOStuff instance to an APC-style cache. nonNativeInsertSelectBatchSize: Optional batch size for non-native INSERT SELECT. ownerId: Optional integer ID of a LoadBalancer instance that manages this instance. criticalSectionProvider: Optional CriticalSectionProvider instance.
int	$connect	One of the class constants (NEW_CONNECTED, NEW_UNCONNECTED) [optional]

Returns

Database|null If the database driver or extension cannot be found

Exceptions

InvalidArgumentException

If the database driver or extension cannot be found

Since

1.18

Definition at line 436 of file Database.php.

References Wikimedia\Rdbms\Database\$conn, $type, and Wikimedia\Rdbms\Database\getClass().

Referenced by Wikimedia\Rdbms\DatabaseSqlite\newStandaloneInstance().

fetchAffectedRowCount()

Wikimedia\Rdbms\Database::fetchAffectedRowCount ( )

abstractprotected

Returns

int Number of retrieved rows according to the driver

Reimplemented in Wikimedia\Rdbms\DatabaseMysqli, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

fetchObject()

Wikimedia\Rdbms\Database::fetchObject

(

IResultWrapper

$res

)

Fetch the next row from the given result object, in object form.

Fields can be retrieved with $row->fieldname, with fields acting like member variables. If no more rows are available, false is returned.

Deprecated:

since 1.37 use IResultWrapper::fetchObject()

Parameters

IResultWrapper

$res

Object as returned from IDatabase::query(), etc.

Returns

stdClass|bool

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 872 of file Database.php.

References $res.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\doLock(), Wikimedia\Rdbms\DatabasePostgres\doLock(), Wikimedia\Rdbms\DatabaseMysqlBase\doLockIsFree(), Wikimedia\Rdbms\DatabasePostgres\doLockIsFree(), Wikimedia\Rdbms\DatabaseMysqlBase\doUnlock(), Wikimedia\Rdbms\DatabasePostgres\doUnlock(), Wikimedia\Rdbms\DatabasePostgres\duplicateTableStructure(), Wikimedia\Rdbms\DatabaseSqlite\duplicateTableStructure(), Wikimedia\Rdbms\PostgresField\fromText(), Wikimedia\Rdbms\DatabasePostgres\getCoreSchemas(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerId(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerUUID(), Wikimedia\Rdbms\DatabaseMysqlBase\serverIsReadOnly(), Wikimedia\Rdbms\DatabasePostgres\serverIsReadOnly(), and Wikimedia\Rdbms\DatabasePostgres\textFieldSize().

fetchRow()

Wikimedia\Rdbms\Database::fetchRow

(

IResultWrapper

$res

)

Fetch the next row from the given result object, in associative array form.

Fields are retrieved with $row['fieldname']. If no more rows are available, false is returned.

Deprecated:

since 1.37 use IResultWrapper::fetchRow()

Parameters

IResultWrapper

$res

Result object as returned from IDatabase::query(), etc.

Returns

array|bool

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 876 of file Database.php.

References $res.

Referenced by Wikimedia\Rdbms\DatabasePostgres\currentSequenceValue(), Wikimedia\Rdbms\DatabasePostgres\estimateRowCount(), Wikimedia\Rdbms\DatabasePostgres\getCurrentSchema(), Wikimedia\Rdbms\DatabasePostgres\getSchemas(), Wikimedia\Rdbms\DatabasePostgres\getSearchPath(), Wikimedia\Rdbms\DatabasePostgres\insertId(), Wikimedia\Rdbms\DatabaseMysqlBase\primaryPosWait(), and Wikimedia\Rdbms\Database\selectField().

fieldExists()

Wikimedia\Rdbms\Database::fieldExists	(		$table,
			$field,
			$fname = __METHOD__
	)

Determines whether a field exists in a table.

Parameters

string	$table	Table name
string	$field	Filed to check on that table
string	$fname	Calling function name (optional)

Returns

bool Whether $table has filed $field

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2475 of file Database.php.

fieldHasBit()

Wikimedia\Rdbms\Database::fieldHasBit ( int  $flags, int  $bit  )

finalprotected

Parameters

int	$flags	A bitfield of flags
int	$bit	Bit flag constant

Returns

bool Whether the bit field has the specified bit flag set

Since

1.34

Definition at line 5840 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery(), Wikimedia\Rdbms\Database\isWriteQuery(), and Wikimedia\Rdbms\Database\query().

fieldName()

Wikimedia\Rdbms\Database::fieldName	(	IResultWrapper	$res,
			$n
	)

Get a field name in a result object.

See also

https://www.php.net/mysql_field_name

Deprecated:

since 1.37

Parameters

IResultWrapper	$res	A SQL result
int	$n

Returns

string

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 892 of file Database.php.

References $res.

fieldNamesWithAlias()

Wikimedia\Rdbms\Database::fieldNamesWithAlias (   $fields )

protected

Gets an array of aliased field names.

Parameters

array

$fields

[ [alias] => field ]

Returns

string[] See fieldNameWithAlias()

Definition at line 3200 of file Database.php.

fieldNameWithAlias()

Wikimedia\Rdbms\Database::fieldNameWithAlias (   $name,   $alias = false  )

protected

Get an aliased field name e.g.

fieldName AS newFieldName

Stability: stable

to override

Parameters

string	$name	Field name
string | bool	$alias	Alias (optional)

Returns

string SQL name for aliased field. Will not alias a field to its own name

Definition at line 3186 of file Database.php.

flatAtomicSectionList()

Wikimedia\Rdbms\Database::flatAtomicSectionList ( )

private

Returns

string

Definition at line 811 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\assertNoOpenTransactions(), and Wikimedia\Rdbms\Database\close().

flushSnapshot()

Wikimedia\Rdbms\Database::flushSnapshot	(		$fname = __METHOD__,
			$flush = self::FLUSHING_ONE
	)

Commit any transaction but error out if writes or callbacks are pending.

This is intended for clearing out REPEATABLE-READ snapshots so that callers can see a new point-in-time of the database. This is useful when one of many transaction rounds finished and significant time will pass in the script's lifetime. It is also useful to call on a replica DB after waiting on replication to catch up to the primary DB.

Parameters

string	$fname	Calling function name
string	$flush	Flush flag, set to situationally valid IDatabase::FLUSHING_* constant to disable warnings about explicitly committing implicit transactions, or calling commit when no transaction is in progress. This will trigger an exception if there is an ongoing explicit transaction. Only set the flush flag if you are sure that these warnings are not applicable, and no explicit transactions are open.

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.28

1.34 Added $flush parameter

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5020 of file Database.php.

freeResult()

Wikimedia\Rdbms\Database::freeResult

(

IResultWrapper

$res

)

Free a result object returned by query() or select()

It's usually not necessary to call this, just use unset() or let the variable holding the result object go out of scope.

Deprecated:

since 1.37 Use IResultWrapper::free()

Parameters

IResultWrapper

$res

A SQL result

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 900 of file Database.php.

References $res.

getApproximateLagStatus()

Wikimedia\Rdbms\Database::getApproximateLagStatus ( )

protected

Get a replica DB lag estimate for this server at the start of a transaction.

This is a no-op unless the server is known a priori to be a replica DB

Stability: stable

to override

Returns

array ('lag': seconds or false on error, 'since': UNIX timestamp of estimate)

Since

1.27

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5203 of file Database.php.

getAttributes()

static Wikimedia\Rdbms\Database::getAttributes ( )

staticprotected

Stability: stable

to override

Returns

array Map of (Database::ATTR_* constant => value)

Since

1.31

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 563 of file Database.php.

getBindingHandle()

Wikimedia\Rdbms\Database::getBindingHandle ( )

protected

Get the underlying binding connection handle.

Makes sure the connection resource is set (disconnects and ping() failure can unset it). This catches broken callers than catch and ignore disconnection exceptions. Unlike checking isOpen(), this is safe to call inside of open().

Stability: stable

to override

Returns

mixed

Exceptions

DBUnexpectedError

Since

1.26

Reimplemented in Wikimedia\Rdbms\DatabaseMysqli, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5856 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\addQuotes(), Wikimedia\Rdbms\DatabasePostgres\doQuery(), Wikimedia\Rdbms\DatabasePostgres\getServerVersion(), and Wikimedia\Rdbms\DatabasePostgres\strencode().

getCacheSetOptions()

static Wikimedia\Rdbms\Database::getCacheSetOptions ( ?IDatabase ...  $dbs )

static

Merge the result of getSessionLagStatus() for several DBs using the most pessimistic values to estimate the lag of any data derived from them in combination.

This is information is useful for caching modules

See also

WANObjectCache::set()

WANObjectCache::getWithSetCallback()

Parameters

IDatabase|null

...$dbs Note: For backward compatibility, it is allowed for null values to be passed among the parameters. This is deprecated since 1.36, only IDatabase objects should be passed.

Returns

array Map of values:

• lag: highest lag of any of the DBs or false on error (e.g. replication stopped)
• since: oldest UNIX timestamp of any of the DB lag estimates
• pending: whether any of the DBs have uncommitted changes

Exceptions

DBError

Since

1.27

Definition at line 5240 of file Database.php.

References $res.

getClass()

static Wikimedia\Rdbms\Database::getClass (   $dbType,   $driver = null  )

staticprivate

Parameters

string	$dbType	A possible DB type (sqlite, mysql, postgres,...)
string | null	$driver	Optional name of a specific DB client driver

Returns

string Database subclass name to use

Exceptions

InvalidArgumentException

Definition at line 510 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\attributesFromType(), and Wikimedia\Rdbms\Database\factory().

getDBname()

Wikimedia\Rdbms\Database::getDBname

(

)

Get the current database name; null if there isn't one.

Returns

string|null

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3001 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseSqlite\attachDatabasesFromTableAliases(), Wikimedia\Rdbms\Database\dbSchema(), Wikimedia\Rdbms\DatabaseMysqlBase\doSelectDomain(), Wikimedia\Rdbms\DatabasePostgres\doSelectDomain(), Wikimedia\Rdbms\DatabaseSqlite\doSelectDomain(), Wikimedia\Rdbms\DatabaseSqlite\getDbFilePath(), Wikimedia\Rdbms\Database\getLogContext(), and Wikimedia\Rdbms\DatabaseMysqlBase\listViews().

getDefaultSchemaVars()

Wikimedia\Rdbms\Database::getDefaultSchemaVars ( )

protected

Get schema variables to use if none have been set via setSchemaVars().

Override this in derived classes to provide variables for tables.sql and SQL patch files.

Stability: stable

to override

Returns

array

Definition at line 5523 of file Database.php.

getDomainID()

Wikimedia\Rdbms\Database::getDomainID

(

)

Return the currently selected domain ID.

Null components (database/schema) might change once a connection is established

Returns

string

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 868 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseSqlite\__construct(), Wikimedia\Rdbms\Database\executeQueryAttempt(), and Wikimedia\Rdbms\Database\handleSessionLossPreconnect().

getFlag()

Wikimedia\Rdbms\Database::getFlag

(

$flag

)

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

Parameters

int

$flag

One of the class IDatabase::DBO_* constants

Returns

bool

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 864 of file Database.php.

Referenced by Wikimedia\Rdbms\LoadBalancer\applyTransactionRoundFlags(), Wikimedia\Rdbms\Database\beginIfImplied(), Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\Database\getTransactionRoundId(), Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabasePostgres\open(), Wikimedia\Rdbms\DatabaseSqlite\open(), and Wikimedia\Rdbms\LoadBalancer\undoTransactionRoundFlags().

getInfinity()

Wikimedia\Rdbms\Database::getInfinity

(

)

Find out when 'infinity' is.Most DBMSes support this. This is a special keyword for timestamps in PostgreSQL, and works with CHAR(14) as well because "i" sorts after all numbers.

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5770 of file Database.php.

getLag()

Wikimedia\Rdbms\Database::getLag

(

)

Get the amount of replication lag for this database server.

Callers should avoid using this method while a transaction is active

Returns

float|int|false Database replication lag in seconds or false on error

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5260 of file Database.php.

getLastPHPError()

Wikimedia\Rdbms\Database::getLastPHPError ( )

protected

Returns

string|bool Last PHP error for this DB (typically connection errors)

Definition at line 950 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\lastError(), and Wikimedia\Rdbms\Database\restoreErrorHandler().

getLazyMasterHandle()

Wikimedia\Rdbms\Database::getLazyMasterHandle ( )

protected

Get a handle to the primary DB server of the cluster to which this server belongs.

Returns

IDatabase|null

Since

1.27

Definition at line 691 of file Database.php.

References Wikimedia\Rdbms\Database\$lazyMasterHandle.

getLBInfo()

Wikimedia\Rdbms\Database::getLBInfo

(

$name = null

)

Get properties passed down from the server info array of the load balancer.

Parameters

string | null

$name

The entry of the info array to get, or null to get the whole array

Returns

array|mixed|null

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 659 of file Database.php.

References Wikimedia\Rdbms\Database\$lbInfo.

Referenced by Wikimedia\Rdbms\LoadBalancer\applyTransactionRoundFlags(), Wikimedia\Rdbms\Database\getTransactionRoundId(), and Wikimedia\Rdbms\LoadBalancer\undoTransactionRoundFlags().

getLogContext()

Wikimedia\Rdbms\Database::getLogContext ( array  $extras = [] )

protected

Create a log context to pass to PSR-3 logger functions.

Parameters

array

$extras

Additional data to add to context

Returns

array

Definition at line 979 of file Database.php.

References Wikimedia\Rdbms\Database\getDBname(), and Wikimedia\Rdbms\Database\getServerName().

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\DatabaseMysqlBase\getLagFromPtHeartbeat(), Wikimedia\Rdbms\Database\getQueryExceptionAndLog(), Wikimedia\Rdbms\Database\newExceptionAfterConnectError(), Wikimedia\Rdbms\DatabaseSqlite\open(), and Wikimedia\Rdbms\DatabaseMysqlBase\primaryPosWait().

getMasterPos()

Wikimedia\Rdbms\Database::getMasterPos

(

)

Deprecated:

since 1.37; use getPrimaryPos() instead.

Returns

DBPrimaryPos|bool False if this is not a primary DB

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 4100 of file Database.php.

References wfDeprecated().

getPrimaryPos()

Wikimedia\Rdbms\Database::getPrimaryPos

(

)

Get the position of this primary DB.

Returns

DBPrimaryPos|bool False if this is not a primary DB

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.37

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 4095 of file Database.php.

getQueryException()

Wikimedia\Rdbms\Database::getQueryException (   $error,   $errno,   $sql,   $fname  )

private

Parameters

string	$error
string | int	$errno
string	$sql
string	$fname

Returns

DBError

Definition at line 1803 of file Database.php.

References Wikimedia\Rdbms\Database\wasConnectionError(), and Wikimedia\Rdbms\Database\wasQueryTimeout().

Referenced by Wikimedia\Rdbms\Database\executeQuery(), and Wikimedia\Rdbms\Database\getQueryExceptionAndLog().

getQueryExceptionAndLog()

Wikimedia\Rdbms\Database::getQueryExceptionAndLog (   $error,   $errno,   $sql,   $fname  )

private

Parameters

string	$error
string | int	$errno
string	$sql
string	$fname

Returns

DBError

Definition at line 1779 of file Database.php.

References Wikimedia\Rdbms\Database\getLogContext(), and Wikimedia\Rdbms\Database\getQueryException().

Referenced by Wikimedia\Rdbms\Database\reportQueryError().

getQueryVerb()

Wikimedia\Rdbms\Database::getQueryVerb (   $sql )

protected

Parameters

string

$sql

Returns

string|null

Definition at line 1186 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\assertQueryIsCurrentlyAllowed(), Wikimedia\Rdbms\Database\isTransactableQuery(), Wikimedia\Rdbms\DatabaseSqlite\isTransactableQuery(), and Wikimedia\Rdbms\Database\updateTrxWriteQueryTime().

getReadOnlyReason()

Wikimedia\Rdbms\Database::getReadOnlyReason ( )

protected

Returns

array|bool Tuple of (read-only reason, "role" or "lb") or false if it is not

Definition at line 5803 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\assertIsWritablePrimary().

getRecordedTransactionLagStatus()

Wikimedia\Rdbms\Database::getRecordedTransactionLagStatus ( )

finalprotected

Get the replica DB lag when the current transaction started.

This is useful when transactions might use snapshot isolation (e.g. REPEATABLE-READ in innodb), so the "real" lag of that data is this lag plus transaction duration. If they don't, it is still safe to be pessimistic. This returns null if there is no transaction.

This returns null if the lag status for this transaction was not yet recorded.

Returns

array|null ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)

Since

1.27

Definition at line 5190 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\getLagFromPtHeartbeat().

getReplicaPos()

Wikimedia\Rdbms\Database::getReplicaPos

(

)

Get the replication position of this replica DB.

Returns

DBPrimaryPos|bool False if this is not a replica DB

Exceptions

DBError

If an error occurs, {

See also

query}

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 4086 of file Database.php.

getSchemaVars()

Wikimedia\Rdbms\Database::getSchemaVars ( )

protected

Get schema variables.

If none have been set via setSchemaVars(), then use some defaults from the current object.

Returns

array

Definition at line 5510 of file Database.php.

getScopedLockAndFlush()

Wikimedia\Rdbms\Database::getScopedLockAndFlush	(		$lockKey,
			$fname,
			$timeout
	)

Acquire a named lock, flush any transaction, and return an RAII style unlocker object.

Only call this from outer transaction scope and when only one DB will be affected. See https://www.mediawiki.org/wiki/Database_transactions for details.

This is suitable for transactions that need to be serialized using cooperative locks, where each transaction can see each others' changes. Any transaction is flushed to clear out stale REPEATABLE-READ snapshot data. Once the returned object falls out of PHP scope, the lock will be released unless a transaction is active. If one is active, then the lock will be released when it either commits or rolls back.

If the lock acquisition failed, then no transaction flush happens, and null is returned.

Parameters

string	$lockKey	Name of lock to release
string	$fname	Name of the calling method
int	$timeout	Acquisition timeout in seconds

Returns

ScopedCallback|null

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.27

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5618 of file Database.php.

getServer()

Wikimedia\Rdbms\Database::getServer

(

)

Get the hostname or IP address of the server.

Returns

string|null

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3005 of file Database.php.

getServerInfo()

Wikimedia\Rdbms\Database::getServerInfo

(

)

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

Use getServerVersion() to get machine-friendly information.

Returns

string Version information from the database server

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 578 of file Database.php.

References Wikimedia\Rdbms\IDatabase\getServerVersion().

getServerName()

Wikimedia\Rdbms\Database::getServerName

(

)

Get the readable name for the server.

Returns

string Readable server name, falling back to the hostname or IP address

Since

1.36

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3009 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\DatabaseMysqlBase\getApproximateLagStatus(), Wikimedia\Rdbms\Database\getLogContext(), Wikimedia\Rdbms\DatabaseMysqlBase\getPrimaryServerInfo(), Wikimedia\Rdbms\Database\handleSessionLossPreconnect(), and Wikimedia\Rdbms\DatabaseMysqlBase\lastError().

getServerUptime()

Wikimedia\Rdbms\Database::getServerUptime

(

)

Determines how long the server has been up.

Returns

int

Exceptions

DBError

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3959 of file Database.php.

getSessionLagStatus()

Wikimedia\Rdbms\Database::getSessionLagStatus

(

)

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

This is useful when transactions might use snapshot isolation (e.g. REPEATABLE-READ in innodb), so the "real" lag of that data is this lag plus transaction duration. If they don't, it is still safe to be pessimistic. In AUTOCOMMIT mode, this still gives an indication of the staleness of subsequent reads.

Returns

array ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.27

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5173 of file Database.php.

getTempTableWrites()

Wikimedia\Rdbms\Database::getTempTableWrites (   $sql,   $pseudoPermanent  )

protected

Parameters

string	$sql	SQL query
bool	$pseudoPermanent	Treat any table from CREATE TEMPORARY as pseudo-permanent

Returns

array[] List of change n-tuples with:

• int: self::TEMP_* constant for temp table operations
• string: SQL query verb from $sql
• string: Name of the temp table changed in $sql

Definition at line 1220 of file Database.php.

References Wikimedia\Rdbms\Database\$TEMP_NORMAL, and Wikimedia\Rdbms\Database\$TEMP_PSEUDO_PERMANENT.

Referenced by Wikimedia\Rdbms\Database\executeQuery().

getTopologyBasedServerId()

Wikimedia\Rdbms\Database::getTopologyBasedServerId

(

)

Get a non-recycled ID that uniquely identifies this server within the replication topology.

A replication topology defines which servers can originate changes to a given dataset and how those changes propagate among database servers. It is assumed that the server only participates in the replication of a single relevant dataset.

Returns

string|null 32, 64, or 128 bit integer ID; null if not applicable or unknown

Exceptions

DBQueryError

Since

1.37

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 582 of file Database.php.

getTopologyRole()

Wikimedia\Rdbms\Database::getTopologyRole

(

)

Get the replication topology role of this server.

A replication topology defines which servers can originate changes to a given dataset and how those changes propagate among database servers. It is assumed that the server only participates in the replication of a single relevant dataset.

Returns

string One of the class ROLE_* constants

Exceptions

DBQueryError

Since

1.34

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 586 of file Database.php.

References Wikimedia\Rdbms\Database\$topologyRole.

getTopologyRootMaster()

Wikimedia\Rdbms\Database::getTopologyRootMaster

(

)

Deprecated:

since 1.37; use getTopologyRootPrimary() instead.

Returns

string|null Readable server name; null if unknown or if co-primaries are defined

Exceptions

DBQueryError

Since

1.34

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 594 of file Database.php.

References Wikimedia\Rdbms\Database\$topologyRootMaster, and wfDeprecated().

getTopologyRootPrimary()

Wikimedia\Rdbms\Database::getTopologyRootPrimary

(

)

Get the readable name of the sole root primary DB server for the replication topology.

A replication topology defines which servers can originate changes to a given dataset and how those changes propagate among database servers. It is assumed that the server only participates in the replication of a single relevant dataset.

Returns

string|null Readable server name; null if unknown or if co-primaries are defined

Exceptions

DBQueryError

Since

1.37

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 590 of file Database.php.

References Wikimedia\Rdbms\Database\$topologyRootMaster.

getTransactionRoundId()

Wikimedia\Rdbms\Database::getTransactionRoundId ( )

finalprotected

Returns

string|null ID of the active explicit transaction round being participating in

Definition at line 732 of file Database.php.

References Wikimedia\Rdbms\Database\getFlag(), and Wikimedia\Rdbms\Database\getLBInfo().

handleSessionLossPostconnect()

Wikimedia\Rdbms\Database::handleSessionLossPostconnect ( )

private

Clean things up after session (and thus transaction) loss after reconnect.

Definition at line 1718 of file Database.php.

References Wikimedia\Rdbms\Database\runOnTransactionIdleCallbacks(), and Wikimedia\Rdbms\Database\runTransactionListenerCallbacks().

handleSessionLossPreconnect()

Wikimedia\Rdbms\Database::handleSessionLossPreconnect ( )

private

Clean things up after session (and thus transaction) loss before reconnect.

Definition at line 1679 of file Database.php.

References Wikimedia\Rdbms\Database\consumeTrxShortId(), Wikimedia\Rdbms\Database\doHandleSessionLossPreconnect(), Wikimedia\Rdbms\Database\getDomainID(), Wikimedia\Rdbms\Database\getServerName(), and Wikimedia\Rdbms\Database\pendingWriteQueryDuration().

ignoreIndexClause()

Wikimedia\Rdbms\Database::ignoreIndexClause

(

$index

)

IGNORE INDEX clause.

The inverse of Database::useIndexClause.

Stability: stable

to override

Parameters

string

$index

Returns

string

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3449 of file Database.php.

implicitOrderby()

Wikimedia\Rdbms\Database::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.

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 699 of file Database.php.

indexExists()

Wikimedia\Rdbms\Database::indexExists	(		$table,
			$index,
			$fname = __METHOD__
	)

Determines whether an index exists.

Parameters

string	$table
string	$index
string	$fname

Returns

bool|null

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2481 of file Database.php.

indexInfo()

Wikimedia\Rdbms\Database::indexInfo (   $table,   $index,   $fname = __METHOD__  )

abstract

Get information about an index into an object.

Stability: stable

to override

Parameters

string	$table	Table name
string	$index	Index name
string	$fname	Calling function name

Returns

mixed Database-specific index description class or false if the index does not exist

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

indexName()

Wikimedia\Rdbms\Database::indexName (   $index )

protected

Allows for index remapping in queries where this is not consistent across DBMS.

Parameters

string

$index

Returns

string

Definition at line 3321 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\ignoreIndexClause(), Wikimedia\Rdbms\DatabaseMysqlBase\indexInfo(), Wikimedia\Rdbms\DatabaseSqlite\indexInfo(), Wikimedia\Rdbms\DatabasePostgres\indexUnique(), Wikimedia\Rdbms\DatabaseSqlite\indexUnique(), and Wikimedia\Rdbms\DatabaseMysqlBase\useIndexClause().

indexUnique()

Wikimedia\Rdbms\Database::indexUnique	(		$table,
			$index,
			$fname = __METHOD__
	)

Determines if a given index is unique.

Parameters

string	$table
string	$index
string	$fname	Calling function name

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2500 of file Database.php.

initConnection()

Wikimedia\Rdbms\Database::initConnection ( )

final

Initialize the connection to the database over the wire (or to local files)

Exceptions

LogicException
InvalidArgumentException
DBConnectionError

Since

1.31

Definition at line 343 of file Database.php.

References Wikimedia\Rdbms\Database\doInitConnection(), and Wikimedia\Rdbms\Database\isOpen().

insert()

Wikimedia\Rdbms\Database::insert	(		$table,
			$rows,
			$fname = __METHOD__,
			$options = []
	)

Insert the given row(s) into a table.

Parameters

string	$table	Table name
array | array[]	$rows	Row(s) to insert, as either: A string-keyed map of (column name => value) defining a new row. Values are treated as literals and quoted appropriately; null is interpreted as NULL. An integer-keyed list of such string-keyed maps, defining a list of new rows. The keys in each map must be identical to each other and in the same order. The rows must not collide with each other.
string	$fname	Calling function name (use METHOD) for logs/profiling
string | array	$options	Combination map/list where each string-keyed entry maps a non-boolean option to the option parameters and each integer-keyed value is the name of a boolean option. Supported options are: IGNORE: Boolean: skip insertion of rows that would cause unique key conflicts. IDatabase::affectedRows() can be used to determine how many rows were inserted.

Returns

bool Return true if no exception was thrown (deprecated since 1.33)

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2510 of file Database.php.

insertSelect()

Wikimedia\Rdbms\Database::insertSelect (   $destTable,   $srcTable,   $varMap,   $conds,   $fname = __METHOD__,   $insertOptions = [],   $selectOptions = [],   $selectJoinConds = []  )

final

INSERT SELECT wrapper.

Warning

If the insert will use an auto-increment or sequence to determine the value of a column, this may break replication on databases using statement-based replication if the SELECT is not deterministically ordered.

Parameters

string	$destTable	The table name to insert into
string | array	$srcTable	May be either a table name, or an array of table names to include in a join.
array	$varMap	Must be an associative array of the form [ 'dest1' => 'source1', ... ]. Source items may be literals rather than field names, but strings should be quoted with IDatabase::addQuotes()
array	$conds	Condition array. See $conds in IDatabase::select() for the details of the format of condition arrays. May be "*" to copy the whole table.
string	$fname	The function name of the caller, from METHOD
array	$insertOptions	Options for the INSERT part of the query, see IDatabase::insert() for details. Also, one additional option is available: pass 'NO_AUTO_COLUMNS' to hint that the query does not use an auto-increment or sequence to determine any column values.
array	$selectOptions	Options for the SELECT part of the query, see IDatabase::select() for details.
array	$selectJoinConds	Join conditions for the SELECT part of the query, see IDatabase::select() for details.

Returns

bool Return true if no exception was thrown (deprecated since 1.33)

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3660 of file Database.php.

installErrorHandler()

Wikimedia\Rdbms\Database::installErrorHandler ( )

protected

Set a custom error handler for logging errors during database connection.

Definition at line 927 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabasePostgres\open().

isFlagInOptions()

Wikimedia\Rdbms\Database::isFlagInOptions (   $option, array  $options  )

finalprotected

Parameters

string	$option	Query option flag (e.g. "IGNORE" or "FOR UPDATE")
array	$options	Combination option/value map and boolean option list

Returns

bool Whether the option appears as an integer-keyed value in the options

Since

1.35

Definition at line 2429 of file Database.php.

isInsertSelectSafe()

Wikimedia\Rdbms\Database::isInsertSelectSafe ( array  $insertOptions, array  $selectOptions  )

protected

Stability: stable

to override

Parameters

array	$insertOptions	INSERT options
array	$selectOptions	SELECT options

Returns

bool Whether an INSERT SELECT with these options will be replication safe

Since

1.31

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3711 of file Database.php.

isOpen()

Wikimedia\Rdbms\Database::isOpen

(

)

Returns

bool Whether a connection to the database open

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 817 of file Database.php.

References Wikimedia\Rdbms\Database\$conn.

Referenced by Wikimedia\Rdbms\Database\assertHasConnectionHandle(), Wikimedia\Rdbms\Database\initConnection(), and Wikimedia\Rdbms\DatabaseSqlite\setTableAliases().

isPristineTemporaryTable()

Wikimedia\Rdbms\Database::isPristineTemporaryTable (   $table )

protected

Check if the table is both a TEMPORARY table and has not yet received CRUD operations.

Parameters

string

$table

Returns

bool

Since

1.35

Definition at line 1307 of file Database.php.

References Wikimedia\Rdbms\Database\tableName().

isQuotedIdentifier()

Wikimedia\Rdbms\Database::isQuotedIdentifier

(

$name

)

Returns if the given identifier looks quoted or not according to the database convention for quoting identifiers.

Stability: stable

to override

Note

Do not use this to determine if untrusted input is safe. A malicious user can trick this function.

Parameters

string

$name

Returns

bool

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3362 of file Database.php.

isReadOnly()

Wikimedia\Rdbms\Database::isReadOnly

(

)

Returns

bool Whether this DB is read-only

Since

1.27

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5796 of file Database.php.

isTransactableQuery()

Wikimedia\Rdbms\Database::isTransactableQuery (   $sql )

protected

Determine whether a SQL statement is sensitive to isolation level.

A SQL statement is considered transactable if its result could vary depending on the transaction isolation level. Operational commands such as 'SET' and 'SHOW' are not considered to be transactable.

Main purpose: Used by query() to decide whether to begin a transaction before the current query (in DBO_TRX mode, on by default).

Stability: stable

to override

Parameters

string

$sql

Returns

bool

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 1204 of file Database.php.

References Wikimedia\Rdbms\Database\getQueryVerb().

Referenced by Wikimedia\Rdbms\Database\beginIfImplied().

isWriteQuery()

Wikimedia\Rdbms\Database::isWriteQuery (   $sql,   $flags  )

protected

Determine whether a query writes to the DB.

When in doubt, this returns true.

Main use cases:

• Subsequent web requests should not need to wait for replication from the primary position seen by this web request, unless this request made changes to the primary DB. This is handled by ChronologyProtector by checking doneWrites() at the end of the request. doneWrites() returns true if any query set lastWriteTime; which query() does based on isWriteQuery().
• Reject write queries to replica DBs, in query().

Parameters

string	$sql
int	$flags	Query flags to query()

Returns

bool

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 1154 of file Database.php.

References Wikimedia\Rdbms\Database\$flags, and Wikimedia\Rdbms\Database\fieldHasBit().

Referenced by Wikimedia\Rdbms\Database\executeQuery().

lastDoneWrites()

Wikimedia\Rdbms\Database::lastDoneWrites

(

)

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

Returns

int|float UNIX timestamp or false

Since

1.24

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 707 of file Database.php.

lastQuery()

Wikimedia\Rdbms\Database::lastQuery

(

)

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

Returns

string SQL text or empty string if there was no such query

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 703 of file Database.php.

References Wikimedia\Rdbms\Database\$lastQuery.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

limitResult()

Wikimedia\Rdbms\Database::limitResult	(		$sql,
			$limit,
			$offset = false
	)

Construct a LIMIT query with optional offset.The SQL should be adjusted so that only the first $limit rows are returned. If $offset is provided as well, then the first $offset rows should be discarded, and the next $limit rows should be returned. If the result of the query is not ordered, then the rows to be returned are theoretically arbitrary.$sql is expected to be a SELECT, if that makes a difference.

Parameters

string	$sql	SQL query we will append the limit too
int	$limit	The SQL limit
int | bool	$offset	The SQL offset (default false)

Returns

string

Since

1.34

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 3827 of file Database.php.

listTables()

Wikimedia\Rdbms\Database::listTables	(		$prefix = null,
			$fname = __METHOD__
	)

List all tables on the database.

Parameters

string | null	$prefix	Only show tables with this prefix, e.g. mw_
string	$fname	Calling function name

Exceptions

DBError

Returns

array

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5073 of file Database.php.

listViews()

Wikimedia\Rdbms\Database::listViews	(		$prefix = null,
			$fname = __METHOD__
	)

Lists all the VIEWs in the database.

Parameters

string | null	$prefix	Only show VIEWs with this prefix, eg. unit_test_
string	$fname	Name of calling function

Exceptions

RuntimeException

Returns

array

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5081 of file Database.php.

lock()

Wikimedia\Rdbms\Database::lock	(		$lockName,
			$method,
			$timeout = 5,
			$flags = 0
	)

Acquire a named lock.Named locks are not related to transactions

Parameters

string	$lockName	Name of lock to aquire
string	$method	Name of the calling method
int	$timeout	Acquisition timeout in seconds (0 means non-blocking)
int	$flags	Bit field of IDatabase::LOCK_* constants

Returns

bool Success

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5559 of file Database.php.

lockForUpdate()

Wikimedia\Rdbms\Database::lockForUpdate	(		$table,
			$conds = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

Lock all rows meeting the given conditions/options FOR UPDATE.

Parameters

string | string[]	$table	Table name(s)
array | string	$conds	Filters on the table
string	$fname	Function name for profiling
array	$options	Options for select ("FOR UPDATE" is added automatically)
array	$join_conds	Join conditions

Returns

int Number of matching rows found (and locked)

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2459 of file Database.php.

lockIsFree()

Wikimedia\Rdbms\Database::lockIsFree	(		$lockName,
			$method
	)

Check to see if a named lock is not locked by any thread (non-blocking)

Parameters

string	$lockName	Name of lock to poll
string	$method	Name of method calling us

Returns

bool

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.20

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5530 of file Database.php.

lockTables()

Wikimedia\Rdbms\Database::lockTables ( array  $read, array  $write,   $method  )

final

Lock specific tables.

Any pending transaction should be resolved before calling this method, since: a) Doing so resets any REPEATABLE-READ snapshot of the data to a fresh one. b) Previous row and table locks from the transaction or session may be released by LOCK TABLES, which may be unsafe for the changes in such a transaction. c) The main use case of lockTables() is to avoid deadlocks and timeouts by locking entire tables in order to do long-running, batched, and lag-aware, updates. Batching and replication lag checks do not work when all the updates happen in a transaction.

Always get all relevant table locks up-front in one call, since LOCK TABLES might release any prior table locks on some RDBMes (e.g MySQL).

For compatibility, callers should check tableLocksHaveTransactionScope() before using this method. If locks are scoped specifically to transactions then caller must either:

• a) Start a new transaction and acquire table locks for the scope of that transaction, doing all row updates within that transaction. It will not be possible to update rows in batches; this might result in high replication lag.
• b) Forgo table locks entirely and avoid calling this method. Careful use of hints like LOCK IN SHARE MODE and FOR UPDATE and the use of query batching may be preferrable to using table locks with a potentially large transaction. Use of MySQL and Postges style REPEATABLE-READ (Snapshot Isolation with or without First-Committer-Rule) can also be considered for certain tasks that require a consistent view of entire tables.

If session scoped locks are not supported, then calling lockTables() will trigger startAtomic(), with unlockTables() triggering endAtomic(). This will automatically start a transaction if one is not already present and cause the locks to be released when the transaction finishes (normally during the unlockTables() call).

In any case, avoid using begin()/commit() in code that runs while such table locks are acquired, as that breaks in case when a transaction is needed. The startAtomic() and endAtomic() methods are safe, however, since they will join any existing transaction.

Parameters

array	$read	Array of tables to lock for read access
array	$write	Array of tables to lock for write access
string	$method	Name of caller

Returns

bool

Since

1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 5666 of file Database.php.

makeGroupByWithHaving()

Wikimedia\Rdbms\Database::makeGroupByWithHaving (   $options )

protected

Returns an optional GROUP BY with an optional HAVING.

Parameters

array

$options

Associative array of options

Returns

string

See also

Database::select()

Since

1.21

Definition at line 1969 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\makeSelectOptions().

makeInsertLists()

Wikimedia\Rdbms\Database::makeInsertLists ( array  $rows )

protected

Make SQL lists of columns, row tuples for INSERT/VALUES expressions.

The tuple column order is that of the columns of the first provided row. The provided rows must have exactly the same keys and ordering thereof.

Parameters

array[]

$rows

Non-empty list of (column => value) maps

Returns

array (comma-separated columns, comma-separated tuples)

Since

1.35

Definition at line 2580 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting(), Wikimedia\Rdbms\DatabaseMysqlBase\doReplace(), Wikimedia\Rdbms\DatabaseSqlite\doReplace(), and Wikimedia\Rdbms\DatabaseMysqlBase\doUpsert().

makeInsertNonConflictingVerbAndOptions()

Wikimedia\Rdbms\Database::makeInsertNonConflictingVerbAndOptions ( )

protected

Stability: stable

to override

Returns

string[] ("INSERT"-style SQL verb, "ON CONFLICT"-style clause or "")

Since

1.35

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2566 of file Database.php.

makeKeyCollisionCondition()

Wikimedia\Rdbms\Database::makeKeyCollisionCondition ( array  $rows, array  $uniqueKey  )

private

Build an SQL condition to find rows with matching key values to those in $rows.

Parameters

array[]	$rows	Non-empty list of rows
string[]	$uniqueKey	List of columns that define a single unique index

Returns

string

Definition at line 3502 of file Database.php.

makeList()

Wikimedia\Rdbms\Database::makeList	(	array	$a,
			$mode = self::LIST_COMMA
	)

Makes an encoded list of strings from an array.

These can be used to make conjunctions or disjunctions on SQL condition strings derived from an array ({

See also

select} $conds documentation).

Example usage:

$sql = $db->makeList( [
    'rev_page' => $id,
    $db->makeList( [ 'rev_minor' => 1, 'rev_len' < 500 ], $db::LIST_OR ] )
], $db::LIST_AND );

This would set $sql to "rev_page = '$id' AND (rev_minor = '1' OR rev_len < '500')"

Parameters

array	$a	Containing the data
int	$mode	IDatabase class constant: IDatabase::LIST_COMMA: Comma separated, no field names IDatabase::LIST_AND: ANDed WHERE clause (without the WHERE). IDatabase::LIST_OR: ORed WHERE clause (without the WHERE) IDatabase::LIST_SET: Comma separated with field names, like a SET clause IDatabase::LIST_NAMES: Comma separated field names

Exceptions

DBError

If an error occurs, {

See also

query}

Returns

string

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2659 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\deleteJoin(), Wikimedia\Rdbms\DatabaseMysqlBase\doUpsert(), and Wikimedia\Rdbms\DatabaseMysqlBase\fetchSecondsSinceHeartbeat().

makeOrderBy()

Wikimedia\Rdbms\Database::makeOrderBy (   $options )

protected

Returns an optional ORDER BY.

Parameters

array

$options

Associative array of options

Returns

string

See also

Database::select()

Since

1.21

Definition at line 1995 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\makeSelectOptions().

makeSelectOptions()

Wikimedia\Rdbms\Database::makeSelectOptions ( array  $options )

protected

Returns an optional USE INDEX clause to go after the table, and a string to go at the end of the query.

See also

Database::select()

Stability: stable

to override

Parameters

array

$options

Associative array of options to be turned into an SQL query, valid keys are listed in the function.

Returns

array

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 1898 of file Database.php.

makeUpdateOptions()

Wikimedia\Rdbms\Database::makeUpdateOptions (   $options )

protected

Make UPDATE options for the Database::update function.

Stability: stable

to override

Parameters

array

$options

The options passed to Database::update

Returns

string

Definition at line 2635 of file Database.php.

makeUpdateOptionsArray()

Wikimedia\Rdbms\Database::makeUpdateOptionsArray (   $options )

protected

Make UPDATE options array for Database::makeUpdateOptions.

Stability: stable

to override

Parameters

array

$options

Returns

array

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 2616 of file Database.php.

makeWhereFrom2d()

Wikimedia\Rdbms\Database::makeWhereFrom2d	(		$data,
			$baseKey,
			$subKey
	)

Build a partial where clause from a 2-d array such as used for LinkBatch.

The keys on each level may be either integers or strings, however it's assumed that $baseKey is probably an integer-typed column (i.e. integer keys are unquoted in the SQL) and $subKey is string-typed (i.e. integer keys are quoted as strings in the SQL).

Todo:

Does this actually belong in the library? It seems overly MW-specific.

Parameters

array	$data	Organized as 2-d [ baseKeyVal => [ subKeyVal => [ignored], ... ], ... ]
string	$baseKey	Field name to match the base-level keys to (eg 'pl_namespace')
string	$subKey	Field name to match the sub-level keys to (eg 'pl_title')

Returns

string|bool SQL fragment, or false if no items in array

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2735 of file Database.php.

References $base.

masterPosWait()

Wikimedia\Rdbms\Database::masterPosWait	(	DBPrimaryPos	$pos,
			$timeout
	)

Deprecated:

since 1.37; use primaryPosWait() instead.

Parameters

DBPrimaryPos	$pos
int	$timeout	The maximum number of seconds to wait for synchronisation

Returns

int|null Zero if the replica DB was past that position already, greater than zero if we waited for some period of time, less than zero if it timed out, and null on error

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4077 of file Database.php.

References wfDeprecated().

maxListLen()

Wikimedia\Rdbms\Database::maxListLen

(

)

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

Returns

int

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5289 of file Database.php.

modifyCallbacksForCancel()

Wikimedia\Rdbms\Database::modifyCallbacksForCancel ( array  $sectionIds, AtomicSectionIdentifier  $newSectionId = null  )

private

Update callbacks that were owned by cancelled atomic sections.

Callbacks for "on commit" should never be run if they're owned by a section that won't be committed.

Callbacks for "on resolution" need to reflect that the section was rolled back, even if the transaction as a whole commits successfully.

Callbacks for "on section cancel" should already have been consumed, but errors during the cancellation itself can prevent that while still destroying the section. Hoist any such callbacks to the new top section, which we assume will itself have to be cancelled or rolled back to resolve the error.

Parameters

AtomicSectionIdentifier[]	$sectionIds	ID of an actual savepoint
AtomicSectionIdentifier | null	$newSectionId	New top section ID.

Exceptions

UnexpectedValueException

Definition at line 4248 of file Database.php.

namedLocksEnqueue()

Wikimedia\Rdbms\Database::namedLocksEnqueue

(

)

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

Returns

bool

Since

1.26

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5658 of file Database.php.

newExceptionAfterConnectError()

Wikimedia\Rdbms\Database::newExceptionAfterConnectError (   $error )

finalprotected

Parameters

string

$error

Returns

DBConnectionError

Definition at line 1817 of file Database.php.

References Wikimedia\Rdbms\Database\getLogContext().

Referenced by Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), Wikimedia\Rdbms\DatabasePostgres\open(), and Wikimedia\Rdbms\DatabaseSqlite\open().

newSelectQueryBuilder()

Wikimedia\Rdbms\Database::newSelectQueryBuilder

(

)

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

Returns

SelectQueryBuilder

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 1835 of file Database.php.

nextSavepointId()

Wikimedia\Rdbms\Database::nextSavepointId (   $fname )

private

Parameters

string

$fname

Returns

string

Definition at line 4544 of file Database.php.

nextSequenceValue()

Wikimedia\Rdbms\Database::nextSequenceValue

(

$seqName

)

Deprecated method, calls should be removed.

This was formerly used for PostgreSQL to handle self::insertId() auto-incrementing fields. It is no longer necessary since DatabasePostgres::insertId() has been reimplemented using lastval()

Implementations should return null if inserting NULL into an auto-incrementing field works, otherwise it should return an instance of NextSequenceValue and filter it on calls to relevant methods.

Deprecated:

since 1.30, no longer needed

Parameters

string

$seqName

Returns

null|NextSequenceValue

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 3419 of file Database.php.

normalizeConditions()

Wikimedia\Rdbms\Database::normalizeConditions (   $conds,   $fname  )

finalprotected

Parameters

array | string	$conds
string	$fname

Returns

array

Since

1.31

Definition at line 2248 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\estimateRowCount(), and Wikimedia\Rdbms\DatabaseMysqlBase\estimateRowCount().

normalizeOptions()

Wikimedia\Rdbms\Database::normalizeOptions (   $options )

finalprotected

Parameters

string | array

$options

Returns

array Combination option/value map and boolean option list

Since

1.35

Definition at line 2341 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\makeUpdateOptionsArray(), and Wikimedia\Rdbms\Database\selectField().

normalizeRowArray()

Wikimedia\Rdbms\Database::normalizeRowArray ( array  $rowOrRows )

finalprotected

Parameters

array

$rowOrRows

A single (field => value) map or a list of such maps

Returns

array[] List of (field => value) maps

Since

1.35

Definition at line 2222 of file Database.php.

normalizeUpsertKeys()

Wikimedia\Rdbms\Database::normalizeUpsertKeys (   $uniqueKeys )

private

Parameters

string | string[] | string[][]

$uniqueKeys

Unique indexes (only one is allowed)

Returns

string[]|null List of columns that defines a single unique index, or null for a legacy fallback to plain insert.

Since

1.35

Definition at line 2308 of file Database.php.

normalizeUpsertParams()

Wikimedia\Rdbms\Database::normalizeUpsertParams (   $uniqueKeys, &  $rows  )

finalprotected

Validate and normalize parameters to upsert() or replace()

Parameters

string | string[] | string[][]	$uniqueKeys	Unique indexes (only one is allowed)
array[]	&$rows	The row array, which will be replaced with a normalized version.

Returns

string[]|null List of columns that defines a single unique index, or null for a legacy fallback to plain insert.

Since

1.35

Definition at line 2273 of file Database.php.

numFields()

Wikimedia\Rdbms\Database::numFields

(

IResultWrapper

$res

)

Get the number of fields in a result object.

See also

https://www.php.net/mysql_num_fields

Deprecated:

since 1.37

Parameters

IResultWrapper

$res

A SQL result

Returns

int

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 888 of file Database.php.

References $res.

numRows()

Wikimedia\Rdbms\Database::numRows

(

$res

)

Get the number of rows in a query result.

Returns zero if the query did not return any rows or was a write query.

Deprecated:

since 1.37 use IResultWrapper::numRows()

Parameters

IResultWrapper | bool

$res

A SQL result

Returns

int

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 880 of file Database.php.

References $res.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\estimateRowCount(), Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\DatabasePostgres\roleExists(), and Wikimedia\Rdbms\DatabasePostgres\schemaExists().

onAtomicSectionCancel()

Wikimedia\Rdbms\Database::onAtomicSectionCancel ( callable  $callback,   $fname = __METHOD__  )

final

Run a callback when the atomic section is cancelled.

The callback is run just after the current atomic section, any outer atomic section, or the whole transaction is rolled back.

An error is thrown if no atomic section is pending. The atomic section need not have been created with the ATOMIC_CANCELABLE flag.

Queries in the function may be running in the context of an outer transaction or may be running in AUTOCOMMIT mode. The callback should use atomic sections if necessary.

Note

do not assume that other IDatabase instances will be AUTOCOMMIT mode

The callback takes the following arguments:

• IDatabase::TRIGGER_CANCEL or IDatabase::TRIGGER_ROLLBACK
• This IDatabase instance

Parameters

callable	$callback
string	$fname	Caller name

Since

1.34

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4177 of file Database.php.

onTransactionCommitOrIdle()

Wikimedia\Rdbms\Database::onTransactionCommitOrIdle ( callable  $callback,   $fname = __METHOD__  )

final

Run a callback when the current transaction commits or now if there is none.

If there is a transaction and it is rolled back, then the callback is cancelled.

When transaction round mode (DBO_TRX) is set, the callback will run at the end of the round, just after all peer transactions COMMIT. If the transaction round is rolled back, then the callback is cancelled.

This IDatabase instance will start off in auto-commit mode when the callback starts. The use of other IDatabase handles from the callback should be avoided unless they are known to be in auto-commit mode. Callbacks that create transactions via begin() or startAtomic() must have matching calls to commit()/endAtomic().

Use this method only for the following purposes:

• (a) RDBMS updates, prone to lock timeouts/deadlocks, that do not require atomicity with respect to the updates in the current transaction (if any)
• (b) Purges to lightweight cache services due to RDBMS updates
• (c) Updates to secondary DBs/stores that must only commit once the updates in the current transaction (if any) are committed (e.g. insert user account row to DB1, then, initialize corresponding LDAP account)

The callback takes the following arguments:

• How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE)
• This IDatabase instance (since 1.32)

Callbacks will execute in the order they were enqueued.

Parameters

callable	$callback
string	$fname	Caller name

Exceptions

DBError

If an error occurs, {

See also

query}

Exceptions

Exception

If the callback runs immediately and an error occurs in it

Since

1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4120 of file Database.php.

onTransactionIdle()

Wikimedia\Rdbms\Database::onTransactionIdle ( callable  $callback,   $fname = __METHOD__  )

final

Alias for onTransactionCommitOrIdle() for backwards-compatibility.

Parameters

callable	$callback
string	$fname

Since

1.20

Deprecated:

Since 1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4143 of file Database.php.

onTransactionPreCommitOrIdle()

Wikimedia\Rdbms\Database::onTransactionPreCommitOrIdle ( callable  $callback,   $fname = __METHOD__  )

final

Run a callback before the current transaction commits or now if there is none.

If there is a transaction and it is rolled back, then the callback is cancelled.

When transaction round mode (DBO_TRX) is set, the callback will run at the end of the round, just after all peer transactions COMMIT. If the transaction round is rolled back, then the callback is cancelled.

If there is no current transaction, one will be created to wrap the callback. Callbacks cannot use begin()/commit() to manage transactions. The use of other IDatabase handles from the callback should be avoided.

Use this method only for the following purposes:

• a) RDBMS updates, prone to lock timeouts/deadlocks, that require atomicity with respect to the updates in the current transaction (if any)
• b) Purges to lightweight cache services due to RDBMS updates

The callback takes the one argument:

• This IDatabase instance (since 1.32)

Callbacks will execute in the order they were enqueued.

Parameters

callable	$callback
string	$fname	Caller name

Exceptions

DBError

If an error occurs, {

See also

query}

Exceptions

Exception

If the callback runs immediately and an error occurs in it

Since

1.22

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4147 of file Database.php.

onTransactionResolution()

Wikimedia\Rdbms\Database::onTransactionResolution ( callable  $callback,   $fname = __METHOD__  )

final

Run a callback when the current transaction commits or rolls back.

An error is thrown if no transaction is pending.

When transaction round mode (DBO_TRX) is set, the callback will run at the end of the round, just after all peer transactions COMMIT/ROLLBACK.

This IDatabase instance will start off in auto-commit mode when the callback starts. The use of other IDatabase handles from the callback should be avoided unless they are known to be in auto-commit mode. Callbacks that create transactions via begin() or startAtomic() must have matching calls to commit()/endAtomic().

Use this method only for the following purposes:

• (a) Release of cooperative locks on resources
• (b) Cancellation of in-proccess deferred tasks

The callback takes the following arguments:

• How the current atomic section (if any) or overall transaction (otherwise) ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK)
• This IDatabase instance (since 1.32)

Callbacks will execute in the order they were enqueued.

Note

Use onAtomicSectionCancel() to take action as soon as an atomic section is cancelled

Parameters

callable	$callback
string	$fname	Caller name

Exceptions

DBError

If an error occurs, {

See also

query}

Exceptions

Exception

If the callback runs immediately and an error occurs in it

Since

1.28

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4113 of file Database.php.

open()

Wikimedia\Rdbms\Database::open (   $server,   $user,   $password,   $db,   $schema,   $tablePrefix  )

abstractprotected

Open a new connection to the database (closing any existing one)

Parameters

string | null

$server

Server host/address and optional port {

See also

connectionParams}

Parameters

string | null

$user

User name {

See also

connectionParams}

Parameters

string | null

$password

User password {

See also

connectionParams}

Parameters

string | null	$db	Database name
string | null	$schema	Database schema name
string	$tablePrefix	Table prefix

Exceptions

DBConnectionError

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Referenced by Wikimedia\Rdbms\Database\doInitConnection().

pendingWriteAndCallbackCallers()

Wikimedia\Rdbms\Database::pendingWriteAndCallbackCallers

(

)

List the methods that have write queries or callbacks for the current transaction.

Access: internal

This method should not be used outside of Database/LoadBalancer

Returns

string[]

Since

1.32

Definition at line 792 of file Database.php.

References Wikimedia\Rdbms\Database\pendingWriteCallers().

Referenced by Wikimedia\Rdbms\Database\close().

pendingWriteCallers()

Wikimedia\Rdbms\Database::pendingWriteCallers

(

)

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

Returns

array

Since

1.27

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 776 of file Database.php.

References Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\Database\pendingWriteAndCallbackCallers().

pendingWriteQueryDuration()

Wikimedia\Rdbms\Database::pendingWriteQueryDuration

(

$type = self::ESTIMATE_TOTAL

)

Get the time spend running write queries for this transaction.

High values could be due to scanning, updates, locking, and such.

Parameters

string

$type

IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL]

Returns

float|bool Returns false if not transaction is active

Since

1.26

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 744 of file Database.php.

References Wikimedia\Rdbms\Database\$trxWriteDuration, $type, Wikimedia\Rdbms\Database\pingAndCalculateLastTrxApplyTime(), and Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\Database\handleSessionLossPreconnect().

pendingWriteRowsAffected()

Wikimedia\Rdbms\Database::pendingWriteRowsAffected

(

)

Get the number of affected rows from pending write queries.

Returns

int

Since

1.30

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 780 of file Database.php.

References Wikimedia\Rdbms\Database\$trxWriteAffectedRows.

ping()

Wikimedia\Rdbms\Database::ping

(

&

$rtt = null

)

Ping the server and try to reconnect if it there is no connection.

Parameters

float | null

&$rtt

Value to store the estimated RTT [optional]

Returns

bool Success or failure

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5112 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\pingAndCalculateLastTrxApplyTime().

pingAndCalculateLastTrxApplyTime()

Wikimedia\Rdbms\Database::pingAndCalculateLastTrxApplyTime ( )

private

Returns

float Time to apply writes to replicas based on trxWrite* fields

Definition at line 762 of file Database.php.

References Wikimedia\Rdbms\Database\$trxWriteAdjQueryCount, and Wikimedia\Rdbms\Database\ping().

Referenced by Wikimedia\Rdbms\Database\pendingWriteQueryDuration().

preCommitCallbacksPending()

Wikimedia\Rdbms\Database::preCommitCallbacksPending

(

)

Returns

bool Whether there is a transaction open with pre-commit callbacks pending

Since

1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 725 of file Database.php.

References Wikimedia\Rdbms\Database\$trxPreCommitOrIdleCallbacks, and Wikimedia\Rdbms\Database\trxLevel().

prependDatabaseOrSchema()

Wikimedia\Rdbms\Database::prependDatabaseOrSchema (   $namespace,   $relation,   $format  )

private

Parameters

string | null	$namespace	Database or schema
string	$relation	Name of table, view, sequence, etc...
string	$format	One of (raw, quoted)

Returns

string Relation name with quoted and merged $namespace as needed

Definition at line 3115 of file Database.php.

primaryPosWait()

Wikimedia\Rdbms\Database::primaryPosWait	(	DBPrimaryPos	$pos,
			$timeout
	)

Wait for the replica DB to catch up to a given primary DB position.Note that this does not start any new transactions. If any existing transaction is flushed, and this is called, then queries will reflect the point the DB was synced up to (on success) without interference from REPEATABLE-READ snapshots.

Parameters

DBPrimaryPos	$pos
int	$timeout	The maximum number of seconds to wait for synchronisation

Returns

int|null Zero if the replica DB was past that position already, greater than zero if we waited for some period of time, less than zero if it timed out, and null on error

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.37

Since

1.37

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 4069 of file Database.php.

qualifiedTableComponents()

Wikimedia\Rdbms\Database::qualifiedTableComponents (   $name )

protected

Get the table components needed for a query given the currently selected database.

Parameters

string

$name

Table name in the form of db.schema.table, db.table, or table

Returns

array (DB name or "" for default, schema name, table prefix, table name)

Definition at line 3075 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\tableExists().

query()

Wikimedia\Rdbms\Database::query	(		$sql,
			$fname = __METHOD__,
			$flags = self::QUERY_NORMAL
	)

Run an SQL query and return the result.

If a connection loss is detected, then an attempt to reconnect will be made. For queries that involve no larger transactions or locks, they will be re-issued for convenience, provided the connection was re-established.

In new code, the query wrappers select(), insert(), update(), delete(), etc. should be used where possible, since they give much better DBMS independence and automatically quote or validate user input in a variety of contexts. This function is generally only useful for queries which are explicitly DBMS-dependent and are unsupported by the query wrappers, such as CREATE TABLE.

However, the query wrappers themselves should call this function.

Parameters

string	$sql	SQL query
string	$fname	Name of the calling function, for profiling/SHOW PROCESSLIST comment (you can use METHOD or add some extra info)
int	$flags	Bit field of IDatabase::QUERY_* constants. Note that suppression of errors is best handled by try/catch rather than using one of these flags.

Returns

bool|IResultWrapper True for a successful write query, IResultWrapper object for a successful read query, or false on failure if QUERY_SILENCE_ERRORS is set.

Exceptions

DBQueryError	If the query is issued, fails, and QUERY_SILENCE_ERRORS is not set.
DBExpectedError	If the query is not, and cannot, be issued yet (non-DBQueryError)
DBError	If the query is inherently not allowed (non-DBExpectedError)

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 1316 of file Database.php.

References Wikimedia\Rdbms\Database\$flags, Wikimedia\Rdbms\Database\assertQueryIsCurrentlyAllowed(), Wikimedia\Rdbms\Database\executeQuery(), Wikimedia\Rdbms\Database\fieldHasBit(), and Wikimedia\Rdbms\Database\reportQueryError().

Referenced by Wikimedia\Rdbms\DatabaseSqlite\attachDatabase(), SqliteMaintenance\backup(), Wikimedia\Rdbms\DatabasePostgres\constraintExists(), Wikimedia\Rdbms\DatabasePostgres\currentSequenceValue(), Wikimedia\Rdbms\DatabaseMysqlBase\deleteJoin(), Wikimedia\Rdbms\DatabaseSqlite\doBegin(), Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting(), Wikimedia\Rdbms\DatabasePostgres\doInsertSelectNative(), Wikimedia\Rdbms\DatabaseMysqlBase\doLock(), Wikimedia\Rdbms\DatabasePostgres\doLock(), Wikimedia\Rdbms\DatabaseMysqlBase\doLockIsFree(), Wikimedia\Rdbms\DatabasePostgres\doLockIsFree(), Wikimedia\Rdbms\DatabaseMysqlBase\doLockTables(), Wikimedia\Rdbms\DatabasePostgres\doLockTables(), Wikimedia\Rdbms\DatabaseMysqlBase\doReplace(), Wikimedia\Rdbms\DatabaseSqlite\doReplace(), Wikimedia\Rdbms\DatabasePostgres\doTruncate(), Wikimedia\Rdbms\DatabaseSqlite\doTruncate(), Wikimedia\Rdbms\DatabaseMysqlBase\doUnlock(), Wikimedia\Rdbms\DatabasePostgres\doUnlock(), Wikimedia\Rdbms\DatabaseMysqlBase\doUnlockTables(), Wikimedia\Rdbms\DatabaseMysqlBase\doUpsert(), Wikimedia\Rdbms\DatabaseSqlite\dropTable(), Wikimedia\Rdbms\DatabaseMysqlBase\duplicateTableStructure(), Wikimedia\Rdbms\DatabasePostgres\duplicateTableStructure(), Wikimedia\Rdbms\DatabaseSqlite\duplicateTableStructure(), Wikimedia\Rdbms\DatabaseMysqlBase\fetchSecondsSinceHeartbeat(), Wikimedia\Rdbms\DatabaseMysqlBase\fieldInfo(), Wikimedia\Rdbms\DatabaseSqlite\fieldInfo(), Wikimedia\Rdbms\PostgresField\fromText(), Wikimedia\Rdbms\DatabasePostgres\getCoreSchemas(), Wikimedia\Rdbms\DatabasePostgres\getCurrentSchema(), Wikimedia\Rdbms\DatabaseMysqlBase\getLagFromSlaveStatus(), Wikimedia\Rdbms\DatabaseMysqlBase\getMysqlStatus(), Wikimedia\Rdbms\DatabasePostgres\getSchemas(), Wikimedia\Rdbms\DatabasePostgres\getSearchPath(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerGTIDs(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerId(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerRoleStatus(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerUUID(), Wikimedia\Rdbms\DatabasePostgres\indexAttributes(), Wikimedia\Rdbms\DatabaseMysqlBase\indexInfo(), Wikimedia\Rdbms\DatabasePostgres\indexInfo(), Wikimedia\Rdbms\DatabaseSqlite\indexInfo(), Wikimedia\Rdbms\DatabasePostgres\indexUnique(), Wikimedia\Rdbms\DatabasePostgres\insertId(), SqliteMaintenance\integrityCheck(), Wikimedia\Rdbms\DatabasePostgres\listTables(), Wikimedia\Rdbms\DatabaseMysqlBase\listTables(), Wikimedia\Rdbms\DatabaseSqlite\listTables(), Wikimedia\Rdbms\DatabaseMysqlBase\listViews(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), Wikimedia\Rdbms\DatabasePostgres\open(), Wikimedia\Rdbms\DatabaseSqlite\open(), Wikimedia\Rdbms\DatabaseMysqlBase\primaryPosWait(), Wikimedia\Rdbms\DatabasePostgres\relationExists(), Wikimedia\Rdbms\DatabasePostgres\roleExists(), Wikimedia\Rdbms\DatabasePostgres\schemaExists(), Wikimedia\Rdbms\DatabaseMysqlBase\serverIsReadOnly(), Wikimedia\Rdbms\DatabasePostgres\serverIsReadOnly(), Wikimedia\Rdbms\DatabaseMysqlBase\setBigSelects(), Wikimedia\Rdbms\DatabasePostgres\setSearchPath(), Wikimedia\Rdbms\DatabaseMysqlBase\setSessionOptions(), Wikimedia\Rdbms\DatabaseMysqlBase\tableExists(), Wikimedia\Rdbms\DatabaseSqlite\tableExists(), Wikimedia\Rdbms\DatabasePostgres\textFieldSize(), Wikimedia\Rdbms\DatabasePostgres\triggerExists(), SqliteMaintenance\vacuum(), and Wikimedia\Rdbms\DatabaseMysqlBase\wasKnownStatementRollbackError().

reassignCallbacksForSection()

Wikimedia\Rdbms\Database::reassignCallbacksForSection ( AtomicSectionIdentifier  $old, AtomicSectionIdentifier  $new  )

private

Hoist callback ownership for callbacks in a section to a parent section.

All callbacks should have an owner that is present in trxAtomicLevels.

Parameters

AtomicSectionIdentifier	$old
AtomicSectionIdentifier	$new

Definition at line 4203 of file Database.php.

registerTempWrites()

Wikimedia\Rdbms\Database::registerTempWrites (   $ret, array  $changes  )

protected

Parameters

IResultWrapper | bool	$ret
array[]	$changes	List of change n-tuples with from getTempWrites()

Definition at line 1276 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery().

relationSchemaQualifier()

Wikimedia\Rdbms\Database::relationSchemaQualifier ( )

protected

Stability: stable

to override

Returns

string Schema to use to qualify relations in queries

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 655 of file Database.php.

References Wikimedia\Rdbms\Database\dbSchema().

replace()

Wikimedia\Rdbms\Database::replace	(		$table,
			$uniqueKeys,
			$rows,
			$fname = __METHOD__
	)

Insert row(s) into a table, deleting all conflicting rows beforehand.

Note some important implications of the deletion semantics:

• If the table has an AUTOINCREMENT column and $rows omit that column, then any conflicting existing rows will be replaced with newer having higher values for that column, even if nothing else changed.
• There might be worse contention than upsert() due to the use of gap-locking. This does not apply to RDBMS types that use predicate locking nor those that just lock the whole table or databases anyway.

Parameters

string	$table	The table name
string | string[] | string[][]	$uniqueKeys	Column name or non-empty list of column name lists that define all applicable unique keys on the table. There must only be one such key. Each unique key on the table is "applicable" unless either: It involves an AUTOINCREMENT column for which no values are assigned in $rows It involves a UUID column for which newly generated UUIDs are assigned in $rows
array | array[]	$rows	Row(s) to insert, in the form of either: A string-keyed map of (column name => value) defining a new row. Values are treated as literals and quoted appropriately; null is interpreted as NULL. Columns belonging to a key in $uniqueKeys must be defined here and non-null. An integer-keyed list of such string-keyed maps, defining a list of new rows. The keys in each map must be identical to each other and in the same order. The rows must not collide with each other.
string	$fname	Calling function name (use METHOD) for logs/profiling

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3453 of file Database.php.

replaceLostConnection()

Wikimedia\Rdbms\Database::replaceLostConnection (   $fname )

protected

Close any existing (dead) database connection and open a new connection.

Parameters

string

$fname

Returns

bool True if new connection is opened successfully, false if error

Definition at line 5137 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

replaceVars()

Wikimedia\Rdbms\Database::replaceVars (   $ins )

protected

Database-independent variable replacement.

Replaces a set of variables in an SQL statement with their contents as given by $this->getSchemaVars().

Supports '{$var}' {$var} and / $var / (without the spaces) style variables.

• '{$var}' should be used for text and is passed through the database's addQuotes method.
• {$var} should be used for identifiers (e.g. table and database names). It is passed through the database's addIdentifierQuotes method which can be overridden if the database uses something other than backticks.
• / *_* / or / $wgDBprefix / passes the name that follows through the database's tableName method.
• / i / passes the name that follows through the database's indexName method.
• In all other cases, / $var / is left unencoded. Except for table options, its use should be avoided. In 1.24 and older, string encoding was applied.

Stability: stable

to override

Parameters

string

$ins

SQL statement to replace variables in

Returns

string The new SQL statement with variables replaced

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5472 of file Database.php.

reportQueryError()

Wikimedia\Rdbms\Database::reportQueryError	(		$error,
			$errno,
			$sql,
			$fname,
			$ignore = false
	)

Report a query error.

Log the error, and if neither the object ignore flag nor the $ignoreErrors flag is set, throw a DBQueryError.

Parameters

string	$error
int	$errno
string	$sql
string	$fname
bool	$ignore

Exceptions

DBQueryError

Definition at line 1764 of file Database.php.

References Wikimedia\Rdbms\Database\getQueryExceptionAndLog().

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\doSelectDomain(), and Wikimedia\Rdbms\Database\query().

restoreErrorHandler()

Wikimedia\Rdbms\Database::restoreErrorHandler ( )

protected

Restore the previous error handler and return the last PHP error for this DB.

Returns

bool|string

Definition at line 938 of file Database.php.

References Wikimedia\Rdbms\Database\getLastPHPError().

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabasePostgres\open().

restoreFlags()

Wikimedia\Rdbms\Database::restoreFlags

(

$state = self::RESTORE_PRIOR

)

Restore the flags to their prior state before the last setFlag/clearFlag call.

Parameters

string

$state

IDatabase::RESTORE_* constant. [default: RESTORE_PRIOR]

Since

1.28

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 851 of file Database.php.

Referenced by Wikimedia\Rdbms\LoadBalancer\undoTransactionRoundFlags().

rollback()

Wikimedia\Rdbms\Database::rollback (   $fname = __METHOD__,   $flush = self::FLUSHING_ONE  )

final

Rollback a transaction previously started using begin()

Only call this from code with outer transaction scope. See https://www.mediawiki.org/wiki/Database_transactions for details. Nesting of transactions is not supported. If a serious unexpected error occurs, throwing an Exception is preferable, using a pre-installed error handler to trigger rollback (in any case, failure to issue COMMIT will cause rollback server-side).

Query, connection, and onTransaction* callback errors will be suppressed and logged.

Parameters

string	$fname	Calling function name
string	$flush	Flush flag, set to a situationally valid IDatabase::FLUSHING_* constant to disable warnings about calling rollback when no transaction is in progress. This will silently break any ongoing explicit transaction. Only set the flush flag if you are sure that it is safe to ignore these warnings in your context.

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.23 Added $flush parameter

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4955 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\close().

runOnAtomicSectionCancelCallbacks()

Wikimedia\Rdbms\Database::runOnAtomicSectionCancelCallbacks (   $trigger, array  $sectionIds  )

private

Consume and run any relevant "on atomic section cancel" callbacks for the active transaction.

Parameters

int	$trigger	IDatabase::TRIGGER_* constant
AtomicSectionIdentifier[]	$sectionIds	IDs of the sections that where just cancelled

Exceptions

Throwable

Any exception thrown by a callback

Definition at line 4411 of file Database.php.

runOnTransactionIdleCallbacks()

Wikimedia\Rdbms\Database::runOnTransactionIdleCallbacks	(		$trigger,
		array &	$errors = []
	)

Consume and run any "on transaction idle/resolution" callbacks.

Access: internal

This method should not be used outside of Database/LoadBalancer

Since

1.20

Parameters

int	$trigger	IDatabase::TRIGGER_* constant
DBError[]	&$errors	DB exceptions caught [returned]

Returns

int Number of callbacks attempted

Exceptions

DBUnexpectedError
Throwable	Any non-DBError exception thrown by a callback

Definition at line 4316 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\handleSessionLossPostconnect(), and Wikimedia\Rdbms\LoadBalancer\runPrimaryTransactionIdleCallbacks().

runOnTransactionPreCommitCallbacks()

Wikimedia\Rdbms\Database::runOnTransactionPreCommitCallbacks

(

)

Consume and run any "on transaction pre-commit" callbacks.

Access: internal

This method should not be used outside of Database/LoadBalancer

Since

1.22

Returns

int Number of callbacks attempted

Exceptions

Throwable

Any exception thrown by a callback

Definition at line 4381 of file Database.php.

Referenced by Wikimedia\Rdbms\LoadBalancer\finalizePrimaryChanges().

runTransactionListenerCallbacks()

Wikimedia\Rdbms\Database::runTransactionListenerCallbacks	(		$trigger,
		array &	$errors = []
	)

Actually run any "transaction listener" callbacks.

Access: internal

This method should not be used outside of Database/LoadBalancer

Since

1.20

Parameters

int	$trigger	IDatabase::TRIGGER_* constant
DBError[]	&$errors	DB exceptions caught [returned]

Exceptions

Throwable

Any non-DBError exception thrown by a callback

Definition at line 4446 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\handleSessionLossPostconnect(), and Wikimedia\Rdbms\LoadBalancer\runPrimaryTransactionListenerCallbacks().

runTransactionPostCommitCallbacks()

Wikimedia\Rdbms\Database::runTransactionPostCommitCallbacks ( )

private

Handle "on transaction idle/resolution" and "transaction listener" callbacks post-COMMIT.

Exceptions

DBError	The first DBError exception thrown by a callback
Throwable	Any non-DBError exception thrown by a callback

Definition at line 4469 of file Database.php.

runTransactionPostRollbackCallbacks()

Wikimedia\Rdbms\Database::runTransactionPostRollbackCallbacks ( )

private

Handle "on transaction idle/resolution" and "transaction listener" callbacks post-ROLLBACK.

This will suppress and log any DBError exceptions

Exceptions

Throwable

Any non-DBError exception thrown by a callback

Definition at line 4486 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\close().

select()

Wikimedia\Rdbms\Database::select	(		$table,
			$vars,
			$conds = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

Execute a SELECT query constructed using the various parameters provided.

Parameters

string | array

$table

Table name(s)

May be either an array of table names, or a single string holding a table name. If an array is given, table aliases can be specified, for example:

[ 'a' => 'user' ]

This includes the user table in the query, with the alias "a" available for use in field names (e.g. a.user_name).

A derived table, defined by the result of selectSQLText(), requires an alias key and a Subquery instance value which wraps the SQL query, for example:

[ 'c' => new Subquery( 'SELECT ...' ) ]

Joins using parentheses for grouping (since MediaWiki 1.31) may be constructed using nested arrays. For example,

[ 'tableA', 'nestedB' => [ 'tableB', 'b2' => 'tableB2' ] ]

along with $join_conds like

[ 'b2' => [ 'JOIN', 'b_id = b2_id' ], 'nestedB' => [ 'LEFT JOIN', 'b_a = a_id' ] ]

will produce SQL something like

FROM tableA LEFT JOIN (tableB JOIN tableB2 AS b2 ON (b_id = b2_id)) ON (b_a = a_id)

All of the table names given here are automatically run through Database::tableName(), which causes the table prefix (if any) to be added, and various other table name mappings to be performed.

Do not use untrusted user input as a table name. Alias names should not have characters outside of the Basic multilingual plane.

Parameters

string | array

$vars

Field name(s)

May be either a field name or an array of field names. The field names can be complete fragments of SQL, for direct inclusion into the SELECT query. If an array is given, field aliases can be specified, for example:

[ 'maxrev' => 'MAX(rev_id)' ]

This includes an expression with the alias "maxrev" in the query.

If an expression is given, care must be taken to ensure that it is DBMS-independent.

Untrusted user input must not be passed to this parameter.

Parameters

string | array

$conds

May be either a string containing a single condition, or an array of conditions. If an array is given, the conditions constructed from each element are combined with AND.

Array elements may take one of two forms:

• Elements with a numeric key are interpreted as raw SQL fragments.
• Elements with a string key are interpreted as equality conditions, where the key is the field name.
  • If the value of such an array element is a scalar (such as a string), it will be treated as data and thus quoted appropriately. If it is null, an IS NULL clause will be added.
  • If the value is an array, an IN (...) clause will be constructed from its non-null elements, and an IS NULL clause will be added if null is present, such that the field may match any of the elements in the array. The non-null elements will be quoted.

Note that expressions are often DBMS-dependent in their syntax. DBMS-independent wrappers are provided for constructing several types of expression commonly used in condition queries. See:

• IDatabase::buildLike()
• IDatabase::conditional()

Untrusted user input is safe in the values of string keys, however untrusted input must not be used in the array key names or in the values of numeric keys. Escaping of untrusted input used in values of numeric keys should be done via IDatabase::addQuotes()

Use an empty array, string, or IDatabase::ALL_ROWS to select all rows.

You can put simple join conditions here, but this is strongly discouraged. Instead of

// $conds...
'rev_actor = actor_id',

use (see below for $join_conds):

// $join_conds...
'actor' => [ 'JOIN', 'rev_actor = actor_id' ],

Parameters

string	$fname	Caller function name
string | array	$options	Query options

Optional: Array of query options. Boolean options are specified by including them in the array as a string value with a numeric key, for example:

[ 'FOR UPDATE' ]

The supported options are:

• OFFSET: Skip this many rows at the start of the result set. OFFSET with LIMIT can theoretically be used for paging through a result set, but this is discouraged for performance reasons.
• LIMIT: Integer: return at most this many rows. The rows are sorted and then the first rows are taken until the limit is reached. LIMIT is applied to a result set after OFFSET.
• LOCK IN SHARE MODE: Boolean: lock the returned rows so that they can't be changed until the next COMMIT. Cannot be used with aggregate functions (COUNT, MAX, etc., but also DISTINCT).
• FOR UPDATE: Boolean: lock the returned rows so that they can't be changed nor read with LOCK IN SHARE MODE until the next COMMIT. Cannot be used with aggregate functions (COUNT, MAX, etc., but also DISTINCT).
• DISTINCT: Boolean: return only unique result rows.
• GROUP BY: May be either an SQL fragment string naming a field or expression to group by, or an array of such SQL fragments.
• HAVING: May be either an string containing a HAVING clause or an array of conditions building the HAVING clause. If an array is given, the conditions constructed from each element are combined with AND.
• ORDER BY: May be either an SQL fragment giving a field name or expression to order by, or an array of such SQL fragments.
• USE INDEX: This may be either a string giving the index name to use for the query, or an array. If it is an associative array, each key gives the table name (or alias), each value gives the index name to use for that table. All strings are SQL fragments and so should be validated by the caller.
• IGNORE INDEX: This may be either be a string giving an index name to ignore for the query, or an array. If it is an associative array, each key gives the table name (or alias), each value gives the index name to ignore for that table. All strings are SQL fragments and so should be validated by the caller.
• EXPLAIN: In MySQL, this causes an EXPLAIN SELECT query to be run, instead of SELECT.

And also the following boolean MySQL extensions, see the MySQL manual for documentation:

• STRAIGHT_JOIN
• SQL_BIG_RESULT
• SQL_BUFFER_RESULT
• SQL_SMALL_RESULT
• SQL_CALC_FOUND_ROWS

Parameters

string | array

$join_conds

Join conditions

Optional associative array of table-specific join conditions. Simple conditions can also be specified in the regular $conds, but this is strongly discouraged in favor of the more explicit syntax here.

The key of the array contains the table name or alias. The value is an array with two elements, numbered 0 and 1. The first gives the type of join, the second is the same as the $conds parameter. Thus it can be an SQL fragment, or an array where the string keys are equality and the numeric keys are SQL fragments all AND'd together. For example:

[ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ]

Returns

IResultWrapper Resulting rows

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2007 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\estimateRowCount(), Wikimedia\Rdbms\DatabaseMysqlBase\estimateRowCount(), and Wikimedia\Rdbms\Database\selectField().

selectDB()

Wikimedia\Rdbms\Database::selectDB (   $db )

final

Change the current database.

This should only be called by a load balancer or if the handle is not attached to one

Parameters

string

$db

Returns

bool True unless an exception was thrown

Exceptions

DBConnectionError	If databasesAreIndependent() is true and connection change fails
DBError	On query error or if database changes are disallowed

Deprecated:

Since 1.32 Use selectDomain() instead

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2967 of file Database.php.

selectDomain()

Wikimedia\Rdbms\Database::selectDomain (   $domain )

final

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

This will throw an error for some database types if the database is unspecified

This should only be called by a load balancer or if the handle is not attached to one

Parameters

string | DatabaseDomain

$domain

Exceptions

DBConnectionError	If databasesAreIndependent() is true and connection change fails
DBError	On query error, if domain changes are disallowed, or the domain is invalid

Since

1.32

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2977 of file Database.php.

References Wikimedia\Rdbms\DatabaseDomain\newFromId().

selectField()

Wikimedia\Rdbms\Database::selectField	(		$table,
			$var,
			$cond = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

A SELECT wrapper which returns a single field from a single result row.

If no result rows are returned from the query, false is returned.

Parameters

string | array

$table

Table name. {

See also

select} for details.

Parameters

string | array

$var

The field name to select. This must be a valid SQL fragment: do not use unvalidated user input. Can be an array, but must contain exactly 1 element then. {

See also

select} for details.

Parameters

string | array

$cond

The condition array. {

See also

select} for details.

Parameters

string	$fname	The function name of the caller.
string | array	$options	The query options. {

See also

select} for details.

Parameters

string | array

$join_conds

The query join conditions. {

See also

select} for details.

Returns

mixed|false The value from the field, or false if nothing was found

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 1839 of file Database.php.

References $res, Wikimedia\Rdbms\Database\fetchRow(), Wikimedia\Rdbms\Database\normalizeOptions(), and Wikimedia\Rdbms\Database\select().

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\getServerVersion(), Wikimedia\Rdbms\DatabasePostgres\ruleExists(), and Wikimedia\Rdbms\DatabaseMysqlBase\setBigSelects().

selectFieldsOrOptionsAggregate()

Wikimedia\Rdbms\Database::selectFieldsOrOptionsAggregate (   $fields,   $options  )

private

Parameters

array | string	$fields
array | string	$options

Returns

bool

Definition at line 2194 of file Database.php.

selectFieldValues()

Wikimedia\Rdbms\Database::selectFieldValues	(		$table,
			$var,
			$cond = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

A SELECT wrapper which returns a list of single field values from result rows.

If no result rows are returned from the query, an empty array is returned.

Parameters

string | array

$table

Table name. {

See also

select} for details.

Parameters

string	$var	The field name to select. This must be a valid SQL fragment: do not use unvalidated user input.
string | array	$cond	The condition array. {

See also

select} for details.

Parameters

string	$fname	The function name of the caller.
string | array	$options	The query options. {

See also

select} for details.

Parameters

string | array

$join_conds

The query join conditions. {

See also

select} for details.

Returns

array The values from the field in the order they were returned from the DB

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.25

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 1864 of file Database.php.

selectOptionsIncludeLocking()

Wikimedia\Rdbms\Database::selectOptionsIncludeLocking (   $options )

private

Parameters

string | array

$options

Returns

bool

Definition at line 2178 of file Database.php.

selectRow()

Wikimedia\Rdbms\Database::selectRow	(		$table,
			$vars,
			$conds,
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

Wrapper to IDatabase::select() that only fetches one row (via LIMIT)

If the query returns no rows, false is returned.

This method is convenient for fetching a row based on a unique key condition.

Parameters

string | array	$table	Table name
string | array	$vars	Field names
string | array	$conds	Conditions
string	$fname	Caller function name
string | array	$options	Query options
array | string	$join_conds	Join conditions

Returns

stdClass|bool

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2106 of file Database.php.

References $res.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\getReplicationSafetyInfo(), and Wikimedia\Rdbms\DatabaseSqlite\indexUnique().

selectRowCount()

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

Get the number of rows in dataset.

This is useful when trying to do COUNT(*) but with a LIMIT for performance.

Takes the same arguments as IDatabase::select().

Since

1.27 Added $join_conds parameter

Parameters

string | string[]	$tables	Table name(s)
string	$var	Column for which NULL values are not counted [default "*"]
array | string	$conds	Filters on the table
string	$fname	Function name for profiling
array	$options	Options for select
array	$join_conds	Join conditions (since 1.27)

Returns

int Row count

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2145 of file Database.php.

References $res.

selectSQLText()

Wikimedia\Rdbms\Database::selectSQLText	(		$table,
			$vars,
			$conds = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

Take the same arguments as IDatabase::select() and return the SQL it would use.This can be useful for making UNION queries, where the SQL text of each query is needed. In general, however, callers outside of Database classes should just use select().

See also

IDatabase::select()

Parameters

string | array	$table	Table name
string | array	$vars	Field names
string | array	$conds	Conditions
string	$fname	Caller function name
string | array	$options	Query options
string | array	$join_conds	Join conditions

Returns

string SQL query string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 2019 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseSqlite\buildGroupConcatField().

serverIsReadOnly()

Wikimedia\Rdbms\Database::serverIsReadOnly

(

)

Returns

bool Whether the DB is marked as read-only server-side

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.28

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 4109 of file Database.php.

setBigSelects()

Wikimedia\Rdbms\Database::setBigSelects

(

$value = true

)

Allow or deny "big selects" for this session only.This is done by setting the sql_big_selects session variable.This is a MySQL-specific feature.

Parameters

bool | string

$value

True for allow, false for deny, or "default" to restore the initial value

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5792 of file Database.php.

setFlag()

Wikimedia\Rdbms\Database::setFlag	(		$flag,
			$remember = self::REMEMBER_NOTHING
	)

Set a flag for this connection.

Parameters

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

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 821 of file Database.php.

References Wikimedia\Rdbms\Database\$flags.

Referenced by Wikimedia\Rdbms\LoadBalancer\applyTransactionRoundFlags().

setIndexAliases()

Wikimedia\Rdbms\Database::setIndexAliases

(

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.

Parameters

string[]

$aliases

Since

1.31

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5830 of file Database.php.

setLBInfo()

Wikimedia\Rdbms\Database::setLBInfo	(		$nameOrArray,
			$value = null
	)

Set the entire array or a particular key of the managing load balancer info array.

Keys matching the IDatabase::LB_* constants are also used internally by subclasses

Parameters

array | string	$nameOrArray	The new array or the name of a key to set
array | null	$value	If $nameOrArray is a string, the new key value (null to unset)

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 671 of file Database.php.

Referenced by Wikimedia\Rdbms\LoadBalancer\applyTransactionRoundFlags(), and Wikimedia\Rdbms\LoadBalancer\undoTransactionRoundFlags().

setLogger()

Wikimedia\Rdbms\Database::setLogger

(

LoggerInterface

$logger

)

Set the PSR-3 logger interface to use for query logging.

(The logger interfaces for connection logging and error logging can be set with the constructor.)

Parameters

LoggerInterface

$logger

Definition at line 574 of file Database.php.

setSchemaVars()

Wikimedia\Rdbms\Database::setSchemaVars

(

$vars

)

Set schema variables to be used when streaming commands from SQL files or stdin.

Variables appear as SQL comments and are substituted by their corresponding values

Parameters

array | null

$vars

Map of (variable => value) or null to use the defaults

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5353 of file Database.php.

setSessionOptions()

Wikimedia\Rdbms\Database::setSessionOptions

(

array

$options

)

Override database's default behavior.$options include: 'connTimeout' : Set the connection timeout value in seconds. May be useful for very long batch queries such as full-wiki dumps, where a single query reads out over hours or days.

Parameters

array

$options

Returns

void

Exceptions

DBError

If an error occurs, {

See also

query}

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5316 of file Database.php.

setTableAliases()

Wikimedia\Rdbms\Database::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.For example, "user" can be converted to "myschema.mydbname.user" for convenience. Appearances like user, somedb.user, somedb.someschema.user will used literally.Calling this twice will completely clear any old table aliases. Also, note that callers are responsible for making sure the schemas and databases actually exist.

Parameters

array[]

$aliases

Map of (table => (dbname, schema, prefix) map)

Since

1.28

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 5822 of file Database.php.

setTransactionError()

Wikimedia\Rdbms\Database::setTransactionError ( Throwable  $trxError )

private

Mark the transaction as requiring rollback (STATUS_TRX_ERROR) due to an error.

Parameters

Throwable

$trxError

Definition at line 5872 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery().

setTransactionListener()

Wikimedia\Rdbms\Database::setTransactionListener (   $name, callable  $callback = null  )

final

Run a callback after each time any transaction commits or rolls back.

The callback takes two arguments:

• IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK
• This IDatabase object Callbacks must commit any transactions that they begin.

Registering a callback here will not affect writesOrCallbacks() pending.

Since callbacks from this or onTransactionCommitOrIdle() can start and end transactions, a single call to IDatabase::commit might trigger multiple runs of the listener callbacks.

Parameters

string	$name	Callback name
callable | null	$callback	Use null to unset a listener

Since

1.28

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4284 of file Database.php.

setTrxEndCallbackSuppression()

Wikimedia\Rdbms\Database::setTrxEndCallbackSuppression (   $suppress )

final

Whether to disable running of post-COMMIT/ROLLBACK callbacks.

Access: internal

This method should not be used outside of Database/LoadBalancer

Since

1.28

Parameters

bool

$suppress

Definition at line 4300 of file Database.php.

Referenced by Wikimedia\Rdbms\LoadBalancer\finalizePrimaryChanges(), and Wikimedia\Rdbms\LoadBalancer\runPrimaryTransactionIdleCallbacks().

sourceFile()

Wikimedia\Rdbms\Database::sourceFile	(		$filename,
		callable	$lineCallback = null,
		callable	$resultCallback = null,
			$fname = false,
		callable	$inputCallback = null
	)

Read and execute SQL commands from a file.

Returns true on success, error string or exception on failure (depending on object's error ignore settings).

Parameters

string	$filename	File name to open
callable | null	$lineCallback	Optional function called before reading each line
callable | null	$resultCallback	Optional function called for each MySQL result
bool | string	$fname	Calling function name or false if name should be generated dynamically using $filename
callable | null	$inputCallback	Optional function called for each complete line sent

Returns

bool|string

Exceptions

Exception

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 5319 of file Database.php.

sourceStream()

Wikimedia\Rdbms\Database::sourceStream	(		$fp,
		callable	$lineCallback = null,
		callable	$resultCallback = null,
			$fname = __METHOD__,
		callable	$inputCallback = null
	)

Read and execute commands from an open file handle.

Returns true on success, error string or exception on failure (depending on object's error ignore settings).

Parameters

resource	$fp	File handle
callable | null	$lineCallback	Optional function called before reading each query
callable | null	$resultCallback	Optional function called for each MySQL result
string	$fname	Calling function name
callable | null	$inputCallback	Optional function called for each complete query sent

Returns

bool|string

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 5357 of file Database.php.

References $line, and $res.

startAtomic()

Wikimedia\Rdbms\Database::startAtomic (   $fname = __METHOD__,   $cancelable = self::ATOMIC_NOT_CANCELABLE  )

final

Begin an atomic section of SQL statements.

Start an implicit transaction if no transaction is already active, set a savepoint (if $cancelable is ATOMIC_CANCELABLE), and track the given section name to enforce that the transaction is not committed prematurely. The end of the section must be signified exactly once, either by endAtomic() or cancelAtomic(). Sections can have have layers of inner sections (sub-sections), but all sections must be ended in order of innermost to outermost. Transactions cannot be started or committed until all atomic sections are closed.

ATOMIC_CANCELABLE is useful when the caller needs to handle specific failure cases by discarding the section's writes. This should not be used for failures when:

• upsert() could easily be used instead
• insert() with IGNORE could easily be used instead
• select() with FOR UPDATE could be checked before issuing writes instead
• The failure is from code that runs after the first write but doesn't need to
• The failures are from contention solvable via onTransactionPreCommitOrIdle()
• The failures are deadlocks; the RDBMs usually discard the whole transaction

Note

callers must use additional measures for situations involving two or more (peer) transactions (e.g. updating two database servers at once). The transaction and savepoint logic of this method only applies to this specific IDatabase instance.

Example usage:

// Start a transaction if there isn't one already
$dbw->startAtomic( __METHOD__ );
// Serialize these thread table updates
$dbw->select( 'thread', '1', [ 'td_id' => $tid ], __METHOD__, 'FOR UPDATE' );
// Add a new comment for the thread
$dbw->insert( 'comment', $row, __METHOD__ );
$cid = $db->insertId();
// Update thread reference to last comment
$dbw->update( 'thread', [ 'td_latest' => $cid ], [ 'td_id' => $tid ], __METHOD__ );
// Demark the end of this conceptual unit of updates
$dbw->endAtomic( __METHOD__ );

Example usage (atomic changes that might have to be discarded):

// Start a transaction if there isn't one already
$sectionId = $dbw->startAtomic( __METHOD__, $dbw::ATOMIC_CANCELABLE );
// Create new record metadata row
$dbw->insert( 'records', $row, __METHOD__ );
// Figure out where to store the data based on the new row's ID
$path = $recordDirectory . '/' . $dbw->insertId();
// Write the record data to the storage system
$status = $fileBackend->create( [ 'dst' => $path, 'content' => $data ] );
if ( $status->isOK() ) {
    // Try to cleanup files orphaned by transaction rollback
    $dbw->onTransactionResolution(
        function ( $type ) use ( $fileBackend, $path ) {
            if ( $type === IDatabase::TRIGGER_ROLLBACK ) {
                $fileBackend->delete( [ 'src' => $path ] );
            }
        },
        __METHOD__
    );
    // Demark the end of this conceptual unit of updates
    $dbw->endAtomic( __METHOD__ );
} else {
    // Discard these writes from the transaction (preserving prior writes)
    $dbw->cancelAtomic( __METHOD__, $sectionId );
}

Since

1.23

Parameters

string	$fname
string	$cancelable	Pass self::ATOMIC_CANCELABLE to use a savepoint and enable self::cancelAtomic() for this section.

Returns

AtomicSectionIdentifier section ID token

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 4559 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting(), and Wikimedia\Rdbms\DatabaseSqlite\doTruncate().

streamStatementEnd()

Wikimedia\Rdbms\Database::streamStatementEnd	(	&	$sql,
		&	$newLine
	)

Called by sourceStream() to check if we've reached a statement end.

Stability: stable

to override

Parameters

string	&$sql	SQL assembled so far
string	&$newLine	New line about to be added to $sql

Returns

bool Whether $newLine contains end of the statement

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabasePostgres.

Definition at line 5435 of file Database.php.

strencode()

Wikimedia\Rdbms\Database::strencode (   $s )

abstract

Wrapper for addslashes()

Stability: stable

to override

Parameters

string

$s

String to be slashed.

Returns

string Slashed string.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

strreplace()

Wikimedia\Rdbms\Database::strreplace	(		$orig,
			$old,
			$new
	)

Returns a SQL expression for simple string replacement (e.g.REPLACE() in mysql)

Parameters

string	$orig	Column to modify
string	$old	Column to seek
string	$new	Column to replace with

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3951 of file Database.php.

tableExists()

Wikimedia\Rdbms\Database::tableExists (   $table,   $fname = __METHOD__  )

abstract

Query whether a given table exists.

Parameters

string	$table
string	$fname

Returns

bool

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabaseSqlite.

tableLocksHaveTransactionScope()

Wikimedia\Rdbms\Database::tableLocksHaveTransactionScope

(

)

Checks if table locks acquired by lockTables() are transaction-bound in their scope.

Transaction-bound table locks will be released when the current transaction terminates. Table locks that are not bound to a transaction are not effected by BEGIN/COMMIT/ROLLBACK and will last until either lockTables()/unlockTables() is called or the TCP connection to the database is closed.

Returns

bool

Since

1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 5662 of file Database.php.

tableName()

Wikimedia\Rdbms\Database::tableName	(		$name,
			$format = 'quoted'
	)

Format a table name ready for use in constructing an SQL query.This does two important things: it quotes the table names to clean them up, and it adds a table prefix if only given a table name with no quotes.All functions of this object which require a table name call this function themselves. Pass the canonical name to such functions. This is only needed when calling query() directly.

Note

This function does not sanitize user input. It is not safe to use this function to escape user input.

Parameters

string	$name	Database table name
string	$format	One of: quoted - Automatically pass the table name through addIdentifierQuotes() so that it can be used in a query. raw - Do not add identifier quotes to the table name

Returns

string Full database name

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3017 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\deleteJoin(), Wikimedia\Rdbms\DatabaseMysqlBase\doLockTables(), Wikimedia\Rdbms\DatabaseMysqlBase\doReplace(), Wikimedia\Rdbms\DatabaseMysqlBase\doUpsert(), Wikimedia\Rdbms\DatabaseMysqlBase\fieldInfo(), Wikimedia\Rdbms\DatabaseMysqlBase\indexInfo(), and Wikimedia\Rdbms\Database\isPristineTemporaryTable().

tableNames()

Wikimedia\Rdbms\Database::tableNames

(

$tables

)

Fetch a number of table names into an array This is handy when you need to construct SQL for joins.

Example: list( $user, $watchlist ) = $dbr->tableNames( 'user', 'watchlist' ) ); $sql = "SELECT wl_namespace, wl_title FROM $watchlist, $user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Parameters

string

...$tables

Returns

array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 3126 of file Database.php.

tableNamesN()

Wikimedia\Rdbms\Database::tableNamesN

(

$tables

)

Fetch a number of table names into an zero-indexed numerical array This is handy when you need to construct SQL for joins.

Example: list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' ); $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Parameters

string

...$tables

Returns

array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 3136 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doTruncate().

tableNamesWithIndexClauseOrJOIN()

Wikimedia\Rdbms\Database::tableNamesWithIndexClauseOrJOIN (   $tables,   $use_index = [],   $ignore_index = [],   $join_conds = []  )

protected

Get the aliased table name clause for a FROM clause which might have a JOIN and/or USE INDEX or IGNORE INDEX clause.

Parameters

array	$tables	( [alias] => table )
array	$use_index	Same as for select()
array	$ignore_index	Same as for select()
array	$join_conds	Same as for select()

Returns

string

Definition at line 3222 of file Database.php.

tableNameWithAlias()

Wikimedia\Rdbms\Database::tableNameWithAlias (   $table,   $alias = false  )

protected

Get an aliased table name.

This returns strings like "tableName AS newTableName" for aliased tables and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables)

See also

Database::tableName()

Parameters

string | Subquery	$table	Table name or object with a 'sql' field
string | bool	$alias	Table alias (optional)

Returns

string SQL name for aliased table. Will not alias a table to its own name

Definition at line 3157 of file Database.php.

tablePrefix()

Wikimedia\Rdbms\Database::tablePrefix

(

$prefix = null

)

Get/set the table prefix.

Parameters

string | null

$prefix

The table prefix to set, or omitted to leave it unchanged

Returns

string The previous table prefix

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 615 of file Database.php.

textFieldSize()

Wikimedia\Rdbms\Database::textFieldSize	(		$table,
			$field
	)

Returns the size of a text field, or -1 for "unlimited".

Parameters

string	$table
string	$field

Returns

int

Stability: stable

to override

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3625 of file Database.php.

References $res.

timestamp()

Wikimedia\Rdbms\Database::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.The result is unquoted, and needs to be passed through addQuotes() before it can be included in raw SQL.

Parameters

string | int

$ts

Returns

string

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabasePostgres.

Definition at line 5089 of file Database.php.

References $t.

timestampOrNull()

Wikimedia\Rdbms\Database::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.

If NULL is input, it is passed through, allowing NULL values to be inserted into timestamp fields.

The result is unquoted, and needs to be passed through addQuotes() before it can be included in raw SQL.

Parameters

string | int | null

$ts

Returns

string|null

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5095 of file Database.php.

truncate()

Wikimedia\Rdbms\Database::truncate	(		$tables,
			$fname = __METHOD__
	)

Delete all data in a table(s) and reset any sequences owned by that table(s)

Parameters

string | string[]	$tables
string	$fname

Exceptions

DBError

If an error occurs

Since

1.35

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 5736 of file Database.php.

trxLevel()

Wikimedia\Rdbms\Database::trxLevel ( )

final

Gets the current transaction level.

Historically, transactions were allowed to be "nested". This is no longer supported, so this function really only returns a boolean.

Returns

int The previous value

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 599 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\beginIfImplied(), Wikimedia\Rdbms\Database\close(), Wikimedia\Rdbms\DatabasePostgres\determineCoreSchema(), Wikimedia\Rdbms\Database\executeQuery(), Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\Database\pendingWriteCallers(), Wikimedia\Rdbms\Database\pendingWriteQueryDuration(), Wikimedia\Rdbms\Database\preCommitCallbacksPending(), Wikimedia\Rdbms\LoadBalancer\runPrimaryTransactionIdleCallbacks(), Wikimedia\Rdbms\Database\trxTimestamp(), Wikimedia\Rdbms\Database\writesOrCallbacksPending(), and Wikimedia\Rdbms\Database\writesPending().

trxStatus()

Wikimedia\Rdbms\Database::trxStatus

(

)

Returns

int One of the STATUS_TRX_* class constants

Since

1.31

Definition at line 611 of file Database.php.

References Wikimedia\Rdbms\Database\$trxStatus.

Referenced by Wikimedia\Rdbms\Database\assertQueryIsCurrentlyAllowed().

trxTimestamp()

Wikimedia\Rdbms\Database::trxTimestamp

(

)

Get the UNIX timestamp of the time that the transaction was established.

This can be used to reason about the staleness of SELECT data in REPEATABLE-READ transaction isolation level. Callers can assume that if a view-snapshot isolation is used, then the data read by SQL queries is at least up to date to that point (possibly more up-to-date since the first SELECT defines the snapshot).

Returns

float|null Returns null if there is not active transaction

Since

1.25

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 603 of file Database.php.

References Wikimedia\Rdbms\Database\trxLevel(), and Wikimedia\Rdbms\Database\trxTimestamp().

Referenced by Wikimedia\Rdbms\Database\trxTimestamp().

unionConditionPermutations()

Wikimedia\Rdbms\Database::unionConditionPermutations	(		$table,
			$vars,
		array	$permute_conds,
			$extra_conds = '',
			$fname = __METHOD__,
			$options = [],
			$join_conds = []
	)

Construct a UNION query for permutations of conditions.

Databases sometimes have trouble with queries that have multiple values for multiple condition parameters combined with limits and ordering. This method constructs queries for the Cartesian product of the conditions and unions them all together.

See also

IDatabase::select()

Parameters

string | array	$table	Table name
string | array	$vars	Field names
array	$permute_conds	Conditions for the Cartesian product. Keys are field names, values are arrays of the possible values for that field.
string | array	$extra_conds	Additional conditions to include in the query.
string	$fname	Caller function name
string | array	$options	Query options. In addition to the options recognized by IDatabase::select(), the following may be used: NOTALL: Set to use UNION instead of UNION ALL. INNER ORDER BY: If specified and supported, subqueries will use this instead of ORDER BY.
string | array	$join_conds	Join conditions

Returns

string SQL query string.

Since

1.30

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3859 of file Database.php.

unionQueries()

Wikimedia\Rdbms\Database::unionQueries	(		$sqls,
			$all
	)

Construct a UNION query.This is used for providing overload point for other DB abstractions not compatible with the MySQL syntax.

Parameters

array	$sqls	SQL statements to combine
bool	$all	Either IDatabase::UNION_ALL or IDatabase::UNION_DISTINCT

Returns

string SQL fragment

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3853 of file Database.php.

unionSupportsOrderAndLimit()

Wikimedia\Rdbms\Database::unionSupportsOrderAndLimit

(

)

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

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3845 of file Database.php.

unlock()

Wikimedia\Rdbms\Database::unlock	(		$lockName,
			$method
	)

Release a lock.Named locks are not related to transactions

Parameters

string	$lockName	Name of lock to release
string	$method	Name of the calling method

Returns

bool Success

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 5594 of file Database.php.

unlockTables()

Wikimedia\Rdbms\Database::unlockTables (   $method )

final

Unlock all tables locked via lockTables()

If table locks are scoped to transactions, then locks might not be released until the transaction ends, which could happen after this method is called.

Parameters

string

$method

The caller

Returns

bool

Since

1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 5691 of file Database.php.

update()

Wikimedia\Rdbms\Database::update	(		$table,
			$set,
			$conds,
			$fname = __METHOD__,
			$options = []
	)

Update all rows in a table that match a given condition.

Parameters

string	$table	Table name
array	$set	Combination map/list where each string-keyed entry maps a column to a literal assigned value and each integer-keyed value is a SQL expression in the format of a column assignment within UPDATE...SET. The (column => value) entries are convenient due to automatic value quoting and conversion of null to NULL. The SQL assignment format is useful for updates like "column = column + X". All assignments have no defined execution order, so they should not depend on each other. Do not modify AUTOINCREMENT or UUID columns in assignments.
array | string	$conds	Condition in the format of IDatabase::select() conditions. In order to prevent possible performance or replication issues or damaging a data accidentally, an empty condition for 'update' queries isn't allowed. IDatabase::ALL_ROWS should be passed explicitely in order to update all rows.
string	$fname	Calling function name (use METHOD) for logs/profiling
string | array	$options	Combination map/list where each string-keyed entry maps a non-boolean option to the option parameters and each integer-keyed value is the name of a boolean option. Supported options are: IGNORE: Boolean: skip update of rows that would cause unique key conflicts. IDatabase::affectedRows() can be used to determine how many rows were updated.

Returns

bool Return true if no exception was thrown (deprecated since 1.33)

Exceptions

DBError

If an error occurs, {

See also

query}

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 2641 of file Database.php.

updateTrxWriteQueryTime()

Wikimedia\Rdbms\Database::updateTrxWriteQueryTime (   $sql,   $runtime,   $affected  )

private

Update the estimated run-time of a query, not counting large row lock times.

LoadBalancer can be set to rollback transactions that will create huge replication lag. It bases this estimate off of pendingWriteQueryDuration(). Certain simple queries, like inserting a row can take a long time due to row locking. This method uses some simple heuristics to discount those cases.

Parameters

string	$sql	A SQL write query
float	$runtime	Total runtime, including RTT
int	$affected	Affected row count

Definition at line 1569 of file Database.php.

References Wikimedia\Rdbms\Database\$SMALL_WRITE_ROWS, Wikimedia\Rdbms\Database\affectedRows(), and Wikimedia\Rdbms\Database\getQueryVerb().

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

upsert()

Wikimedia\Rdbms\Database::upsert	(		$table,
		array	$rows,
			$uniqueKeys,
		array	$set,
			$fname = __METHOD__
	)

Upsert the given row(s) into a table.

This updates any existing rows that conflict with the provided rows and inserts any of the provided rows that do not conflict with existing rows. Conflicts are determined by the provided unique indexes.

Parameters

string	$table	Table name
array | array[]	$rows	Row(s) to insert, in the form of either: A string-keyed map of (column name => value) defining a new row. Values are treated as literals and quoted appropriately; null is interpreted as NULL. Columns belonging to a key in $uniqueKeys must be defined here and non-null. An integer-keyed list of such string-keyed maps, defining a list of new rows. The keys in each map must be identical to each other and in the same order. The rows must not collide with each other.
string | string[] | string[][]	$uniqueKeys	Column name or non-empty list of column name lists that define all applicable unique keys on the table. There must only be one such key. Each unique key on the table is "applicable" unless either: It involves an AUTOINCREMENT column for which no values are assigned in $rows It involves a UUID column for which newly generated UUIDs are assigned in $rows Passing string[] to $uniqueKeys is deprecated.
array	$set	Combination map/list where each string-keyed entry maps a column to a literal assigned value and each integer-keyed value is a SQL assignment expression of the form "<unquoted alphanumeric column> = <SQL expression>". The (column => value) entries are convenient due to automatic value quoting and conversion of null to NULL. The SQL assignment entries are useful for updates like "column = column + X". All of the assignments have no defined execution order, so callers should make sure that they not depend on each other. Do not modify AUTOINCREMENT or UUID columns in assignments, even if they are just "secondary" unique keys.
string	$fname	Calling function name (use METHOD) for logs/profiling

Returns

bool Return true if no exception was thrown (deprecated since 1.33)

Exceptions

DBError

If an error occurs, {

See also

query}

Since

1.22

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3539 of file Database.php.

useIndexClause()

Wikimedia\Rdbms\Database::useIndexClause

(

$index

)

USE INDEX clause.

This can be used as optimisation in queries that affect tables with multiple indexes if the database does not pick the most optimal one by default. The "right" index might vary between database backends and versions thereof, as such in practice this is biased toward specifically improving performance of large wiki farms that use MySQL or MariaDB (like Wikipedia).

Stability: stable

to override

Parameters

string

$index

Returns

string

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 3436 of file Database.php.

wasConnectionError()

Wikimedia\Rdbms\Database::wasConnectionError

(

$errno

)

Do not use this method outside of Database/DBError classes.

Stability: stable

to override

Parameters

int | string

$errno

Returns

bool Whether the given query error was a connection drop

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 4010 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt(), and Wikimedia\Rdbms\Database\getQueryException().

wasConnectionLoss()

Wikimedia\Rdbms\Database::wasConnectionLoss

(

)

Determines if the last query error was due to a dropped connection.Note that during a connection loss, the prior transaction will have been lost

Returns

bool

Since

1.31

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3983 of file Database.php.

wasDeadlock()

Wikimedia\Rdbms\Database::wasDeadlock

(

)

Determines if the last failure was due to a deadlock.Note that during a deadlock, the prior transaction will have been lost

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3967 of file Database.php.

wasErrorReissuable()

Wikimedia\Rdbms\Database::wasErrorReissuable

(

)

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

Note that the transaction may have been lost, discarding prior writes and results

Returns

bool

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 3995 of file Database.php.

wasKnownStatementRollbackError()

Wikimedia\Rdbms\Database::wasKnownStatementRollbackError ( )

protected

Stability: stable

to override

Returns

bool Whether it is known that the last query error only caused statement rollback

Note

This is for backwards compatibility for callers catching DBError exceptions in order to ignore problems like duplicate key errors or foriegn key violations

Since

1.31

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, Wikimedia\Rdbms\DatabasePostgres, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 4021 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

wasLockTimeout()

Wikimedia\Rdbms\Database::wasLockTimeout

(

)

Determines if the last failure was due to a lock timeout.Note that during a lock wait timeout, the prior transaction will have been lost

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabasePostgres.

Definition at line 3975 of file Database.php.

wasQueryTimeout()

Wikimedia\Rdbms\Database::wasQueryTimeout (   $error,   $errno  )

protected

Checks whether the cause of the error is detected to be a timeout.

It returns false by default, and not all engines support detecting this yet. If this returns false, it will be treated as a generic query error.

Stability: stable

to override

Parameters

string	$error	Error text
int	$errno	Error number

Returns

bool

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase.

Definition at line 1749 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getQueryException().

wasReadOnlyError()

Wikimedia\Rdbms\Database::wasReadOnlyError

(

)

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

Returns

bool

Stability: stable

to override

Implements Wikimedia\Rdbms\IDatabase.

Reimplemented in Wikimedia\Rdbms\DatabaseMysqlBase, and Wikimedia\Rdbms\DatabaseSqlite.

Definition at line 3991 of file Database.php.

writesOrCallbacksPending()

Wikimedia\Rdbms\Database::writesOrCallbacksPending

(

)

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

This does not count recurring callbacks, e.g. from setTransactionListener().

Returns

bool

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 715 of file Database.php.

References Wikimedia\Rdbms\Database\$trxSectionCancelCallbacks, and Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\Database\close(), and Wikimedia\Rdbms\Database\executeQueryAttempt().

writesPending()

Wikimedia\Rdbms\Database::writesPending

(

)

Returns

bool Whether there is a transaction open with possible write queries

Since

1.27

Implements Wikimedia\Rdbms\IDatabase.

Definition at line 711 of file Database.php.

References Wikimedia\Rdbms\Database\$trxDoneWrites, and Wikimedia\Rdbms\Database\trxLevel().

Referenced by Wikimedia\Rdbms\LoadBalancer\runPrimaryTransactionIdleCallbacks().

Member Data Documentation

$affectedRowCount

int null Wikimedia\Rdbms\Database::$affectedRowCount

protected

Rows affected by the last query to query() or its CRUD wrappers.

Definition at line 183 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\doInsertNonConflicting().

$agent

string Wikimedia\Rdbms\Database::$agent

protected

Agent name for query profiling.

Definition at line 93 of file Database.php.

$cliMode

bool Wikimedia\Rdbms\Database::$cliMode

protected

Whether this PHP instance is for a CLI script.

Definition at line 91 of file Database.php.

$conn

object resource null Wikimedia\Rdbms\Database::$conn

protected

Database connection.

Definition at line 77 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabasePostgres\addQuotes(), Wikimedia\Rdbms\DatabaseMysqli\closeConnection(), Wikimedia\Rdbms\DatabasePostgres\doQuery(), Wikimedia\Rdbms\Database\factory(), Wikimedia\Rdbms\DatabaseMysqli\fetchAffectedRowCount(), Wikimedia\Rdbms\DatabaseMysqlBase\getPrimaryServerInfo(), Wikimedia\Rdbms\DatabasePostgres\getServerVersion(), Wikimedia\Rdbms\DatabaseMysqli\insertId(), Wikimedia\Rdbms\Database\isOpen(), Wikimedia\Rdbms\DatabaseMysqli\mysqlError(), and Wikimedia\Rdbms\DatabaseMysqli\mysqlRealEscapeString().

$connectionParams

array<string,mixed> Wikimedia\Rdbms\Database::$connectionParams

protected

Connection parameters used by initConnection() and open()

Definition at line 99 of file Database.php.

$connectionVariables

string [] int [] float [] Wikimedia\Rdbms\Database::$connectionVariables

protected

SQL variables values to use for all new connections.

Definition at line 101 of file Database.php.

$connLogger

LoggerInterface Wikimedia\Rdbms\Database::$connLogger

protected

Definition at line 58 of file Database.php.

$csmError

DBUnexpectedError null Wikimedia\Rdbms\Database::$csmError

private

Last unresolved critical section error.

Definition at line 201 of file Database.php.

$csmFname

string null Wikimedia\Rdbms\Database::$csmFname

private

Last critical section caller name.

Definition at line 199 of file Database.php.

$csmId

int null Wikimedia\Rdbms\Database::$csmId

private

Current critical section numeric ID.

Definition at line 197 of file Database.php.

$csProvider

CriticalSectionProvider null Wikimedia\Rdbms\Database::$csProvider

protected

Definition at line 56 of file Database.php.

$currentDomain

DatabaseDomain Wikimedia\Rdbms\Database::$currentDomain

protected

Definition at line 73 of file Database.php.

$DBO_MUTABLE

int Wikimedia\Rdbms\Database::$DBO_MUTABLE

staticprotected

Initial value:

= (
        self::DBO_DEBUG | self::DBO_NOBUFFER | self::DBO_TRX | self::DBO_DDLMODE
    )

Bit field of all DBO_* flags that can be changed after connection.

Definition at line 262 of file Database.php.

$DEADLOCK_DELAY_MAX

int Wikimedia\Rdbms\Database::$DEADLOCK_DELAY_MAX = 1500000

staticprivate

Maximum time to wait before retry.

Definition at line 240 of file Database.php.

$DEADLOCK_DELAY_MIN

int Wikimedia\Rdbms\Database::$DEADLOCK_DELAY_MIN = 500000

staticprivate

Minimum time to wait before retry, in microseconds.

Definition at line 238 of file Database.php.

$DEADLOCK_TRIES

int Wikimedia\Rdbms\Database::$DEADLOCK_TRIES = 4

staticprivate

Number of times to re-try an operation in case of deadlock.

Definition at line 236 of file Database.php.

$delimiter

string Wikimedia\Rdbms\Database::$delimiter = ';'

protected

Current SQL query delimiter.

Definition at line 110 of file Database.php.

$deprecationLogger

callable Wikimedia\Rdbms\Database::$deprecationLogger

protected

Deprecation logging callback.

Definition at line 66 of file Database.php.

$errorLogger

callable Wikimedia\Rdbms\Database::$errorLogger

protected

Error logging callback.

Definition at line 64 of file Database.php.

$flags

int Wikimedia\Rdbms\Database::$flags

protected

Current bit field of class DBO_* constants.

Definition at line 106 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\clearFlag(), Wikimedia\Rdbms\Database\executeQuery(), Wikimedia\Rdbms\Database\executeQueryAttempt(), Wikimedia\Rdbms\DatabaseMysqlBase\getPrimaryServerInfo(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerGTIDs(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerId(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerRoleStatus(), Wikimedia\Rdbms\DatabaseMysqlBase\getServerUUID(), Wikimedia\Rdbms\DatabasePostgres\indexAttributes(), Wikimedia\Rdbms\DatabasePostgres\indexUnique(), Wikimedia\Rdbms\Database\isWriteQuery(), Wikimedia\Rdbms\DatabaseSqlite\isWriteQuery(), Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabaseSqlite\open(), Wikimedia\Rdbms\DatabaseMysqlBase\primaryPosWait(), Wikimedia\Rdbms\Database\query(), Wikimedia\Rdbms\DatabaseMysqlBase\serverIsReadOnly(), Wikimedia\Rdbms\Database\setFlag(), Wikimedia\Rdbms\DatabaseMysqlBase\setSessionOptions(), and Wikimedia\Rdbms\DatabasePostgres\textFieldSize().

$htmlErrors

string bool null Wikimedia\Rdbms\Database::$htmlErrors

private

Stashed value of html_errors INI setting.

Definition at line 119 of file Database.php.

$indexAliases

string [] Wikimedia\Rdbms\Database::$indexAliases = []

protected

Current map of (index alias => index)

Definition at line 114 of file Database.php.

$lastPhpError

string bool Wikimedia\Rdbms\Database::$lastPhpError = false

private

Definition at line 192 of file Database.php.

$lastPing

float Wikimedia\Rdbms\Database::$lastPing = 0.0

private

UNIX timestamp.

Definition at line 186 of file Database.php.

$lastQuery

string Wikimedia\Rdbms\Database::$lastQuery = ''

private

The last SQL query attempted.

Definition at line 188 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\lastQuery().

$lastRoundTripEstimate

float Wikimedia\Rdbms\Database::$lastRoundTripEstimate = 0.0

private

Query round trip time estimate.

Definition at line 194 of file Database.php.

$lastWriteTime

float bool Wikimedia\Rdbms\Database::$lastWriteTime = false

private

UNIX timestamp of last write query.

Definition at line 190 of file Database.php.

$lazyMasterHandle

IDatabase null Wikimedia\Rdbms\Database::$lazyMasterHandle

private

Lazy handle to the primary DB this server replicates from.

Definition at line 80 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getLazyMasterHandle().

$lbInfo

array Wikimedia\Rdbms\Database::$lbInfo = []

protected

Current LoadBalancer tracking information.

Definition at line 108 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getLBInfo().

$MUTABLE_FLAGS

string [] Wikimedia\Rdbms\Database::$MUTABLE_FLAGS

staticprotected

Initial value:

= [
        'DBO_DEBUG',
        'DBO_NOBUFFER',
        'DBO_TRX',
        'DBO_DDLMODE',
    ]

List of DBO_* flags that can be changed after connection.

Definition at line 255 of file Database.php.

$nonNativeInsertSelectBatchSize

int Wikimedia\Rdbms\Database::$nonNativeInsertSelectBatchSize

protected

Row batch size to use for emulated INSERT SELECT queries.

Definition at line 103 of file Database.php.

$NOT_APPLICABLE

string Wikimedia\Rdbms\Database::$NOT_APPLICABLE = 'n/a'

staticprivate

Idiom used when a cancelable atomic section started the transaction.

Definition at line 226 of file Database.php.

$ownerId

int null Wikimedia\Rdbms\Database::$ownerId

private

Integer ID of the managing LBFactory instance or null if none.

Definition at line 204 of file Database.php.

$password

string null Wikimedia\Rdbms\Database::$password

protected

Password used to establish the current connection.

Definition at line 87 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabasePostgres\open().

$PING_QUERY

string Wikimedia\Rdbms\Database::$PING_QUERY = 'SELECT 1 AS ping'

staticprivate

Dummy SQL query.

Definition at line 245 of file Database.php.

$PING_TTL

float Wikimedia\Rdbms\Database::$PING_TTL = 1.0

staticprivate

How long before it is worth doing a dummy query to test the connection.

Definition at line 243 of file Database.php.

$priorFlags

int [] Wikimedia\Rdbms\Database::$priorFlags = []

private

Prior flags member variable values.

Definition at line 121 of file Database.php.

$profiler

callable null Wikimedia\Rdbms\Database::$profiler

protected

Definition at line 68 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQueryAttempt().

$queryLogger

LoggerInterface Wikimedia\Rdbms\Database::$queryLogger

protected

Definition at line 60 of file Database.php.

$replLogger

LoggerInterface Wikimedia\Rdbms\Database::$replLogger

protected

Definition at line 62 of file Database.php.

$SAVEPOINT_PREFIX

string Wikimedia\Rdbms\Database::$SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic'

staticprivate

Prefix to the atomic section counter used to make savepoint IDs.

Definition at line 228 of file Database.php.

$schemaVars

array null Wikimedia\Rdbms\Database::$schemaVars

protected

Current variables use for schema element placeholders.

Definition at line 116 of file Database.php.

$server

string null Wikimedia\Rdbms\Database::$server

protected

Server that this instance is currently connected to.

Definition at line 83 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabasePostgres\open().

$serverName

string null Wikimedia\Rdbms\Database::$serverName

protected

Readible name or host/IP of the database server.

Definition at line 89 of file Database.php.

$sessionDirtyTempTables

array Wikimedia\Rdbms\Database::$sessionDirtyTempTables = []

protected

Map of (table name => 1) for current TEMPORARY tables.

Definition at line 128 of file Database.php.

$sessionNamedLocks

array<string,float> Wikimedia\Rdbms\Database::$sessionNamedLocks = []

protected

Map of (name => UNIX timestamp) for locks obtained via lock()

Definition at line 124 of file Database.php.

$sessionTempTables

array Wikimedia\Rdbms\Database::$sessionTempTables = []

protected

Map of (table name => 1) for current TEMPORARY tables.

Definition at line 126 of file Database.php.

$SLOW_WRITE_SEC

float Wikimedia\Rdbms\Database::$SLOW_WRITE_SEC = 0.500

staticprivate

Consider a write slow if it took more than this many seconds.

Definition at line 250 of file Database.php.

$SMALL_WRITE_ROWS

int Wikimedia\Rdbms\Database::$SMALL_WRITE_ROWS = 100

staticprivate

Assume an insert of this many rows or less should be fast to replicate.

Definition at line 252 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\updateTrxWriteQueryTime().

$srvCache

BagOStuff Wikimedia\Rdbms\Database::$srvCache

protected

APC cache.

Definition at line 54 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqlBase\getPrimaryServerInfo(), and Wikimedia\Rdbms\DatabaseMysqlBase\getServerVersion().

$tableAliases

array [] Wikimedia\Rdbms\Database::$tableAliases = []

protected

Current map of (table => (dbname, schema, prefix) map)

Definition at line 112 of file Database.php.

$TEMP_NORMAL

int Wikimedia\Rdbms\Database::$TEMP_NORMAL = 1

staticprivate

Writes to this temporary table do not affect lastDoneWrites()

Definition at line 231 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\executeQuery(), and Wikimedia\Rdbms\Database\getTempTableWrites().

$TEMP_PSEUDO_PERMANENT

int Wikimedia\Rdbms\Database::$TEMP_PSEUDO_PERMANENT = 2

staticprivate

Writes to this temporary table effect lastDoneWrites()

Definition at line 233 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getTempTableWrites().

$TINY_WRITE_SEC

float Wikimedia\Rdbms\Database::$TINY_WRITE_SEC = 0.010

staticprivate

Guess of how many seconds it takes to replicate a small insert.

Definition at line 248 of file Database.php.

$topologyRole

string Wikimedia\Rdbms\Database::$topologyRole

protected

Replication topology role of the server; one of the class ROLE_* constants.

Definition at line 95 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getTopologyRole().

$topologyRootMaster

string null Wikimedia\Rdbms\Database::$topologyRootMaster

protected

Host (or address) of the root primary server for the replication topology.

Definition at line 97 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\getTopologyRootMaster(), and Wikimedia\Rdbms\Database\getTopologyRootPrimary().

$trxAtomicCounter

int Wikimedia\Rdbms\Database::$trxAtomicCounter = 0

private

Counter for atomic savepoint identifiers (reset with each transaction)

Definition at line 149 of file Database.php.

$trxAtomicLevels

array Wikimedia\Rdbms\Database::$trxAtomicLevels = []

private

List of (name, unique ID, savepoint ID) for each active atomic section level.

Definition at line 151 of file Database.php.

$trxAutomatic

bool Wikimedia\Rdbms\Database::$trxAutomatic = false

private

Whether the current transaction was started implicitly due to DBO_TRX.

Definition at line 147 of file Database.php.

$trxAutomaticAtomic

bool Wikimedia\Rdbms\Database::$trxAutomaticAtomic = false

private

Whether the current transaction was started implicitly by startAtomic()

Definition at line 153 of file Database.php.

$trxDoneWrites

bool Wikimedia\Rdbms\Database::$trxDoneWrites = false

private

Whether possible write queries were done in the last transaction started.

Definition at line 145 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\writesPending().

$trxEndCallbacks

array [] Wikimedia\Rdbms\Database::$trxEndCallbacks = []

private

List of (callable, method name, atomic section id)

Definition at line 174 of file Database.php.

$trxEndCallbacksSuppressed

bool Wikimedia\Rdbms\Database::$trxEndCallbacksSuppressed = false

private

Whether to suppress triggering of transaction end callbacks.

Definition at line 180 of file Database.php.

$trxFname

string null Wikimedia\Rdbms\Database::$trxFname = null

private

Name of the function that start the last transaction.

Definition at line 143 of file Database.php.

$trxPostCommitOrIdleCallbacks

array [] Wikimedia\Rdbms\Database::$trxPostCommitOrIdleCallbacks = []

private

List of (callable, method name, atomic section id)

Definition at line 167 of file Database.php.

$trxPreCommitOrIdleCallbacks

array [] Wikimedia\Rdbms\Database::$trxPreCommitOrIdleCallbacks = []

private

List of (callable, method name, atomic section id)

Definition at line 169 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\preCommitCallbacksPending().

$trxProfiler

TransactionProfiler Wikimedia\Rdbms\Database::$trxProfiler

protected

Definition at line 70 of file Database.php.

$trxRecurringCallbacks

callable [] Wikimedia\Rdbms\Database::$trxRecurringCallbacks = []

private

Map of (name => callable)

Definition at line 178 of file Database.php.

$trxReplicaLagStatus

array null Wikimedia\Rdbms\Database::$trxReplicaLagStatus = null

private

Replication lag estimate at the time of BEGIN for the last transaction.

Definition at line 141 of file Database.php.

$trxSectionCancelCallbacks

array [] Wikimedia\Rdbms\Database::$trxSectionCancelCallbacks = []

private

List of (callable, method name, atomic section id)

Definition at line 176 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\writesOrCallbacksPending().

$trxShortId

string Wikimedia\Rdbms\Database::$trxShortId = ''

private

ID of the active transaction or the empty string otherwise.

Definition at line 131 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\consumeTrxShortId().

$trxStatus

int Wikimedia\Rdbms\Database::$trxStatus = self::STATUS_TRX_NONE

private

Transaction status.

Definition at line 133 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\trxStatus().

$trxStatusCause

Throwable null Wikimedia\Rdbms\Database::$trxStatusCause

private

The last error that caused the status to become STATUS_TRX_ERROR.

Definition at line 135 of file Database.php.

$trxStatusIgnoredCause

array null Wikimedia\Rdbms\Database::$trxStatusIgnoredCause

private

Error details of the last statement-only rollback.

Definition at line 137 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\assertQueryIsCurrentlyAllowed().

$trxTimestamp

float null Wikimedia\Rdbms\Database::$trxTimestamp = null

private

UNIX timestamp at the time of BEGIN for the last transaction.

Definition at line 139 of file Database.php.

$trxWriteAdjDuration

float Wikimedia\Rdbms\Database::$trxWriteAdjDuration = 0.0

private

Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries.

Definition at line 163 of file Database.php.

$trxWriteAdjQueryCount

int Wikimedia\Rdbms\Database::$trxWriteAdjQueryCount = 0

private

Number of write queries counted in trxWriteAdjDuration.

Definition at line 165 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\pingAndCalculateLastTrxApplyTime().

$trxWriteAffectedRows

int Wikimedia\Rdbms\Database::$trxWriteAffectedRows = 0

private

Number of rows affected by write queries for the current transaction.

Definition at line 161 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\pendingWriteRowsAffected().

$trxWriteCallers

string [] Wikimedia\Rdbms\Database::$trxWriteCallers = []

private

Write query callers of the current transaction.

Definition at line 155 of file Database.php.

$trxWriteDuration

float Wikimedia\Rdbms\Database::$trxWriteDuration = 0.0

private

Seconds spent in write queries for the current transaction.

Definition at line 157 of file Database.php.

Referenced by Wikimedia\Rdbms\Database\pendingWriteQueryDuration().

$trxWriteQueryCount

int Wikimedia\Rdbms\Database::$trxWriteQueryCount = 0

private

Number of write queries for the current transaction.

Definition at line 159 of file Database.php.

$user

string null Wikimedia\Rdbms\Database::$user

protected

User that this instance is currently connected under the name of.

Definition at line 85 of file Database.php.

Referenced by Wikimedia\Rdbms\DatabaseMysqli\mysqlConnect(), Wikimedia\Rdbms\DatabaseMysqlBase\open(), and Wikimedia\Rdbms\DatabasePostgres\open().

CONN_HOST

const Wikimedia\Rdbms\Database::CONN_HOST = 'host'

protected

Hostname or IP address to use on all connections.

Definition at line 267 of file Database.php.

CONN_INITIAL_DB

const Wikimedia\Rdbms\Database::CONN_INITIAL_DB = 'dbname'

protected

Database name to use on initial connection.

Definition at line 273 of file Database.php.

CONN_INITIAL_SCHEMA

const Wikimedia\Rdbms\Database::CONN_INITIAL_SCHEMA = 'schema'

protected

Schema name to use on initial connection.

Definition at line 275 of file Database.php.

CONN_INITIAL_TABLE_PREFIX

const Wikimedia\Rdbms\Database::CONN_INITIAL_TABLE_PREFIX = 'tablePrefix'

protected

Table prefix to use on initial connection.

Definition at line 277 of file Database.php.

CONN_PASSWORD

const Wikimedia\Rdbms\Database::CONN_PASSWORD = 'password'

protected

Database server password to use on all connections.

Definition at line 271 of file Database.php.

CONN_USER

const Wikimedia\Rdbms\Database::CONN_USER = 'user'

protected

Database server username to use on all connections.

Definition at line 269 of file Database.php.

---

The documentation for this class was generated from the following file:

• includes/libs/rdbms/database/Database.php