* @ingroup Database
*/
interface IDatabase {
- /* Constants to onTransactionResolution() callbacks */
+ /** @var int Callback triggered immediately due to no active transaction */
const TRIGGER_IDLE = 1;
+ /** @var int Callback triggered by commit */
const TRIGGER_COMMIT = 2;
+ /** @var int Callback triggered by rollback */
const TRIGGER_ROLLBACK = 3;
+ /** @var string Transaction is requested by regular caller outside of the DB layer */
+ const TRANSACTION_EXPLICIT = '';
+ /** @var string Transaction is requested interally via DBO_TRX/startAtomic() */
+ const TRANSACTION_INTERNAL = 'implicit';
+
+ /** @var string Transaction operation comes from service managing all DBs */
+ const FLUSHING_ALL_PEERS = 'flush';
+ /** @var string Transaction operation comes from the database class internally */
+ const FLUSHING_INTERNAL = 'flush';
+
+ /** @var string No not remember the prior flags */
+ const REMEMBER_NOTHING = '';
+ /** @var string Remember the prior flags */
+ const REMEMBER_PRIOR = 'remember';
+ /** @var string Restore to the prior flag state */
+ const RESTORE_PRIOR = 'prior';
+ /** @var string Restore to the initial flag state */
+ const RESTORE_INITIAL = 'initial';
+
/**
* A string describing the current software version, and possibly
* other details in a user-friendly way. Will be listed on Special:Version, etc.
*/
public function trxTimestamp();
+ /**
+ * @return bool Whether an explicit transaction or atomic sections are still open
+ * @since 1.28
+ */
+ public function explicitTrxActive();
+
/**
* Get/set the table prefix.
* @param string $prefix The table prefix to set, or omitted to leave it unchanged.
* - DBO_DEFAULT: automatically sets DBO_TRX if not in command line mode
* and removes it in command line mode
* - DBO_PERSISTENT: use persistant database connection
+ * @param string $remember IDatabase::REMEMBER_* constant [default: REMEMBER_NOTHING]
*/
- public function setFlag( $flag );
+ public function setFlag( $flag, $remember = self::REMEMBER_NOTHING );
/**
* Clear a flag for this connection
* - DBO_DEFAULT: automatically sets DBO_TRX if not in command line mode
* and removes it in command line mode
* - DBO_PERSISTENT: use persistant database connection
+ * @param string $remember IDatabase::REMEMBER_* constant [default: REMEMBER_NOTHING]
*/
- public function clearFlag( $flag );
+ public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING );
+
+ /**
+ * Restore the flags to their prior state before the last setFlag/clearFlag call
+ *
+ * @param string $state IDatabase::RESTORE_* constant. [default: RESTORE_PRIOR]
+ * @since 1.28
+ */
+ public function restoreFlags( $state = self::RESTORE_PRIOR );
/**
* Returns a boolean whether the flag $flag is set for this connection
*
* Example:
* $id = $dbw->nextSequenceValue( 'page_page_id_seq' );
- * $dbw->insert( 'page', array( 'page_id' => $id ) );
+ * $dbw->insert( 'page', [ 'page_id' => $id ] );
* $id = $dbw->insertId();
*
* @return int
* May be either an array of table names, or a single string holding a table
* name. If an array is given, table aliases can be specified, for example:
*
- * array( 'a' => 'user' )
+ * [ 'a' => 'user' ]
*
* This includes the user table in the query, with the alias "a" available
* for use in field names (e.g. a.user_name).
* can be complete fragments of SQL, for direct inclusion into the SELECT
* query. If an array is given, field aliases can be specified, for example:
*
- * array( 'maxrev' => 'MAX(rev_id)' )
+ * [ 'maxrev' => 'MAX(rev_id)' ]
*
* This includes an expression with the alias "maxrev" in the query.
*
* including them in the array as a string value with a numeric key, for
* example:
*
- * array( 'FOR UPDATE' )
+ * [ 'FOR UPDATE' ]
*
* The supported options are:
*
* an SQL fragment, or an array where the string keys are equality and the
* numeric keys are SQL fragments all AND'd together. For example:
*
- * array( 'page' => array( 'LEFT JOIN', 'page_latest=rev_id' ) )
+ * [ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ]
*
* @return ResultWrapper|bool If the query returned no rows, a ResultWrapper
* with no rows in it will be returned. If there was a query error, a
* The keys on each level may be either integers or strings.
*
* @param array $data Organized as 2-d
- * array(baseKeyVal => array(subKeyVal => [ignored], ...), ...)
+ * [ baseKeyVal => [ subKeyVal => [ignored], ... ], ... ]
* @param string $baseKey Field name to match the base-level keys to (eg 'pl_namespace')
* @param string $subKey Field name to match the sub-level keys to (eg 'pl_title')
* @return string|bool SQL fragment, or false if no items in array
* Example: $dbr->buildLike( 'My_page_title/', $dbr->anyString() ) returns
* a LIKE clause that searches for subpages of 'My page title'.
* Alternatively:
- * $pattern = array( 'My_page_title/', $dbr->anyString() );
+ * $pattern = [ 'My_page_title/', $dbr->anyString() ];
* $query .= $dbr->buildLike( $pattern );
*
* @since 1.16
* to include in a join.
*
* @param array $varMap Must be an associative array of the form
- * array( 'dest1' => 'source1', ...). Source items may be literals
+ * [ 'dest1' => 'source1', ... ]. Source items may be literals
* rather than field names, but strings should be quoted with
* IDatabase::addQuotes()
*
/**
* Determines how long the server has been up
- * STUB
*
* @return int
*/
/**
* Determines if the last failure was due to a deadlock
- * STUB
*
* @return bool
*/
/**
* Determines if the last failure was due to a lock timeout
- * STUB
*
* @return bool
*/
public function wasLockTimeout();
/**
- * Determines if the last query error was something that should be dealt
- * with by pinging the connection and reissuing the query.
- * STUB
+ * Determines if the last query error was due to a dropped connection and should
+ * be dealt with by pinging the connection and reissuing the query.
*
* @return bool
*/
/**
* Determines if the last failure was due to the database being read-only.
- * STUB
*
* @return bool
*/
*
* @param string $fname Caller name (usually __METHOD__)
* @param callable $callback Callback that issues DB updates
+ * @return mixed $res Result of the callback (since 1.28)
* @throws DBError
* @throws RuntimeException
* @throws UnexpectedValueException
* Begin a transaction. If a transaction is already in progress,
* that transaction will be committed before the new transaction is started.
*
+ * Only call this from code with outer transcation scope.
+ * See https://www.mediawiki.org/wiki/Database_transactions for details.
+ * Nesting of transactions is not supported.
+ *
* Note that when the DBO_TRX flag is set (which is usually the case for web
* requests, but not for maintenance scripts), any previous database query
* will have started a transaction automatically.
* automatically because of the DBO_TRX flag.
*
* @param string $fname
+ * @param string $mode A situationally valid IDatabase::TRANSACTION_* constant [optional]
* @throws DBError
*/
- public function begin( $fname = __METHOD__ );
+ public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT );
/**
* Commits a transaction previously started using begin().
* If no transaction is in progress, a warning is issued.
*
+ * Only call this from code with outer transcation scope.
+ * See https://www.mediawiki.org/wiki/Database_transactions for details.
* Nesting of transactions is not supported.
*
* @param string $fname
- * @param string $flush Flush flag, set to 'flush' to disable warnings about
- * explicitly committing implicit transactions, or calling commit when no
- * transaction is in progress.
+ * @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.
*
* Rollback a transaction previously started using begin().
* If no transaction is in progress, a warning is issued.
*
- * No-op on non-transactional databases.
+ * Only call this from code with outer transcation scope.
+ * See https://www.mediawiki.org/wiki/Database_transactions for details.
+ * Nesting of transactions is not supported. If a serious unexpected error occurs,
+ * 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 $flush Flush flag, set to 'flush' to disable warnings about
- * calling rollback when no transaction is in progress. This will silently
- * break any ongoing explicit transaction. Only set the flush flag if you
- * are sure that it is safe to ignore these warnings in your context.
+ * @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
+ * flush flag if you are sure that it is safe to ignore these warnings in your context.
* @throws DBUnexpectedError
* @since 1.23 Added $flush parameter
*/
/**
* Acquire a named lock, flush any transaction, and return an RAII style unlocker object
*
+ * Only call this from outer transcation scope and when only one DB will be affected.
+ * See https://www.mediawiki.org/wiki/Database_transactions for details.
+ *
* This is suitiable for transactions that need to be serialized using cooperative locks,
* where each transaction can see each others' changes. Any transaction is flushed to clear
* out stale REPEATABLE-READ snapshot data. Once the returned object falls out of PHP scope,
- * any transaction will be committed and the lock will be released.
+ * the lock will be released unless a transaction is active. If one is active, then the lock
+ * will be released when it either commits or rolls back.
*
* If the lock acquisition failed, then no transaction flush happens, and null is returned.
*
dépôts / lhc / web / wiklou.git / blobdiff