<?php
/**
- * @defgroup Database Database
- *
- * This file deals with database interface functions
- * and query specifics/optimisations.
- *
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* http://www.gnu.org/copyleft/gpl.html
*
* @file
- * @ingroup Database
*/
namespace Wikimedia\Rdbms;
use Wikimedia\ScopedCallback;
-use Exception;
use RuntimeException;
use UnexpectedValueException;
use stdClass;
+/**
+ * @defgroup Database Database
+ * This group deals with database interface functions
+ * and query specifics/optimisations.
+ */
/**
* Basic database interface for live and lazy-loaded relation database handles
*
* 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 );
* @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 = []
* @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(
*
* [ '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__,
* @param array|string $join_conds Join conditions
*
* @return stdClass|bool
+ * @throws DBError
*/
public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
$options = [], $join_conds = []
* @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 = []
* @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 = []
* @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__ );
* @param string $index
* @param string $fname
* @return bool|null
+ * @throws DBError
*/
public function indexExists( $table, $index, $fname = __METHOD__ );
* @param string $table
* @param string $fname
* @return bool
+ * @throws DBError
*/
public function tableExists( $table, $fname = __METHOD__ );
* @param array $options Array of options
*
* @return bool
+ * @throws DBError
*/
public function insert( $table, $a, $fname = __METHOD__, $options = [] );
* - 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 = [] );
* @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__ );
* 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(
* @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__
* @param string $fname Name of the calling function
* @throws DBUnexpectedError
* @return bool|IResultWrapper
+ * @throws DBError
*/
public function delete( $table, $conds, $fname = __METHOD__ );
* INSERT SELECT wrapper. Takes data from a SELECT query and inserts it
* into another table.
*
+ * @warning If the insert will use an auto-increment or sequence to
+ * determine the value of a column, this may break replication on
+ * databases using statement-based replication if the SELECT is not
+ * deterministically ordered.
+ *
* @param string $destTable The table name to insert into
* @param string|array $srcTable May be either a table name, or an array of table names
* to include in a join.
* IDatabase::select() for details.
*
* @return bool
+ * @throws DBError
*/
public function insertSelect( $destTable, $srcTable, $varMap, $conds,
$fname = __METHOD__,
* Determines how long the server has been up
*
* @return int
+ * @throws DBError
*/
public function getServerUptime();
* @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();
* Get the position of this master
*
* @return DBMasterPos|bool False if this is not a master
+ * @throws DBError
*/
public function getMasterPos();
* 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 = '' );
* 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 = '' );
* 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__ );
* instead.
*
* @return int|bool Database replication lag in seconds or false on error
+ * @throws DBError
*/
public function getLag();
* 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();
*
* @param array $options
* @return void
+ * @throws DBError
*/
public function setSessionOptions( array $options );
* @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 );
* @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 );
* @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 );
* @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 );
dépôts / lhc / web / wiklou.git / blobdiff