MediaWiki  master
IDatabase.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
22 use Exception;
23 use stdClass;
26 use Wikimedia\ScopedCallback;
27 
39 interface IDatabase extends ISQLPlatform, DbQuoter {
41  public const TRIGGER_IDLE = 1;
43  public const TRIGGER_COMMIT = 2;
45  public const TRIGGER_ROLLBACK = 3;
47  public const TRIGGER_CANCEL = 4;
48 
50  public const TRANSACTION_EXPLICIT = '';
52  public const TRANSACTION_INTERNAL = 'implicit';
53 
55  public const ATOMIC_NOT_CANCELABLE = '';
57  public const ATOMIC_CANCELABLE = 'cancelable';
58 
60  public const FLUSHING_ONE = '';
62  public const FLUSHING_ALL_PEERS = 'flush';
64  public const FLUSHING_INTERNAL = 'flush-internal';
65 
67  public const REMEMBER_NOTHING = '';
69  public const REMEMBER_PRIOR = 'remember';
71  public const RESTORE_PRIOR = 'prior';
73  public const RESTORE_INITIAL = 'initial';
74 
76  public const ESTIMATE_TOTAL = 'total';
78  public const ESTIMATE_DB_APPLY = 'apply';
79 
81  public const DBO_DEBUG = 1;
83  public const DBO_NOBUFFER = 2;
85  public const DBO_IGNORE = 4;
87  public const DBO_TRX = 8;
89  public const DBO_DEFAULT = 16;
91  public const DBO_PERSISTENT = 32;
93  public const DBO_SYSDBA = 64;
95  public const DBO_DDLMODE = 128;
100  public const DBO_SSL = 256;
102  public const DBO_COMPRESS = 512;
103 
105  public const LOCK_TIMESTAMP = 1;
106 
108  public const UNION_ALL = true;
110  public const UNION_DISTINCT = false;
111 
113  public const LB_TRX_ROUND_ID = 'trxRoundId';
115  public const LB_READ_ONLY_REASON = 'readOnlyReason';
116 
118  public const ROLE_STREAMING_MASTER = 'streaming-master';
120  public const ROLE_STREAMING_REPLICA = 'streaming-replica';
122  public const ROLE_STATIC_CLONE = 'static-clone';
124  public const ROLE_UNKNOWN = 'unknown';
125 
133  public function getServerInfo();
134 
146  public function getTopologyBasedServerId();
147 
159  public function getTopologyRole();
160 
169  public function trxLevel();
170 
182  public function trxTimestamp();
183 
193  public function explicitTrxActive();
194 
201  public function tablePrefix( $prefix = null );
202 
209  public function dbSchema( $schema = null );
210 
217  public function getLBInfo( $name = null );
218 
227  public function setLBInfo( $nameOrArray, $value = null );
228 
234  public function lastQuery();
235 
242  public function lastDoneWrites();
243 
248  public function writesPending();
249 
258  public function writesOrCallbacksPending();
259 
269  public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
270 
277  public function pendingWriteCallers();
278 
282  public function isOpen();
283 
290  public function setFlag( $flag, $remember = self::REMEMBER_NOTHING );
291 
298  public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING );
299 
306  public function restoreFlags( $state = self::RESTORE_PRIOR );
307 
314  public function getFlag( $flag );
315 
323  public function getDomainID();
324 
330  public function getType();
331 
341  public function insertId();
342 
348  public function lastErrno();
349 
355  public function lastError();
356 
365  public function affectedRows();
366 
374  public function getSoftwareLink();
375 
381  public function getServerVersion();
382 
396  public function close( $fname = __METHOD__ );
397 
423  public function query( $sql, $fname = __METHOD__, $flags = 0 );
424 
437  public function queryMulti(
438  array $sqls, string $fname = __METHOD__, int $flags = 0, ?string $summarySql = null
439  );
440 
452 
472  public function selectField(
473  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
474  );
475 
496  public function selectFieldValues(
497  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
498  ): array;
499 
683  public function select(
684  $table,
685  $vars,
686  $conds = '',
687  $fname = __METHOD__,
688  $options = [],
689  $join_conds = []
690  );
691 
711  public function selectRow(
712  $table,
713  $vars,
714  $conds,
715  $fname = __METHOD__,
716  $options = [],
717  $join_conds = []
718  );
719 
745  public function estimateRowCount(
746  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
747  );
748 
770  public function selectRowCount(
771  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
772  );
773 
786  public function lockForUpdate(
787  $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
788  );
789 
809  public function insert( $table, $rows, $fname = __METHOD__, $options = [] );
810 
835  public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] );
836 
849  public function databasesAreIndependent();
850 
862  public function selectDB( $db );
863 
876  public function selectDomain( $domain );
877 
883  public function getDBname();
884 
890  public function getServer();
891 
898  public function getServerName();
899 
916  public function nextSequenceValue( $seqName );
917 
949  public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ );
950 
990  public function upsert(
991  $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__
992  );
993 
1011  public function deleteJoin(
1012  $delTable,
1013  $joinTable,
1014  $delVar,
1015  $joinVar,
1016  $conds,
1017  $fname = __METHOD__
1018  );
1019 
1032  public function delete( $table, $conds, $fname = __METHOD__ );
1033 
1064  public function insertSelect(
1065  $destTable,
1066  $srcTable,
1067  $varMap,
1068  $conds,
1069  $fname = __METHOD__,
1070  $insertOptions = [],
1071  $selectOptions = [],
1072  $selectJoinConds = []
1073  );
1074 
1082  public function wasDeadlock();
1083 
1091  public function wasLockTimeout();
1092 
1101  public function wasConnectionLoss();
1102 
1108  public function wasReadOnlyError();
1109 
1117  public function wasErrorReissuable();
1118 
1134  public function primaryPosWait( DBPrimaryPos $pos, $timeout );
1135 
1142  public function getReplicaPos();
1143 
1151  public function getPrimaryPos();
1152 
1158  public function serverIsReadOnly();
1159 
1192  public function onTransactionResolution( callable $callback, $fname = __METHOD__ );
1193 
1228  public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ );
1229 
1259  public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ );
1260 
1284  public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ );
1285 
1303  public function setTransactionListener( $name, callable $callback = null );
1304 
1379  public function startAtomic( $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE );
1380 
1392  public function endAtomic( $fname = __METHOD__ );
1393 
1419  public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null );
1420 
1493  public function doAtomicSection(
1494  $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
1495  );
1496 
1516  public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT );
1517 
1536  public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1537 
1557  public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1558 
1576  public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1577 
1597  public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1598 
1605  public function ping( &$rtt = null );
1606 
1615  public function getLag();
1616 
1631  public function getSessionLagStatus();
1632 
1643  public function encodeBlob( $b );
1644 
1654  public function decodeBlob( $b );
1655 
1667  public function setSessionOptions( array $options );
1668 
1678  public function lockIsFree( $lockName, $method );
1679 
1692  public function lock( $lockName, $method, $timeout = 5, $flags = 0 );
1693 
1704  public function unlock( $lockName, $method );
1705 
1727  public function getScopedLockAndFlush( $lockKey, $fname, $timeout );
1728 
1735  public function namedLocksEnqueue();
1736 
1746  public function setBigSelects( $value = true );
1747 
1752  public function isReadOnly();
1753 
1761  public function __toString();
1762 }
1763 
1767 class_alias( IDatabase::class, 'IDatabase' );
Class used for token representing identifiers for atomic sections from IDatabase instances.
Note that none of the methods in this class are stable to override.
An object representing a primary or replica DB position in a replicated setup.
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:39
onTransactionResolution(callable $callback, $fname=__METHOD__)
Run a callback when the current transaction commits or rolls back.
onTransactionPreCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback before the current transaction commits or now if there is none.
flushSnapshot( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commit any transaction but error out if writes or callbacks are pending.
rollback( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Rollback a transaction previously started using begin()
setSessionOptions(array $options)
Override database's default behavior.
nextSequenceValue( $seqName)
Deprecated method, calls should be removed.
lastDoneWrites()
Get the last time the connection may have been used for a write query.
unlock( $lockName, $method)
Release a lock.
explicitTrxActive()
Check whether there is a transaction open at the specific request of a caller.
namedLocksEnqueue()
Check to see if a named lock used by lock() use blocking queues.
setBigSelects( $value=true)
Allow or deny "big selects" for this session only.
selectRow( $table, $vars, $conds, $fname=__METHOD__, $options=[], $join_conds=[])
Wrapper to IDatabase::select() that only fetches one row (via LIMIT)
primaryPosWait(DBPrimaryPos $pos, $timeout)
Wait for the replica DB to catch up to a given primary DB position.
wasLockTimeout()
Determines if the last failure was due to a lock timeout.
doAtomicSection( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Perform an atomic section of reversible SQL statements from a callback.
getDomainID()
Return the currently selected domain ID.
lastErrno()
Get the RDBMS-specific error code from the last query statement.
endAtomic( $fname=__METHOD__)
Ends an atomic section of SQL statements.
lock( $lockName, $method, $timeout=5, $flags=0)
Acquire a named lock.
close( $fname=__METHOD__)
Close the database connection.
getServer()
Get the hostname or IP address of the server.
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.
getReplicaPos()
Get the replication position of this replica DB.
setLBInfo( $nameOrArray, $value=null)
Set the entire array or a particular key of the managing load balancer info array.
setTransactionListener( $name, callable $callback=null)
Run a callback after each time any transaction commits or rolls back.
getSoftwareLink()
Returns a wikitext style link to the DB's website (e.g.
wasErrorReissuable()
Determines if the last query error was due to something outside of the query itself.
flushSession( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Release important session-level state (named lock, table locks) as post-rollback cleanup.
lockForUpdate( $table, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Lock all rows meeting the given conditions/options FOR UPDATE.
queryMulti(array $sqls, string $fname=__METHOD__, int $flags=0, ?string $summarySql=null)
Run a batch of SQL query statements and return the results.
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
__toString()
Get a debugging string that mentions the database type, the ID of this instance, and the ID of any un...
restoreFlags( $state=self::RESTORE_PRIOR)
Restore the flags to their prior state before the last setFlag/clearFlag call.
insertSelect( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
INSERT SELECT wrapper.
deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname=__METHOD__)
Delete all rows in a table that match a condition which includes a join.
wasConnectionLoss()
Determines if the last query error was due to a dropped connection.
getTopologyBasedServerId()
Get a non-recycled ID that uniquely identifies this server within the replication topology.
affectedRows()
Get the number of rows affected by the last write query.
getServerInfo()
Get a human-readable string describing the current software version.
getFlag( $flag)
Returns a boolean whether the flag $flag is set for this connection.
lockIsFree( $lockName, $method)
Check to see if a named lock is not locked by any thread (non-blocking)
clearFlag( $flag, $remember=self::REMEMBER_NOTHING)
Clear a flag for this connection.
pendingWriteQueryDuration( $type=self::ESTIMATE_TOTAL)
Get the time spend running write queries for this transaction.
lastQuery()
Get the last query that sent on account of IDatabase::query()
update( $table, $set, $conds, $fname=__METHOD__, $options=[])
Update all rows in a table that match a given condition.
selectDomain( $domain)
Set the current domain (database, schema, and table prefix)
upsert( $table, array $rows, $uniqueKeys, array $set, $fname=__METHOD__)
Upsert row(s) into a table, in the provided order, while updating conflicting rows.
lastError()
Get the RDBMS-specific error description from the last query statement.
selectField( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
A SELECT wrapper which returns a single field from a single result row.
commit( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commits a transaction previously started using begin()
getTopologyRole()
Get the replication topology role of this server.
getType()
Get the RDBMS type of the server (e.g.
getLag()
Get the amount of replication lag for this database server.
getSessionLagStatus()
Get the replica DB lag when the current transaction started or a general lag estimate if not transact...
onTransactionCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback when the current transaction commits or now if there is none.
newSelectQueryBuilder()
Create an empty SelectQueryBuilder which can be used to run queries against this connection.
wasDeadlock()
Determines if the last failure was due to a deadlock.
tablePrefix( $prefix=null)
Get/set the table prefix.
selectRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Get the number of rows in dataset.
databasesAreIndependent()
Returns true if DBs are assumed to be on potentially different servers.
ping(&$rtt=null)
Ping the server and try to reconnect if it there is no connection.
getScopedLockAndFlush( $lockKey, $fname, $timeout)
Acquire a named lock, flush any transaction, and return an RAII style unlocker object.
decodeBlob( $b)
Some DBMSs return a special placeholder object representing blob fields in result objects.
onAtomicSectionCancel(callable $callback, $fname=__METHOD__)
Run a callback when the atomic section is cancelled.
query( $sql, $fname=__METHOD__, $flags=0)
Run an SQL query statement and return the result.
encodeBlob( $b)
Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strin...
getServerVersion()
A string describing the current software version, like from mysql_get_server_info()
begin( $fname=__METHOD__, $mode=self::TRANSACTION_EXPLICIT)
Begin a transaction.
insert( $table, $rows, $fname=__METHOD__, $options=[])
Insert row(s) into a table, in the provided order.
replace( $table, $uniqueKeys, $rows, $fname=__METHOD__)
Insert row(s) into a table, in the provided order, while deleting conflicting rows.
selectFieldValues( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
A SELECT wrapper which returns a list of single field values from result rows.
wasReadOnlyError()
Determines if the last failure was due to the database being read-only.
trxLevel()
Gets the current transaction level.
startAtomic( $fname=__METHOD__, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Begin an atomic section of SQL statements.
insertId()
Get the inserted value of an auto-increment row.
setFlag( $flag, $remember=self::REMEMBER_NOTHING)
Set a flag for this connection.
trxTimestamp()
Get the UNIX timestamp of the time that the transaction was established.
getDBname()
Get the current database name; null if there isn't one.
writesOrCallbacksPending()
Whether there is a transaction open with either possible write queries or unresolved pre-commit/commi...
getServerName()
Get the readable name for the server.
const LOCK_TIMESTAMP
Flag to return the lock acquisition timestamp (null if not acquired)
Definition: IDatabase.php:105
pendingWriteCallers()
Get the list of method names that did write queries for this transaction.
getPrimaryPos()
Get the position of this primary DB.
cancelAtomic( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
Cancel an atomic section of SQL statements.
dbSchema( $schema=null)
Get/set the db schema.
estimateRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Estimate the number of rows in dataset.
Interface for query language.
const DBO_NOBUFFER
Definition: defines.php:10
const DBO_DDLMODE
Definition: defines.php:16
const DBO_SYSDBA
Definition: defines.php:15
const DBO_COMPRESS
Definition: defines.php:19
const DBO_DEFAULT
Definition: defines.php:13
const DBO_SSL
Definition: defines.php:18
const DBO_IGNORE
Definition: defines.php:11
const DBO_PERSISTENT
Definition: defines.php:14
const DBO_DEBUG
Definition: defines.php:9
const DBO_TRX
Definition: defines.php:12