* Fields can be retrieved with $row->fieldname, with fields acting like
* member variables.
*
- * @param $res SQL result object as returned from DatabaseBase::query(), etc.
+ * @param $res ResultWrapper|object as returned from DatabaseBase::query(), etc.
* @return Row object
* @throws DBUnexpectedError Thrown if the database returns an error
*/
protected $mDefaultBigSelects = null;
protected $mSchemaVars = false;
+ protected $preparedArgs;
+
# ------------------------------------------------------------------------------
# Accessors
# ------------------------------------------------------------------------------
/**
* Boolean, controls output of large amounts of debug information.
- * @param $debug:
+ * @param $debug bool|null
* - true to enable debugging
* - false to disable debugging
* - omitted or null to do nothing
* code should use lastErrno() and lastError() to handle the
* situation as appropriate.
*
+ * @param $ignoreErrors bool|null
+ *
* @return The previous value of the flag.
*/
function ignoreErrors( $ignoreErrors = null ) {
* @return The previous table prefix.
*/
function tablePrefix( $prefix = null ) {
- return wfSetVar( $this->mTablePrefix, $prefix, true );
+ return wfSetVar( $this->mTablePrefix, $prefix );
}
/**
* Get properties passed down from the server info array of the load
* balancer.
*
- * @param $name The entry of the info array to get, or null to get the
+ * @param $name string The entry of the info array to get, or null to get the
* whole array
+ *
+ * @return LoadBalancer|null
*/
function getLBInfo( $name = null ) {
if ( is_null( $name ) ) {
*
* @param $name
* @param $value
- * @return void
*/
function setLBInfo( $name, $value = null ) {
if ( is_null( $value ) ) {
/**
* Set lag time in seconds for a fake slave
+ *
+ * @param $lag int
*/
function setFakeSlaveLag( $lag ) {
$this->mFakeSlaveLag = $lag;
/**
* Make this connection a fake master
+ *
+ * @param $enabled bool
*/
function setFakeMaster( $enabled = true ) {
$this->mFakeMaster = $enabled;
/**
* Returns true if this database supports (and uses) cascading deletes
+ *
+ * @return bool
*/
function cascadingDeletes() {
return false;
/**
* Returns true if this database supports (and uses) triggers (e.g. on the page table)
+ *
+ * @return bool
*/
function cleanupTriggers() {
return false;
/**
* Returns true if this database is strict about what can be put into an IP field.
* Specifically, it uses a NULL value instead of an empty string.
+ *
+ * @return bool
*/
function strictIPs() {
return false;
/**
* Returns true if this database uses timestamps rather than integers
+ *
+ * @return bool
*/
function realTimestamps() {
return false;
/**
* Returns true if this database does an implicit sort when doing GROUP BY
+ *
+ * @return bool
*/
function implicitGroupby() {
return true;
/**
* Returns true if this database does an implicit order by when the column has an index
* For example: SELECT page_title FROM page LIMIT 1
+ *
+ * @return bool
*/
function implicitOrderby() {
return true;
/**
* Returns true if this database requires that SELECT DISTINCT queries require that all
ORDER BY expressions occur in the SELECT list per the SQL92 standard
+ *
+ * @return bool
*/
function standardSelectDistinct() {
return true;
/**
* Returns true if this database can do a native search on IP columns
* e.g. this works as expected: .. WHERE rc_ip = '127.42.12.102/32';
+ *
+ * @return bool
*/
function searchableIPs() {
return false;
/**
* Returns true if this database can use functional indexes
+ *
+ * @return bool
*/
function functionalIndexes() {
return false;
return $this->mLastQuery;
}
-
/**
* Returns true if the connection may have been used for write queries.
* Should return true if unsure.
/**
* General read-only accessor
+ *
+ * @param $name string
+ *
+ * @return string
*/
function getProperty( $name ) {
return $this->$name;
}
}
+ /**
+ * Called by serialize. Throw an exception when DB connection is serialized.
+ * This causes problems on some database engines because the connection is
+ * not restored on unserialize.
+ */
+ public function __sleep() {
+ throw new MWException( 'Database serialization may cause problems, since the connection is not restored on wakeup.' );
+ }
+
/**
* Same as new DatabaseMysql( ... ), kept for backward compatibility
* @deprecated since 1.17
set_error_handler( array( $this, 'connectionErrorHandler' ) );
}
+ /**
+ * @return bool|string
+ */
protected function restoreErrorHandler() {
restore_error_handler();
if ( $this->htmlErrors !== false ) {
* The DBMS-dependent part of query()
*
* @param $sql String: SQL query.
- * @return Result object to feed to fetchObject, fetchRow, ...; or false on failure
+ * @return ResultWrapper Result object to feed to fetchObject, fetchRow, ...; or false on failure
*/
protected abstract function doQuery( $sql );
* Determine whether a query writes to the DB.
* Should return true if unsure.
*
+ * @param $sql string
+ *
* @return bool
*/
function isWriteQuery( $sql ) {
# that would delay transaction initializations to once connection
# is really used by application
$sqlstart = substr( $sql, 0, 10 ); // very much worth it, benchmark certified(tm)
- if ( strpos( $sqlstart, "SHOW " ) !== 0 and strpos( $sqlstart, "SET " ) !== 0 )
+ if ( strpos( $sqlstart, "SHOW " ) !== 0 && strpos( $sqlstart, "SET " ) !== 0 )
$this->begin();
}
* database classes. The query wrapper functions (select() etc.) should be
* used instead.
*
+ * @param $sql string
+ * @param $func string
+ *
* @return array
*/
function prepare( $sql, $func = 'DatabaseBase::prepare' ) {
*
* @param $matches Array
* @return String
- * @private
*/
function fillPreparedArg( $matches ) {
switch( $matches[1] ) {
* This function exists for historical reasons, DatabaseBase::update() has a more standard
* calling convention and feature set
*
+ * @param $table string
+ * @param $var
+ * @param $value
+ * @param $cond
+ * @param $fname string
+ *
* @return bool
*/
function set( $table, $var, $value, $cond, $fname = 'DatabaseBase::set' ) {
* @param $options Array Query options
* @param $join_conds Array Join conditions
*
- *
* @param $table string|array
*
* May be either an array of table names, or a single string holding a table
* - If the value is an array, an IN(...) clause will be constructed,
* such that the field name may match any of the elements in the
* array. The elements of the array will be quoted.
- * - If the field name ends with "!", this is taken as a flag which
- * inverts the comparison, allowing NOT IN clauses to be constructed,
- * for example: array( 'user_id!' => array( 1, 2, 3 ) )
*
* Note that expressions are often DBMS-dependent in their syntax.
* DBMS-independent wrappers are provided for constructing several types of
$from = ' FROM ' . implode( ',', $this->tableNamesWithAlias( $table ) );
}
} elseif ( $table != '' ) {
- if ( $table { 0 } == ' ' ) {
+ if ( $table[0] == ' ' ) {
$from = ' FROM ' . $table;
} else {
$from = ' FROM ' . $this->tableName( $table );
* Takes the same arguments as DatabaseBase::select().
*
* @param $table String: table name
- * @param $vars Array: unused
- * @param $conds Array: filters on the table
+ * @param Array|string $vars : unused
+ * @param Array|string $conds : filters on the table
* @param $fname String: function name for profiling
* @param $options Array: options for select
* @return Integer: row count
* Removes most variables from an SQL query and replaces them with X or N for numbers.
* It's only slightly flawed. Don't use for anything important.
*
- * @param $sql String: A SQL Query
+ * @param $sql String A SQL Query
+ *
+ * @return string
*/
static function generalizeSQL( $sql ) {
# This does the same as the regexp below would do, but in such a way
* Usually throws a DBQueryError on failure
* If errors are explicitly ignored, returns NULL on failure
*
+ * @param $table
+ * @param $index
+ * @param $fname string
+ *
* @return bool|null
*/
function indexExists( $table, $index, $fname = 'DatabaseBase::indexExists' ) {
/**
* Query whether a given table exists
*
- * @string table
+ * @param $table string
+ * @param $fname string
*
* @return bool
*/
- function tableExists( $table ) {
+ function tableExists( $table, $fname = __METHOD__ ) {
$table = $this->tableName( $table );
$old = $this->ignoreErrors( true );
- $res = $this->query( "SELECT 1 FROM $table LIMIT 1", __METHOD__ );
+ $res = $this->query( "SELECT 1 FROM $table LIMIT 1", $fname );
$this->ignoreErrors( $old );
return (bool)$res;
}
/**
+ * @todo document
* mysql_field_type() wrapper
*/
function fieldType( $res, $index ) {
*
* @param $table String Table name. This will be passed through
* DatabaseBase::tableName().
- * @param $a Array of rows to insert
+ * @param $a Array of rows to insert
* @param $fname String Calling function name (use __METHOD__) for logs/profiling
* @param $options Array of options
*
/**
* UPDATE wrapper. Takes a condition array and a SET array.
*
- * @param $table String name of the table to UPDATE. This will be passed through
+ * @param $table String|array name of the table to UPDATE. This will be passed through
* DatabaseBase::tableName().
*
- * @param $values Array: An array of values to SET. For each array element,
+ * @param $values Array An array of values to SET. For each array element,
* the key gives the field name, and the value gives the data
* to set that field to. The data will be quoted by
* DatabaseBase::addQuotes().
*
- * @param $conds Array: An array of conditions (WHERE). See
+ * @param $conds Array An array of conditions (WHERE). See
* DatabaseBase::select() for the details of the format of
* condition arrays. Use '*' to update all rows.
*
- * @param $fname String: The function name of the caller (from __METHOD__),
+ * @param $fname String The function name of the caller (from __METHOD__),
* for logging and profiling.
*
- * @param $options Array: An array of UPDATE options, can be:
+ * @param $options Array An array of UPDATE options, can be:
* - IGNORE: Ignore unique key conflicts
* - LOW_PRIORITY: MySQL-specific, see MySQL manual.
* @return Boolean
*/
function update( $table, $values, $conds, $fname = 'DatabaseBase::update', $options = array() ) {
- $table = $this->tableName( $table );
+ if ( is_array( $table ) ) {
+ $table = implode( ',', array_map( array( $this, 'tableName' ), $table ) );
+ } else {
+ $table = $this->tableName( $table );
+ }
$opts = $this->makeUpdateOptions( $options );
$sql = "UPDATE $opts $table SET " . $this->makeList( $values, LIST_SET );
- if ( $conds != '*' ) {
+ if ( $conds !== array() && $conds !== '*' ) {
$sql .= " WHERE " . $this->makeList( $conds, LIST_AND );
}
/**
* Makes an encoded list of strings from an array
* @param $a Array containing the data
- * @param $mode:
+ * @param $mode int Constant
* - LIST_COMMA: comma separated, no field names
* - LIST_AND: ANDed WHERE clause (without the WHERE). See
* the documentation for $conds in DatabaseBase::select().
* - LIST_SET: comma separated with field names, like a SET clause
* - LIST_NAMES: comma separated field names
*
- * In LIST_AND or LIST_OR modes, you can suffix a field with an exclamation
- * mark to generate a 'NOT IN' structure.
- *
- * Example:
- * $db->makeList( array( 'field!' => array( 1,2,3 ) );
- *
- * outputs:
- * 'field' NOT IN ('1', '2', '3' );
-
* @return string
*/
function makeList( $a, $mode = LIST_COMMA ) {
$first = false;
}
- // Support 'NOT IN' by suffixing fieldname with an exclamation mark
- $not = false;
- if( substr($field,-1) == '!' ) {
- $not = true;
- $field = substr($field, 0, -1 );
- }
-
if ( ( $mode == LIST_AND || $mode == LIST_OR ) && is_numeric( $field ) ) {
$list .= "($value)";
} elseif ( ( $mode == LIST_SET ) && is_numeric( $field ) ) {
// Don't necessarily assume the single key is 0; we don't
// enforce linear numeric ordering on other arrays here.
$value = array_values( $value );
-
- $operator = $not ? ' != ' : ' = ';
- $list .= $field . $operator . $this->addQuotes( $value[0] );
+ $list .= $field . " = " . $this->addQuotes( $value[0] );
} else {
- $operator = $not ? ' NOT IN ' : ' IN ';
- $list .= $field . $operator . "(" . $this->makeList( $value ) . ")";
+ $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
}
} elseif ( $value === null ) {
if ( $mode == LIST_AND || $mode == LIST_OR ) {
$list .= "$field IS ";
- if ( $not ) {
- $list .= "NOT ";
- }
} elseif ( $mode == LIST_SET ) {
$list .= "$field = ";
}
* Change the current database
*
* @todo Explain what exactly will fail if this is not overridden.
+ *
+ * @param $db
+ *
* @return bool Success or failure
*/
function selectDB( $db ) {
* when calling query() directly.
*
* @param $name String: database table name
- * @param $quoted Boolean: Automatically pass the table name through
- * addIdentifierQuotes() so that it can be used in a query.
+ * @param $format String One of:
+ * quoted - Automatically pass the table name through addIdentifierQuotes()
+ * so that it can be used in a query.
+ * raw - Do not add identifier quotes to the table name
* @return String: full database name
*/
- function tableName( $name, $quoted = true ) {
+ function tableName( $name, $format = 'quoted' ) {
global $wgSharedDB, $wgSharedPrefix, $wgSharedTables;
# Skip the entire process when we have a string quoted on both ends.
# Note that we check the end so that we will still quote any use of
}
$prefix = $this->mTablePrefix; # Default prefix
+ # A database name has been specified in input. We don't want any
+ # prefixes added.
+ if ( isset( $database ) ) {
+ $prefix = '';
+ }
+
# Note that we use the long format because php will complain in in_array if
# the input is not an array, and will complain in is_array if it is not set.
if ( !isset( $database ) # Don't use shared database if pre selected.
# Quote the $database and $table and apply the prefix if not quoted.
if ( isset( $database ) ) {
- $database = ( !$quoted || $this->isQuotedIdentifier( $database ) ? $database : $this->addIdentifierQuotes( $database ) );
- $prefix = '';
+ $database = ( $format == 'quoted' || $this->isQuotedIdentifier( $database ) ? $database : $this->addIdentifierQuotes( $database ) );
}
$table = "{$prefix}{$table}";
- if ( $quoted && !$this->isQuotedIdentifier( $table ) ) {
+ if ( $format == 'quoted' && !$this->isQuotedIdentifier( $table ) ) {
$table = $this->addIdentifierQuotes( "{$table}" );
}
* extract($dbr->tableNames('user','watchlist'));
* $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
* WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+ *
+ * @return array
*/
public function tableNames() {
$inArray = func_get_args();
* list( $user, $watchlist ) = $dbr->tableNamesN('user','watchlist');
* $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
* WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+ *
+ * @return array
*/
public function tableNamesN() {
$inArray = func_get_args();
* e.g. tableName AS newTableName
*
* @param $name string Table name, see tableName()
- * @param $alias string Alias (optional)
+ * @param $alias string|bool Alias (optional)
* @return string SQL name for aliased table. Will not alias a table to its own name
*/
public function tableNameWithAlias( $name, $alias = false ) {
* Get the aliased table name clause for a FROM clause
* which might have a JOIN and/or USE INDEX clause
*
- * @param $tables array( [alias] => table )
- * @param $use_index array() Same as for select()
- * @param $join_conds array() Same as for select()
+ * @param $tables array ( [alias] => table )
+ * @param $use_index array Same as for select()
+ * @param $join_conds array Same as for select()
* @return string
*/
protected function tableNamesWithUseIndexOrJOIN(
* Since MySQL is the odd one out here the double quotes are our generic
* and we implement backticks in DatabaseMysql.
*
+ * @param $s string
+ *
* @return string
*/
public function addIdentifierQuotes( $s ) {
* was renamed to addIdentifierQuotes.
* @deprecated since 1.18 use addIdentifierQuotes
*
+ * @param $s string
+ *
* @return string
*/
function quote_ident( $s ) {
* WARNING: you should almost never use this function directly,
* instead use buildLike() that escapes everything automatically
* @deprecated since 1.17, warnings in 1.17, removed in ???
+ *
+ * @param $s string
+ *
+ * @return string
*/
public function escapeLike( $s ) {
wfDeprecated( __METHOD__ );
return $this->escapeLikeInternal( $s );
}
+ /**
+ * @param $s string
+ * @return string
+ */
protected function escapeLikeInternal( $s ) {
$s = str_replace( '\\', '\\\\', $s );
$s = $this->strencode( $s );
/**
* Returns a token for buildLike() that denotes a '%' to be used in a LIKE query
*
- * @rerturn LikeMatch
+ * @return LikeMatch
*/
function anyString() {
return new LikeMatch( '%' );
* 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()
+ *
+ * Any implementation of this function should *not* involve reusing
+ * sequence numbers created for rolled-back transactions.
+ * See http://bugs.mysql.com/bug.php?id=30767 for details.
*/
function nextSequenceValue( $seqName ) {
return null;
* to collide. However if you do this, you run the risk of encountering
* errors which wouldn't have occurred in MySQL.
*
- * @param $rows Can be either a single row to insert, or multiple rows,
+ * @param $table String: The table to replace the row(s) in.
+ * @param $rows array Can be either a single row to insert, or multiple rows,
* in the same format as for DatabaseBase::insert()
- * @param $uniqueIndexes is an array of indexes. Each element may be either
+ * @param $uniqueIndexes array is an array of indexes. Each element may be either
* a field name or an array of field names
- *
- * @param $table String: The table to replace the row(s) in.
- * @param $uniqueIndexes Array: An associative array of indexes
- * @param $rows Array: Array of rows to replace
* @param $fname String: Calling function name (use __METHOD__) for logs/profiling
*/
function replace( $table, $uniqueIndexes, $rows, $fname = 'DatabaseBase::replace' ) {
* @param $table Table name
* @param $rows Rows to insert
* @param $fname Caller function name
+ *
+ * @return ResultWrapper
*/
protected function nativeReplace( $table, $rows, $fname ) {
$table = $this->tableName( $table );
/**
* Returns the size of a text field, or -1 for "unlimited"
+ *
+ * @param $table string
+ * @param $field string
+ *
+ * @return int
*/
function textFieldSize( $table, $field ) {
$table = $this->tableName( $table );
* INSERT SELECT wrapper. Takes data from a SELECT query and inserts it
* into another table.
*
- * @param $destTable The table name to insert into
- * @param $srcTable May be either a table name, or an array of table names
+ * @param $destTable string The table name to insert into
+ * @param $srcTable string|array May be either a table name, or an array of table names
* to include in a join.
*
- * @param $varMap must be an associative array of the form
+ * @param $varMap array must be an associative array of the form
* array( 'dest1' => 'source1', ...). Source items may be literals
* rather than field names, but strings should be quoted with
* DatabaseBase::addQuotes()
*
- * @param $conds Condition array. See $conds in DatabaseBase::select() for
+ * @param $conds array Condition array. See $conds in DatabaseBase::select() for
* the details of the format of condition arrays. May be "*" to copy the
* whole table.
*
- * @param $fname The function name of the caller, from __METHOD__
+ * @param $fname string The function name of the caller, from __METHOD__
*
- * @param $insertOptions Options for the INSERT part of the query, see
+ * @param $insertOptions array Options for the INSERT part of the query, see
* DatabaseBase::insert() for details.
- * @param $selectOptions Options for the SELECT part of the query, see
+ * @param $selectOptions array Options for the SELECT part of the query, see
* DatabaseBase::select() for details.
*
* @return ResultWrapper
" FROM $srcTable $useIndex ";
if ( $conds != '*' ) {
- $sql .= ' WHERE ' . $this->makeList( $conds, LIST_AND );
+ if ( is_array( $conds ) ) {
+ $conds = $this->makeList( $conds, LIST_AND );
+ }
+ $sql .= " WHERE $conds";
}
$sql .= " $tailOpts";
* The version provided by default works in MySQL and SQLite. It will very
* likely need to be overridden for most other DBMSes.
*
- * @param $sql String: SQL query we will append the limit too
- * @param $limit Integer: the SQL limit
- * @param $offset Integer the SQL offset (default false)
+ * @param $sql String SQL query we will append the limit too
+ * @param $limit Integer the SQL limit
+ * @param $offset Integer|false the SQL offset (default false)
*
* @return string
*/
. "{$limit} ";
}
+ /**
+ * @param $sql
+ * @param $num
+ * @return string
+ */
function limitResultForUpdate( $sql, $num ) {
return $this->limitResult( $sql, $num, 0 );
}
* Returns whatever the callback function returned on its successful,
* iteration, or false on error, for example if the retry limit was
* reached.
+ *
+ * @return bool
*/
function deadlockLoop() {
$myFname = 'DatabaseBase::deadlockLoop';
/**
* Begin a transaction, committing any previously open transaction
+ *
+ * @param $fname string
*/
function begin( $fname = 'DatabaseBase::begin' ) {
$this->query( 'BEGIN', $fname );
/**
* End a transaction
+ *
+ * @param $fname string
*/
function commit( $fname = 'DatabaseBase::commit' ) {
if ( $this->mTrxLevel ) {
/**
* Rollback a transaction.
* No-op on non-transactional databases.
+ *
+ * @param $fname string
*/
function rollback( $fname = 'DatabaseBase::rollback' ) {
if ( $this->mTrxLevel ) {
* The result is unquoted, and needs to be passed through addQuotes()
* before it can be included in raw SQL.
*
+ * @param $ts string|int
+ *
* @return string
*/
function timestamp( $ts = 0 ) {
* The result is unquoted, and needs to be passed through addQuotes()
* before it can be included in raw SQL.
*
+ * @param $ts string|int
+ *
* @return string
*/
function timestampOrNull( $ts = null ) {
* a wrapper. Nowadays, raw database objects are never exposed to external
* callers, so this is unnecessary in external code. For compatibility with
* old code, ResultWrapper objects are passed through unaltered.
+ *
+ * @param $result bool|ResultWrapper
+ *
+ * @param bool|ResultWrapper
*/
function resultObject( $result ) {
if ( empty( $result ) ) {
/**
* Return aggregated value alias
+ *
+ * @param $valuedata
+ * @param $valuename string
+ *
+ * @return string
*/
function aggregateValue ( $valuedata, $valuename = 'value' ) {
return $valuename;
}
/**
- * Get slave lag.
- * Currently supported only by MySQL
+ * Get slave lag. Currently supported only by MySQL.
+ *
+ * Note that this function will generate a fatal error on many
+ * installations. Most callers should use LoadBalancer::safeGetLag()
+ * instead.
+ *
* @return Database replication lag in seconds
*/
function getLag() {
/**
* Return the maximum number of items allowed in a list, or 0 for unlimited.
*
- * return int
+ * @return int
*/
function maxListLen() {
return 0;
continue;
}
- if ( '-' == $line { 0 } && '-' == $line { 1 } ) {
+ if ( '-' == $line[0] && '-' == $line[1] ) {
continue;
}
}
}
elseif ( !$dollarquote ) {
- if ( ';' == $line { $sl } && ( $sl < 2 || ';' != $line { $sl - 1 } ) ) {
+ if ( ';' == $line[$sl] && ( $sl < 2 || ';' != $line[$sl - 1] ) ) {
$done = true;
$line = substr( $line, 0, $sl );
}
/**
* Get schema variables. If none have been set via setSchemaVars(), then
* use some defaults from the current object.
+ *
+ * @return array
*/
protected function getSchemaVars() {
if ( $this->mSchemaVars ) {
* @param $tableName string
* @param $fName string
* @return bool|ResultWrapper
+ * @since 1.18
*/
public function dropTable( $tableName, $fName = 'DatabaseBase::dropTable' ) {
- if( !$this->tableExists( $tableName ) ) {
+ if( !$this->tableExists( $tableName, $fName ) ) {
return false;
}
$sql = "DROP TABLE " . $this->tableName( $tableName );