MediaWiki  master
IDatabase.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
22 use Exception;
23 use Wikimedia\ScopedCallback;
24 
36 interface IDatabase extends IReadableDatabase {
38  public const TRIGGER_IDLE = 1;
40  public const TRIGGER_COMMIT = 2;
42  public const TRIGGER_ROLLBACK = 3;
44  public const TRIGGER_CANCEL = 4;
45 
47  public const TRANSACTION_EXPLICIT = '';
49  public const TRANSACTION_INTERNAL = 'implicit';
50 
52  public const ATOMIC_NOT_CANCELABLE = '';
54  public const ATOMIC_CANCELABLE = 'cancelable';
55 
57  public const FLUSHING_ONE = '';
59  public const FLUSHING_ALL_PEERS = 'flush';
61  public const FLUSHING_INTERNAL = 'flush-internal';
62 
64  public const ESTIMATE_TOTAL = 'total';
66  public const ESTIMATE_DB_APPLY = 'apply';
67 
69  public const LOCK_TIMESTAMP = 1;
70 
72  public const LB_TRX_ROUND_ID = 'trxRoundId';
74  public const LB_READ_ONLY_REASON = 'readOnlyReason';
75 
77  public const ROLE_STREAMING_MASTER = 'streaming-master';
79  public const ROLE_STREAMING_REPLICA = 'streaming-replica';
81  public const ROLE_STATIC_CLONE = 'static-clone';
83  public const ROLE_UNKNOWN = 'unknown';
84 
96  public function getTopologyBasedServerId();
97 
109  public function getTopologyRole();
110 
119  public function trxLevel();
120 
132  public function trxTimestamp();
133 
143  public function explicitTrxActive();
144 
151  public function getLBInfo( $name = null );
152 
161  public function setLBInfo( $nameOrArray, $value = null );
162 
169  public function lastDoneWrites();
170 
175  public function writesPending();
176 
185  public function writesOrCallbacksPending();
186 
196  public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
197 
204  public function pendingWriteCallers();
205 
226  public function insertId();
227 
250  public function affectedRows();
251 
280  public function query( $sql, $fname = __METHOD__, $flags = 0 );
281 
293 
305 
318  public function lockForUpdate(
319  $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
320  );
321 
344  public function insert( $table, $rows, $fname = __METHOD__, $options = [] );
345 
373  public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] );
374 
391  public function nextSequenceValue( $seqName );
392 
427  public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ );
428 
469  public function upsert(
470  $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__
471  );
472 
493  public function deleteJoin(
494  $delTable,
495  $joinTable,
496  $delVar,
497  $joinVar,
498  $conds,
499  $fname = __METHOD__
500  );
501 
517  public function delete( $table, $conds, $fname = __METHOD__ );
518 
552  public function insertSelect(
553  $destTable,
554  $srcTable,
555  $varMap,
556  $conds,
557  $fname = __METHOD__,
558  $insertOptions = [],
559  $selectOptions = [],
560  $selectJoinConds = []
561  );
562 
570  public function getPrimaryPos();
571 
577  public function serverIsReadOnly();
578 
611  public function onTransactionResolution( callable $callback, $fname = __METHOD__ );
612 
647  public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ );
648 
678  public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ );
679 
703  public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ );
704 
722  public function setTransactionListener( $name, callable $callback = null );
723 
798  public function startAtomic( $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE );
799 
811  public function endAtomic( $fname = __METHOD__ );
812 
838  public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null );
839 
912  public function doAtomicSection(
913  $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
914  );
915 
935  public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT );
936 
955  public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
956 
976  public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
977 
995  public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
996 
1017  public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
1018 
1036  public function setSessionOptions( array $options );
1037 
1047  public function lockIsFree( $lockName, $method );
1048 
1061  public function lock( $lockName, $method, $timeout = 5, $flags = 0 );
1062 
1073  public function unlock( $lockName, $method );
1074 
1096  public function getScopedLockAndFlush( $lockKey, $fname, $timeout );
1097 
1104  public function namedLocksEnqueue();
1105 
1114  public function isReadOnly();
1115 }
1116 
1120 class_alias( IDatabase::class, 'IDatabase' );
Class used for token representing identifiers for atomic sections from IDatabase instances.
A query builder for DELETE queries with a fluent interface.
Build UPDATE queries with a fluent interface.
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:36
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.
doAtomicSection( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Perform an atomic section of reversible SQL statements from a callback.
endAtomic( $fname=__METHOD__)
Ends an atomic section of SQL statements.
lock( $lockName, $method, $timeout=5, $flags=0)
Acquire a named lock.
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.
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.
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
newUpdateQueryBuilder()
Get an UpdateQueryBuilder bound to this connection.
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.
getTopologyBasedServerId()
Get a non-recycled ID that uniquely identifies this server within the replication topology.
newDeleteQueryBuilder()
Get an DeleteQueryBuilder bound to this connection.
affectedRows()
Get the number of rows affected by the last query method call.
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.
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 row(s) into a table, in the provided order, while updating conflicting rows.
commit( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commits a transaction previously started using begin()
getTopologyRole()
Get the replication topology role of this server.
onTransactionCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback when the current transaction commits or now if there is none.
getScopedLockAndFlush( $lockKey, $fname, $timeout)
Acquire a named lock, flush any transaction, and return an RAII style unlocker object.
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.
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.
trxLevel()
Gets the current transaction level.
startAtomic( $fname=__METHOD__, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Begin an atomic section of SQL statements.
insertId()
Get the sequence-based ID assigned by the last query method call.
trxTimestamp()
Get the UNIX timestamp of the time that the transaction was established.
writesOrCallbacksPending()
Whether there is a transaction open with either possible write queries or unresolved pre-commit/commi...
const LOCK_TIMESTAMP
Flag to return the lock acquisition timestamp (null if not acquired)
Definition: IDatabase.php:69
pendingWriteCallers()
Get the list of method names that did write queries for this transaction.
getPrimaryPos()
Get the replication position of this primary DB server.
cancelAtomic( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
Cancel an atomic section of SQL statements.
isReadOnly()
Check if this DB server is marked as read-only according to load balancer info.
A database connection without write operations.