interface IDatabase {
/** @var int Callback triggered immediately due to no active transaction */
const TRIGGER_IDLE = 1;
- /** @var int Callback triggered by commit */
+ /** @var int Callback triggered by COMMIT */
const TRIGGER_COMMIT = 2;
- /** @var int Callback triggered by rollback */
+ /** @var int Callback triggered by ROLLBACK */
const TRIGGER_ROLLBACK = 3;
/** @var string Transaction is requested by regular caller outside of the DB layer */
/** @var string Restore to the initial flag state */
const RESTORE_INITIAL = 'initial';
+ /** @var string Estimate total time (RTT, scanning, waiting on locks, applying) */
+ const ESTIMATE_TOTAL = 'total';
+ /** @var string Estimate time to apply (scanning, applying) */
+ const ESTIMATE_DB_APPLY = 'apply';
+
/**
* A string describing the current software version, and possibly
* other details in a user-friendly way. Will be listed on Special:Version, etc.
/**
* Returns true if there is a transaction open with possible write
* queries or transaction pre-commit/idle callbacks waiting on it to finish.
+ * This does *not* count recurring callbacks, e.g. from setTransactionListener().
*
* @return bool
*/
*
* High times could be due to scanning, updates, locking, and such
*
+ * @param string $type IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL]
* @return float|bool Returns false if not transaction is active
* @since 1.26
*/
- public function pendingWriteQueryDuration();
+ public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
/**
* Get the list of method names that did write queries for this transaction
public function wasReadOnlyError();
/**
- * Wait for the slave to catch up to a given master position
+ * Wait for the replica DB to catch up to a given master position
*
* @param DBMasterPos $pos
* @param int $timeout The maximum number of seconds to wait for synchronisation
- * @return int|null Zero if the slave was past that position already,
+ * @return 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
*/
public function masterPosWait( DBMasterPos $pos, $timeout );
/**
- * Get the replication position of this slave
+ * Get the replication position of this replica DB
*
- * @return DBMasterPos|bool False if this is not a slave.
+ * @return DBMasterPos|bool False if this is not a replica DB.
*/
public function getSlavePos();
* This is useful for combining cooperative locks and DB transactions.
*
* The callback takes one argument:
- * How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK)
+ * - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK)
*
* @param callable $callback
* @return mixed
* Updates will execute in the order they were enqueued.
*
* The callback takes one argument:
- * How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE)
+ * - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE)
*
* @param callable $callback
* @since 1.20
*/
public function onTransactionPreCommitOrIdle( callable $callback );
+ /**
+ * Run a callback 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
+ *
+ * @param string $name Callback name
+ * @param callable|null $callback Use null to unset a listener
+ * @return mixed
+ * @since 1.28
+ */
+ public function setTransactionListener( $name, callable $callback = null );
+
/**
* Begin an atomic section of statements
*
* will cause a warning, unless the current transaction was started
* automatically because of the DBO_TRX flag.
*
- * @param string $fname
+ * @param string $fname Calling function name
* @param string $mode A situationally valid IDatabase::TRANSACTION_* constant [optional]
* @throws DBError
*/
* throwing an Exception is preferrable, using a pre-installed error handler to trigger
* rollback (in any case, failure to issue COMMIT will cause rollback server-side).
*
- * @param string $fname
+ * @param string $fname Calling function name
* @param 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
*/
public function rollback( $fname = __METHOD__, $flush = '' );
+ /**
+ * 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 master.
+ *
+ * @param string $fname Calling function name
+ * @throws DBUnexpectedError
+ * @since 1.28
+ */
+ public function flushSnapshot( $fname = __METHOD__ );
+
/**
* List all tables on the database
*
/**
* Ping the server and try to reconnect if it there is no connection
*
+ * @param float|null &$rtt Value to store the estimated RTT [optional]
* @return bool Success or failure
*/
- public function ping();
+ public function ping( &$rtt = null );
/**
- * Get slave lag. Currently supported only by MySQL.
+ * Get replica DB lag. Currently supported only by MySQL.
*
* Note that this function will generate a fatal error on many
* installations. Most callers should use LoadBalancer::safeGetLag()
public function getLag();
/**
- * Get the slave lag when the current transaction started
+ * 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
dépôts / lhc / web / wiklou.git / blobdiff