MediaWiki  master
IDatabase.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
22 use Exception;
23 use stdClass;
27 use Wikimedia\ScopedCallback;
28 
42  public const TRIGGER_IDLE = 1;
44  public const TRIGGER_COMMIT = 2;
46  public const TRIGGER_ROLLBACK = 3;
48  public const TRIGGER_CANCEL = 4;
49 
51  public const TRANSACTION_EXPLICIT = '';
53  public const TRANSACTION_INTERNAL = 'implicit';
54 
56  public const ATOMIC_NOT_CANCELABLE = '';
58  public const ATOMIC_CANCELABLE = 'cancelable';
59 
61  public const FLUSHING_ONE = '';
63  public const FLUSHING_ALL_PEERS = 'flush';
65  public const FLUSHING_INTERNAL = 'flush-internal';
66 
68  public const ESTIMATE_TOTAL = 'total';
70  public const ESTIMATE_DB_APPLY = 'apply';
75  public const DBO_SSL = 256;
77  public const DBO_COMPRESS = 512;
78 
80  public const LOCK_TIMESTAMP = 1;
81 
83  public const UNION_ALL = true;
85  public const UNION_DISTINCT = false;
86 
88  public const LB_TRX_ROUND_ID = 'trxRoundId';
90  public const LB_READ_ONLY_REASON = 'readOnlyReason';
91 
93  public const ROLE_STREAMING_MASTER = 'streaming-master';
95  public const ROLE_STREAMING_REPLICA = 'streaming-replica';
97  public const ROLE_STATIC_CLONE = 'static-clone';
99  public const ROLE_UNKNOWN = 'unknown';
100 
108  public function getServerInfo();
109 
121  public function getTopologyBasedServerId();
122 
134  public function getTopologyRole();
135 
144  public function trxLevel();
145 
157  public function trxTimestamp();
158 
168  public function explicitTrxActive();
169 
176  public function tablePrefix( $prefix = null );
177 
184  public function dbSchema( $schema = null );
185 
192  public function getLBInfo( $name = null );
193 
202  public function setLBInfo( $nameOrArray, $value = null );
203 
209  public function lastQuery();
210 
217  public function lastDoneWrites();
218 
223  public function writesPending();
224 
233  public function writesOrCallbacksPending();
234 
244  public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
245 
252  public function pendingWriteCallers();
253 
257  public function isOpen();
258 
266  public function getDomainID();
267 
273  public function getType();
274 
284  public function insertId();
285 
291  public function lastErrno();
292 
298  public function lastError();
299 
309  public function affectedRows();
310 
318  public function getSoftwareLink();
319 
325  public function getServerVersion();
326 
340  public function close( $fname = __METHOD__ );
341 
370  public function query( $sql, $fname = __METHOD__, $flags = 0 );
371 
391  public function queryMulti(
392  array $sqls, string $fname = __METHOD__, int $flags = 0, ?string $summarySql = null
393  );
394 
406 
426  public function selectField(
427  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
428  );
429 
450  public function selectFieldValues(
451  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
452  ): array;
453 
637  public function select(
638  $table,
639  $vars,
640  $conds = '',
641  $fname = __METHOD__,
642  $options = [],
643  $join_conds = []
644  );
645 
665  public function selectRow(
666  $table,
667  $vars,
668  $conds,
669  $fname = __METHOD__,
670  $options = [],
671  $join_conds = []
672  );
673 
699  public function estimateRowCount(
700  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
701  );
702 
724  public function selectRowCount(
725  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
726  );
727 
740  public function lockForUpdate(
741  $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
742  );
743 
766  public function insert( $table, $rows, $fname = __METHOD__, $options = [] );
767 
795  public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] );
796 
809  public function databasesAreIndependent();
810 
823  public function selectDomain( $domain );
824 
830  public function getDBname();
831 
837  public function getServer();
838 
845  public function getServerName();
846 
863  public function nextSequenceValue( $seqName );
864 
899  public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ );
900 
941  public function upsert(
942  $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__
943  );
944 
965  public function deleteJoin(
966  $delTable,
967  $joinTable,
968  $delVar,
969  $joinVar,
970  $conds,
971  $fname = __METHOD__
972  );
973 
989  public function delete( $table, $conds, $fname = __METHOD__ );
990 
1024  public function insertSelect(
1025  $destTable,
1026  $srcTable,
1027  $varMap,
1028  $conds,
1029  $fname = __METHOD__,
1030  $insertOptions = [],
1031  $selectOptions = [],
1032  $selectJoinConds = []
1033  );
1034 
1042  public function wasDeadlock();
1043 
1051  public function wasLockTimeout();
1052 
1061  public function wasConnectionLoss();
1062 
1068  public function wasReadOnlyError();
1069 
1078  public function wasErrorReissuable();
1079 
1097  public function primaryPosWait( DBPrimaryPos $pos, $timeout );
1098 
1105  public function getReplicaPos();
1106 
1114  public function getPrimaryPos();
1115 
1121  public function serverIsReadOnly();
1122 
1155  public function onTransactionResolution( callable $callback, $fname = __METHOD__ );
1156 
1191  public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ );
1192 
1222  public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ );
1223 
1247  public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ );
1248 
1266  public function setTransactionListener( $name, callable $callback = null );
1267 
1342  public function startAtomic( $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE );
1343 
1355  public function endAtomic( $fname = __METHOD__ );
1356 
1382  public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null );
1383 
1456  public function doAtomicSection(
1457  $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
1458  );
1459 
1479  public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT );
1480 
1499  public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1500 
1520  public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1521 
1539  public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1540 
1561  public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1562 
1568  public function ping();
1569 
1578  public function getLag();
1579 
1594  public function getSessionLagStatus();
1595 
1606  public function encodeBlob( $b );
1607 
1617  public function decodeBlob( $b );
1618 
1630  public function setSessionOptions( array $options );
1631 
1641  public function lockIsFree( $lockName, $method );
1642 
1655  public function lock( $lockName, $method, $timeout = 5, $flags = 0 );
1656 
1667  public function unlock( $lockName, $method );
1668 
1690  public function getScopedLockAndFlush( $lockKey, $fname, $timeout );
1691 
1698  public function namedLocksEnqueue();
1699 
1704  public function isReadOnly();
1705 
1713  public function __toString();
1714 }
1715 
1719 class_alias( IDatabase::class, 'IDatabase' );
Class used for token representing identifiers for atomic sections from IDatabase instances.
A query builder for SELECT queries with a fluent interface.
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:40
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.
ping()
Ping the server and try to reconnect if it there is no connection.
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 server to catch up to a given primary server 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 attempted 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.
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...
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 attempted query statement.
getServerInfo()
Get a human-readable string describing the current software version.
lockIsFree( $lockName, $method)
Check to see if a named lock is not locked by any thread (non-blocking)
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 attempted 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 server lag when the current transaction started or a general lag estimate if not tran...
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.
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.
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:80
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_COMPRESS
Definition: defines.php:19
const DBO_SSL
Definition: defines.php:18