const TRIGGER_COMMIT = 2;
/** @var int Callback triggered by ROLLBACK */
const TRIGGER_ROLLBACK = 3;
+ /** @var int Callback triggered by atomic section cancel (ROLLBACK TO SAVEPOINT) */
+ const TRIGGER_CANCEL = 4;
/** @var string Transaction is requested by regular caller outside of the DB layer */
const TRANSACTION_EXPLICIT = '';
/** @var int Enable compression in connection protocol */
const DBO_COMPRESS = 512;
+ /** @var int Idiom for "no special flags" */
+ const QUERY_NORMAL = 0;
/** @var int Ignore query errors and return false when they happen */
const QUERY_SILENCE_ERRORS = 1; // b/c for 1.32 query() argument; note that (int)true = 1
/**
const QUERY_REPLICA_ROLE = 4;
/** @var int Ignore the current presence of any DBO_TRX flag */
const QUERY_IGNORE_DBO_TRX = 8;
+ /** @var int Do not try to retry the query if the connection was lost */
+ const QUERY_NO_RETRY = 16;
/** @var bool Parameter to unionQueries() for UNION ALL */
const UNION_ALL = true;
* $query .= $dbr->buildLike( $pattern );
*
* @since 1.16
+ * @param array[]|string|LikeMatch $param
* @return string Fully built LIKE statement
+ * @phan-suppress-next-line PhanMismatchVariadicComment
+ * @phan-param array|string|LikeMatch ...$param T226223
*/
- public function buildLike();
+ public function buildLike( $param );
/**
* Returns a token for buildLike() that denotes a '_' to be used in a LIKE query
*
* This is useful for combining cooperative locks and DB transactions.
*
+ * Note this is called when the whole transaction is resolved. To take action immediately
+ * when an atomic section is cancelled, use onAtomicSectionCancel().
+ *
* @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
*
* The callback takes the following arguments:
*/
public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ );
+ /**
+ * 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
+ *
+ * @param callable $callback
+ * @param string $fname Caller name
+ * @since 1.34
+ */
+ public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ );
+
/**
* Run a callback after each time any transaction commits or rolls back
*
*
* @throws DBError
*/
- public function commit( $fname = __METHOD__, $flush = '' );
+ public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
/**
* Rollback a transaction previously started using begin().
* @throws DBError
* @since 1.23 Added $flush parameter
*/
- public function rollback( $fname = __METHOD__, $flush = '' );
+ public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
/**
* Commit any transaction but error out if writes or callbacks are pending
* useful to call on a replica DB after waiting on replication to catch up to the master.
*
* @param string $fname Calling function name
+ * @param 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.
+ *
* @throws DBError
* @since 1.28
+ * @since 1.34 Added $flush parameter
*/
- public function flushSnapshot( $fname = __METHOD__ );
+ public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
/**
* Convert a timestamp in one of the formats accepted by wfTimestamp()
*
* @param string $lockName Name of lock to aquire
* @param string $method Name of the calling method
- * @param int $timeout Acquisition timeout in seconds
+ * @param int $timeout Acquisition timeout in seconds (0 means non-blocking)
* @return bool
* @throws DBError
*/