X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Flibs%2Frdbms%2Fdatabase%2FIDatabase.php;h=85b3481fe3e9a838bdb817754df211040b2bd643;hb=71184c31f6e1b55155d916ac447d0a59ae59a94a;hp=9375efc2538e1003f7a1e59ae140426de8a04a00;hpb=feaf1daca9a0614efd35278e196a0fc18cb381a3;p=lhc%2Fweb%2Fwiklou.git diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php index 9375efc253..85b3481fe3 100644 --- a/includes/libs/rdbms/database/IDatabase.php +++ b/includes/libs/rdbms/database/IDatabase.php @@ -1,10 +1,5 @@ nextSequenceValue( 'page_page_id_seq' ); - * $dbw->insert( 'page', [ 'page_id' => $id ] ); - * $id = $dbw->insertId(); + * This should only be called after an insert that used an auto-incremented + * value. If no such insert was previously done in the current database + * session, the return value is undefined. * * @return int */ @@ -526,9 +523,9 @@ interface IDatabase { * comment (you can use __METHOD__ or add some extra info) * @param bool $tempIgnore Whether to avoid throwing an exception on errors... * maybe best to catch the exception instead? - * @throws DBError * @return bool|IResultWrapper True for a successful write query, IResultWrapper object * for a successful read query, or false on failure if $tempIgnore set + * @throws DBError */ public function query( $sql, $fname = __METHOD__, $tempIgnore = false ); @@ -570,7 +567,8 @@ interface IDatabase { * @param string|array $options The query options. See IDatabase::select() for details. * @param string|array $join_conds The query join conditions. See IDatabase::select() for details. * - * @return bool|mixed The value from the field, or false on failure. + * @return mixed The value from the field + * @throws DBError */ public function selectField( $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] @@ -592,7 +590,8 @@ interface IDatabase { * @param string|array $options The query options. See IDatabase::select() for details. * @param string|array $join_conds The query join conditions. See IDatabase::select() for details. * - * @return bool|array The values from the field, or false on failure + * @return array The values from the field + * @throws DBError * @since 1.25 */ public function selectFieldValues( @@ -621,6 +620,19 @@ interface IDatabase { * This includes the user table in the query, with the alias "a" available * for use in field names (e.g. a.user_name). * + * Joins using parentheses for grouping (since MediaWiki 1.31) may be + * constructed using nested arrays. For example, + * + * [ 'tableA', 'nestedB' => [ 'tableB', 'b2' => 'tableB2' ] ] + * + * along with `$join_conds` like + * + * [ 'b2' => [ 'JOIN', 'b_id = b2_id' ], 'nestedB' => [ 'LEFT JOIN', 'b_a = a_id' ] ] + * + * will produce SQL something like + * + * FROM tableA LEFT JOIN (tableB JOIN tableB2 AS b2 ON (b_id = b2_id)) ON (b_a = a_id) + * * All of the table names given here are automatically run through * Database::tableName(), which causes the table prefix (if any) to be * added, and various other table name mappings to be performed. @@ -743,10 +755,8 @@ interface IDatabase { * * [ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ] * - * @return IResultWrapper|bool If the query returned no rows, a IResultWrapper - * with no rows in it will be returned. If there was a query error, a - * DBQueryError exception will be thrown, except if the "ignore errors" - * option was set, in which case false will be returned. + * @return IResultWrapper Resulting rows + * @throws DBError */ public function select( $table, $vars, $conds = '', $fname = __METHOD__, @@ -787,6 +797,7 @@ interface IDatabase { * @param array|string $join_conds Join conditions * * @return stdClass|bool + * @throws DBError */ public function selectRow( $table, $vars, $conds, $fname = __METHOD__, $options = [], $join_conds = [] @@ -811,6 +822,7 @@ interface IDatabase { * @param string $fname Function name for profiling * @param array $options Options for select * @return int Row count + * @throws DBError */ public function estimateRowCount( $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [] @@ -832,6 +844,7 @@ interface IDatabase { * @param array $options Options for select * @param array $join_conds Join conditions (since 1.27) * @return int Row count + * @throws DBError */ public function selectRowCount( $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] @@ -844,6 +857,7 @@ interface IDatabase { * @param string $field Filed to check on that table * @param string $fname Calling function name (optional) * @return bool Whether $table has filed $field + * @throws DBError */ public function fieldExists( $table, $field, $fname = __METHOD__ ); @@ -856,6 +870,7 @@ interface IDatabase { * @param string $index * @param string $fname * @return bool|null + * @throws DBError */ public function indexExists( $table, $index, $fname = __METHOD__ ); @@ -865,6 +880,7 @@ interface IDatabase { * @param string $table * @param string $fname * @return bool + * @throws DBError */ public function tableExists( $table, $fname = __METHOD__ ); @@ -910,6 +926,7 @@ interface IDatabase { * @param array $options Array of options * * @return bool + * @throws DBError */ public function insert( $table, $a, $fname = __METHOD__, $options = [] ); @@ -932,6 +949,7 @@ interface IDatabase { * - IGNORE: Ignore unique key conflicts * - LOW_PRIORITY: MySQL-specific, see MySQL manual. * @return bool + * @throws DBError */ public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ); @@ -1114,15 +1132,20 @@ interface IDatabase { public function anyString(); /** - * Returns an appropriately quoted sequence value for inserting a new row. - * MySQL has autoincrement fields, so this is just NULL. But the PostgreSQL - * subclass will return an integer, and save the value for insertId() + * Deprecated method, calls should be removed. * - * Any implementation of this function should *not* involve reusing - * sequence numbers created for rolled-back transactions. - * See https://bugs.mysql.com/bug.php?id=30767 for details. + * This was formerly used for PostgreSQL and Oracle to handle + * self::insertId() auto-incrementing fields. It is no longer necessary + * since DatabasePostgres::insertId() has been reimplemented using + * `lastval()` and Oracle has been reimplemented using triggers. + * + * Implementations should return null if inserting `NULL` into an + * auto-incrementing field works, otherwise it should return an instance of + * NextSequenceValue and filter it on calls to relevant methods. + * + * @deprecated since 1.30, no longer needed * @param string $seqName - * @return null|int + * @return null|NextSequenceValue */ public function nextSequenceValue( $seqName ); @@ -1147,6 +1170,7 @@ interface IDatabase { * @param array $rows Can be either a single row to insert, or multiple rows, * in the same format as for IDatabase::insert() * @param string $fname Calling function name (use __METHOD__) for logs/profiling + * @throws DBError */ public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ); @@ -1183,7 +1207,7 @@ interface IDatabase { * Values with integer keys form unquoted SET statements, which can be used for * things like "field = field + 1" or similar computed values. * @param string $fname Calling function name (use __METHOD__) for logs/profiling - * @throws Exception + * @throws DBError * @return bool */ public function upsert( @@ -1208,7 +1232,7 @@ interface IDatabase { * @param array $conds Condition array of field names mapped to variables, * ANDed together in the WHERE clause * @param string $fname Calling function name (use __METHOD__) for logs/profiling - * @throws DBUnexpectedError + * @throws DBError */ public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__ @@ -1223,6 +1247,7 @@ interface IDatabase { * @param string $fname Name of the calling function * @throws DBUnexpectedError * @return bool|IResultWrapper + * @throws DBError */ public function delete( $table, $conds, $fname = __METHOD__ ); @@ -1253,6 +1278,7 @@ interface IDatabase { * IDatabase::select() for details. * * @return bool + * @throws DBError */ public function insertSelect( $destTable, $srcTable, $varMap, $conds, $fname = __METHOD__, @@ -1334,6 +1360,7 @@ interface IDatabase { * Determines how long the server has been up * * @return int + * @throws DBError */ public function getServerUptime(); @@ -1374,13 +1401,15 @@ interface IDatabase { * @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 + * @throws DBError */ public function masterPosWait( DBMasterPos $pos, $timeout ); /** * Get the replication position of this replica DB * - * @return DBMasterPos|bool False if this is not a replica DB. + * @return DBMasterPos|bool False if this is not a replica DB + * @throws DBError */ public function getReplicaPos(); @@ -1388,6 +1417,7 @@ interface IDatabase { * Get the position of this master * * @return DBMasterPos|bool False if this is not a master + * @throws DBError */ public function getMasterPos(); @@ -1576,7 +1606,7 @@ interface IDatabase { * Only set the flush flag if you are sure that these warnings are not applicable, * and no explicit transactions are open. * - * @throws DBUnexpectedError + * @throws DBError */ public function commit( $fname = __METHOD__, $flush = '' ); @@ -1590,12 +1620,14 @@ interface IDatabase { * 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). * + * Query, connection, and onTransaction* callback errors will be suppressed and logged. + * * @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 * flush flag if you are sure that it is safe to ignore these warnings in your context. - * @throws DBUnexpectedError + * @throws DBError * @since 1.23 Added $flush parameter */ public function rollback( $fname = __METHOD__, $flush = '' ); @@ -1609,7 +1641,7 @@ interface IDatabase { * 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 + * @throws DBError * @since 1.28 */ public function flushSnapshot( $fname = __METHOD__ ); @@ -1668,6 +1700,7 @@ interface IDatabase { * instead. * * @return int|bool Database replication lag in seconds or false on error + * @throws DBError */ public function getLag(); @@ -1682,6 +1715,7 @@ interface IDatabase { * indication of the staleness of subsequent reads. * * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN) + * @throws DBError * @since 1.27 */ public function getSessionLagStatus(); @@ -1723,6 +1757,7 @@ interface IDatabase { * * @param array $options * @return void + * @throws DBError */ public function setSessionOptions( array $options ); @@ -1741,6 +1776,7 @@ interface IDatabase { * @param string $lockName Name of lock to poll * @param string $method Name of method calling us * @return bool + * @throws DBError * @since 1.20 */ public function lockIsFree( $lockName, $method ); @@ -1754,6 +1790,7 @@ interface IDatabase { * @param string $method Name of the calling method * @param int $timeout Acquisition timeout in seconds * @return bool + * @throws DBError */ public function lock( $lockName, $method, $timeout = 5 ); @@ -1766,8 +1803,10 @@ interface IDatabase { * @param string $method Name of the calling method * * @return int Returns 1 if the lock was released, 0 if the lock was not established - * by this thread (in which case the lock is not released), and NULL if the named - * lock did not exist + * by this thread (in which case the lock is not released), and NULL if the named lock + * did not exist + * + * @throws DBError */ public function unlock( $lockName, $method ); @@ -1789,7 +1828,7 @@ interface IDatabase { * @param string $fname Name of the calling method * @param int $timeout Acquisition timeout in seconds * @return ScopedCallback|null - * @throws DBUnexpectedError + * @throws DBError * @since 1.27 */ public function getScopedLockAndFlush( $lockKey, $fname, $timeout );