PHPXRef 0.7.1 : MediaWiki-1.24.0 : Detail view of Database.php

Interface: DatabaseType - X-Ref

Base interface for all DBMS-specific code. At a bare minimum, all of the
following must be implemented to support MediaWiki

getType() X-Ref

Get the type of the DBMS, as it appears in $wgDBtype.

return: string

open( $server, $user, $password, $dbName ) X-Ref

Open a connection to the database. Usually aborts on failure

param: string $server Database server host
param: string $user Database user name
param: string $password Database user password
param: string $dbName Database name
return: bool

fetchObject( $res ) X-Ref

Fetch the next row from the given result object, in object form.
Fields can be retrieved with $row->fieldname, with fields acting like
member variables.
If no more rows are available, false is returned.

param: ResultWrapper|stdClass $res Object as returned from DatabaseBase::query(), etc.
return: stdClass|bool

fetchRow( $res ) X-Ref

Fetch the next row from the given result object, in associative array
form. Fields are retrieved with $row['fieldname'].
If no more rows are available, false is returned.

param: ResultWrapper $res Result object as returned from DatabaseBase::query(), etc.
return: array|bool

numRows( $res ) X-Ref

Get the number of rows in a result object

param: mixed $res A SQL result
return: int

numFields( $res ) X-Ref

Get the number of fields in a result object

param: mixed $res A SQL result
return: int

fieldName( $res, $n ) X-Ref

Get a field name in a result object

param: mixed $res A SQL result
param: int $n
return: string

insertId() X-Ref

Get the inserted value of an auto-increment row

The value inserted should be fetched from nextSequenceValue()

Example:
$id = $dbw->nextSequenceValue( 'page_page_id_seq' );
$dbw->insert( 'page', array( 'page_id' => $id ) );
$id = $dbw->insertId();

return: int

dataSeek( $res, $row ) X-Ref

Change the position of the cursor in a result object

param: mixed $res A SQL result
param: int $row

lastErrno() X-Ref

Get the last error number

return: int

lastError() X-Ref

Get a description of the last error

return: string

fieldInfo( $table, $field ) X-Ref

mysql_fetch_field() wrapper
Returns false if the field doesn't exist

param: string $table Table name
param: string $field Field name
return: Field

indexInfo( $table, $index, $fname = __METHOD__ ) X-Ref

Get information about an index into an object

param: string $table Table name
param: string $index Index name
param: string $fname Calling function name
return: mixed Database-specific index description class or false if the index does not exist

affectedRows() X-Ref

Get the number of rows affected by the last write query

return: int

strencode( $s ) X-Ref

Wrapper for addslashes()

param: string $s String to be slashed.
return: string Slashed string.

getSoftwareLink() X-Ref

Returns a wikitext link to the DB's website, e.g.,
return "[http://www.mysql.com/ MySQL]";
Should at least contain plain text, if for some reason
your database has no website.

return: string Wikitext of a link to the server software's web site

getServerVersion() X-Ref

A string describing the current software version, like from
mysql_get_server_info().

return: string Version information from the database server.

getServerInfo() X-Ref

A string describing the current software version, and possibly
other details in a user-friendly way. Will be listed on Special:Version, etc.
Use getServerVersion() to get machine-friendly information.

return: string Version information from the database server

Interface: IDatabase - X-Ref

Interface for classes that implement or wrap DatabaseBase

getServerInfo() X-Ref

getDelimiter() X-Ref

return: string Command delimiter used by this database engine

debug( $debug = null ) X-Ref

Boolean, controls output of large amounts of debug information.

param: bool|null $debug
return: bool|null Previous value of the flag

bufferResults( $buffer = null ) X-Ref

Turns buffering of SQL result sets on (true) or off (false). Default is
"on".

Unbuffered queries are very troublesome in MySQL:

- If another query is executed while the first query is being read
out, the first query is killed. This means you can't call normal
MediaWiki functions while you are reading an unbuffered query result
from a normal wfGetDB() connection.

- Unbuffered queries cause the MySQL server to use large amounts of
memory and to hold broad locks which block other queries.

If you want to limit client-side memory, it's almost always better to
split up queries into batches using a LIMIT clause than to switch off
buffering.

param: null|bool $buffer
return: null|bool The previous value of the flag

ignoreErrors( $ignoreErrors = null ) X-Ref

Turns on (false) or off (true) the automatic generation and sending
of a "we're sorry, but there has been a database error" page on
database errors. Default is on (false). When turned off, the
code should use lastErrno() and lastError() to handle the
situation as appropriate.

Do not use this function outside of the Database classes.

param: null|bool $ignoreErrors
return: bool The previous value of the flag.

trxLevel() X-Ref

Gets the current transaction level.

Historically, transactions were allowed to be "nested". This is no
longer supported, so this function really only returns a boolean.

return: int The previous value

errorCount( $count = null ) X-Ref

Get/set the number of errors logged. Only useful when errors are ignored

param: int $count The count to set, or omitted to leave it unchanged.
return: int The error count

tablePrefix( $prefix = null ) X-Ref

Get/set the table prefix.

param: string $prefix The table prefix to set, or omitted to leave it unchanged.
return: string The previous table prefix.

dbSchema( $schema = null ) X-Ref

Get/set the db schema.

param: string $schema The database schema to set, or omitted to leave it unchanged.
return: string The previous db schema.

setFileHandle( $fh ) X-Ref

Set the filehandle to copy write statements to.

param: resource $fh File handle

getLBInfo( $name = null ) X-Ref

Get properties passed down from the server info array of the load
balancer.

param: string $name The entry of the info array to get, or null to get the
return: array|mixed|null

setLBInfo( $name, $value = null ) X-Ref

Set the LB info array, or a member of it. If called with one parameter,
the LB info array is set to that parameter. If it is called with two
parameters, the member with the given name is set to the given value.

param: string $name
param: array $value

setFakeSlaveLag( $lag ) X-Ref

Set lag time in seconds for a fake slave

param: mixed $lag Valid values for this parameter are determined by the

setFakeMaster( $enabled = true ) X-Ref

Make this connection a fake master

param: bool $enabled

cascadingDeletes() X-Ref

Returns true if this database supports (and uses) cascading deletes

return: bool

cleanupTriggers() X-Ref

Returns true if this database supports (and uses) triggers (e.g. on the page table)

return: bool

strictIPs() X-Ref

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

realTimestamps() X-Ref

Returns true if this database uses timestamps rather than integers

return: bool

implicitGroupby() X-Ref

Returns true if this database does an implicit sort when doing GROUP BY

return: bool

implicitOrderby() X-Ref

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

searchableIPs() X-Ref

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

functionalIndexes() X-Ref

Returns true if this database can use functional indexes

return: bool

lastQuery() X-Ref

Return the last query that went through DatabaseBase::query()

return: string

doneWrites() X-Ref

Returns true if the connection may have been used for write queries.
Should return true if unsure.

return: bool

lastDoneWrites() X-Ref

Returns the last time the connection may have been used for write queries.
Should return a timestamp if unsure.

return: int|float UNIX timestamp or false

writesOrCallbacksPending() X-Ref

Returns true if there is a transaction open with possible write
queries or transaction pre-commit/idle callbacks waiting on it to finish.

return: bool

isOpen() X-Ref

Is a connection to the database open?

return: bool

setFlag( $flag ) X-Ref

Set a flag for this connection

param: int $flag DBO_* constants from Defines.php:

clearFlag( $flag ) X-Ref

Clear a flag for this connection

param: int $flag DBO_* constants from Defines.php:

getFlag( $flag ) X-Ref

Returns a boolean whether the flag $flag is set for this connection

param: int $flag DBO_* constants from Defines.php:
return: bool

getProperty( $name ) X-Ref

General read-only accessor

param: string $name
return: string

getWikiID() X-Ref

return: string

getSqlFilePath( $filename ) X-Ref

Return a path to the DBMS-specific SQL file if it exists,
otherwise default SQL file

param: string $filename
return: string

getSchemaPath() X-Ref

Return a path to the DBMS-specific schema file,
otherwise default to tables.sql

return: string

getUpdateKeysPath() X-Ref

Return a path to the DBMS-specific update key file,
otherwise default to update-keys.sql

return: string

__construct( $params = null ) X-Ref

Constructor.

FIXME: It is possible to construct a Database object with no associated
connection object, by specifying no parameters to __construct(). This
feature is deprecated and should be removed.

DatabaseBase subclasses should not be constructed directly in external
code. DatabaseBase::factory() should be used instead.

param: array $params Parameters passed from DatabaseBase::factory()

__sleep() X-Ref

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.

factory( $dbType, $p = array() X-Ref

Given a DB type, construct the name of the appropriate child class of
DatabaseBase. This is designed to replace all of the manual stuff like:
$class = 'Database' . ucfirst( strtolower( $dbType ) );
as well as validate against the canonical list of DB types we have

This factory function is mostly useful for when you need to connect to a
database other than the MediaWiki default (such as for external auth,
an extension, et cetera). Do not use this to connect to the MediaWiki
database. Example uses in core:
param: string $dbType A possible DB type
param: array $p An array of options to pass to the constructor.
return: DatabaseBase|null DatabaseBase subclass or null

installErrorHandler() X-Ref

No description

restoreErrorHandler() X-Ref

return: bool|string

connectionErrorHandler( $errno, $errstr ) X-Ref

param: int $errno
param: string $errstr

close() X-Ref

Closes a database connection.
if it is open : commits any open transactions

return: bool Operation success. true if already closed.

reportConnectionError( $error = 'Unknown error' ) X-Ref

param: string $error Fallback error message, used if none is given by DB

isWriteQuery( $sql ) X-Ref

Determine whether a query writes to the DB.
Should return true if unsure.

param: string $sql
return: bool

query( $sql, $fname = __METHOD__, $tempIgnore = false ) X-Ref

Run an SQL query and return the result. Normally throws a DBQueryError
on failure. If errors are ignored, returns false instead.

In new code, the query wrappers select(), insert(), update(), delete(),
etc. should be used where possible, since they give much better DBMS
independence and automatically quote or validate user input in a variety
of contexts. This function is generally only useful for queries which are
explicitly DBMS-dependent and are unsupported by the query wrappers, such
as CREATE TABLE.

However, the query wrappers themselves should call this function.

param: string $sql SQL query
param: string $fname Name of the calling function, for profiling/SHOW PROCESSLIST
param: bool $tempIgnore Whether to avoid throwing an exception on errors...
return: bool|ResultWrapper True for a successful write query, ResultWrapper object

reportQueryError( $error, $errno, $sql, $fname, $tempIgnore = false ) X-Ref

Report a query error. Log the error, and if neither the object ignore
flag nor the $tempIgnore flag is set, throw a DBQueryError.

param: string $error
param: int $errno
param: string $sql
param: string $fname
param: bool $tempIgnore

prepare( $sql, $func = 'DatabaseBase::prepare' ) X-Ref

Intended to be compatible with the PEAR::DB wrapper functions.
http://pear.php.net/manual/en/package.database.db.intro-execute.php

? = scalar value, quoted as necessary
! = raw SQL bit (a function for instance)
& = filename; reads the file and inserts as a blob
(we don't use this though...)

param: string $sql
param: string $func
return: array

freePrepared( $prepared ) X-Ref

Free a prepared query, generated by prepare().

param: string $prepared

execute( $prepared, $args = null ) X-Ref

Execute a prepared query with the various arguments

param: string $prepared The prepared sql
param: mixed $args Either an array here, or put scalars as varargs
return: ResultWrapper

fillPrepared( $preparedQuery, $args ) X-Ref

For faking prepared SQL statements on DBs that don't support it directly.

param: string $preparedQuery A 'preparable' SQL statement
param: array $args Array of Arguments to fill it with
return: string Executable SQL

fillPreparedArg( $matches ) X-Ref

preg_callback func for fillPrepared()
The arguments should be in $this->preparedArgs and must not be touched
while we're doing this.

param: array $matches
return: string

freeResult( $res ) X-Ref

Free a result object returned by query() or select(). It's usually not
necessary to call this, just use unset() or let the variable holding
the result object go out of scope.

param: mixed $res A SQL result

selectField( $table, $var, $cond = '', $fname = __METHOD__,$options = array() X-Ref

A SELECT wrapper which returns a single field from a single result row.

Usually throws a DBQueryError on failure. If errors are explicitly
ignored, returns false on failure.

If no result rows are returned from the query, false is returned.

param: string|array $table Table name. See DatabaseBase::select() for details.
param: string $var The field name to select. This must be a valid SQL
param: string|array $cond The condition array. See DatabaseBase::select() for details.
param: string $fname The function name of the caller.
param: string|array $options The query options. See DatabaseBase::select() for details.
return: bool|mixed The value from the field, or false on failure.

makeSelectOptions( $options ) X-Ref

Returns an optional USE INDEX clause to go after the table, and a
string to go at the end of the query.

param: array $options Associative array of options to be turned into
return: array

makeGroupByWithHaving( $options ) X-Ref

Returns an optional GROUP BY with an optional HAVING

param: array $options Associative array of options
return: string

makeOrderBy( $options ) X-Ref

Returns an optional ORDER BY

param: array $options Associative array of options
return: string

select( $table, $vars, $conds = '', $fname = __METHOD__,$options = array() X-Ref

Execute a SELECT query constructed using the various parameters provided.
See below for full details of the parameters.

param: string|array $table Table name
param: string|array $vars Field names
param: string|array $conds Conditions
param: string $fname Caller function name
param: array $options Query options
param: array $join_conds Join conditions
param: string|array $table
param: string|array $vars
param: string|array $conds
param: string|array $options
param: string|array $join_conds
return: ResultWrapper|bool If the query returned no rows, a ResultWrapper

selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,$options = array() X-Ref

The equivalent of DatabaseBase::select() except that the constructed SQL
is returned, instead of being immediately executed. This can be useful for
doing UNION queries, where the SQL text of each query is needed. In general,
however, callers outside of Database classes should just use select().

param: string|array $table Table name
param: string|array $vars Field names
param: string|array $conds Conditions
param: string $fname Caller function name
param: string|array $options Query options
param: string|array $join_conds Join conditions
return: string SQL query string.

selectRow( $table, $vars, $conds, $fname = __METHOD__,$options = array() X-Ref

Single row SELECT wrapper. Equivalent to DatabaseBase::select(), except
that a single row object is returned. If the query returns no rows,
false is returned.

param: string|array $table Table name
param: string|array $vars Field names
param: array $conds Conditions
param: string $fname Caller function name
param: string|array $options Query options
param: array|string $join_conds Join conditions
return: stdClass|bool

estimateRowCount($table, $vars = '*', $conds = '', $fname = __METHOD__, $options = array() X-Ref

Estimate the number of rows in dataset

MySQL allows you to estimate the number of rows that would be returned
by a SELECT query, using EXPLAIN SELECT. The estimate is provided using
index cardinality statistics, and is notoriously inaccurate, especially
when large numbers of rows have recently been added or deleted.

For DBMSs that don't support fast result size estimation, this function
will actually perform the SELECT COUNT(*).

Takes the same arguments as DatabaseBase::select().

param: string $table Table name
param: string $vars Unused
param: array|string $conds Filters on the table
param: string $fname Function name for profiling
param: array $options Options for select
return: int Row count

selectRowCount($table, $vars = '*', $conds = '', $fname = __METHOD__, $options = array() X-Ref

Get the number of rows in dataset

This is useful when trying to do COUNT(*) but with a LIMIT for performance.

Takes the same arguments as DatabaseBase::select().

param: string $table Table name
param: string $vars Unused
param: array|string $conds Filters on the table
param: string $fname Function name for profiling
param: array $options Options for select
return: int Row count

generalizeSQL( $sql ) X-Ref

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: string $sql A SQL Query
return: string

fieldExists( $table, $field, $fname = __METHOD__ ) X-Ref

Determines whether a field exists in a table

param: string $table Table name
param: string $field Filed to check on that table
param: string $fname Calling function name (optional)
return: bool Whether $table has filed $field

indexExists( $table, $index, $fname = __METHOD__ ) X-Ref

Determines whether an index exists
Usually throws a DBQueryError on failure
If errors are explicitly ignored, returns NULL on failure

param: string $table
param: string $index
param: string $fname
return: bool|null

tableExists( $table, $fname = __METHOD__ ) X-Ref

Query whether a given table exists

param: string $table
param: string $fname
return: bool

indexUnique( $table, $index ) X-Ref

Determines if a given index is unique

param: string $table
param: string $index
return: bool

makeInsertOptions( $options ) X-Ref

Helper for DatabaseBase::insert().

param: array $options
return: string

insert( $table, $a, $fname = __METHOD__, $options = array() X-Ref

INSERT wrapper, inserts an array into a table.

$a may be either:

- A single associative array. The array keys are the field names, and
the values are the values to insert. The values are treated as data
and will be quoted appropriately. If NULL is inserted, this will be
converted to a database NULL.
- An array with numeric keys, holding a list of associative arrays.
This causes a multi-row INSERT on DBMSs that support it. The keys in
each subarray must be identical to each other, and in the same order.

Usually throws a DBQueryError on failure. If errors are explicitly ignored,
returns success.

$options is an array of options, with boolean options encoded as values
with numeric keys, in the same style as $options in
DatabaseBase::select(). Supported options are:

- IGNORE: Boolean: if present, duplicate key errors are ignored, and
any rows which cause duplicate key errors are not inserted. It's
possible to determine how many rows were successfully inserted using
DatabaseBase::affectedRows().

param: string $table Table name. This will be passed through
param: array $a Array of rows to insert
param: string $fname Calling function name (use __METHOD__) for logs/profiling
param: array $options Array of options
return: bool

makeUpdateOptionsArray( $options ) X-Ref

Make UPDATE options array for DatabaseBase::makeUpdateOptions

param: array $options
return: array

makeUpdateOptions( $options ) X-Ref

Make UPDATE options for the DatabaseBase::update function

param: array $options The options passed to DatabaseBase::update
return: string

update( $table, $values, $conds, $fname = __METHOD__, $options = array() X-Ref

UPDATE wrapper. Takes a condition array and a SET array.

param: string $table Name of the table to UPDATE. This will be passed through
param: array $values An array of values to SET. For each array element,
param: array $conds An array of conditions (WHERE). See
param: string $fname The function name of the caller (from __METHOD__),
param: array $options An array of UPDATE options, can be:
return: bool

makeList( $a, $mode = LIST_COMMA ) X-Ref

Makes an encoded list of strings from an array

param: array $a Containing the data
param: int $mode Constant
return: string

makeWhereFrom2d( $data, $baseKey, $subKey ) X-Ref

Build a partial where clause from a 2-d array such as used for LinkBatch.
The keys on each level may be either integers or strings.

param: array $data Organized as 2-d
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

aggregateValue( $valuedata, $valuename = 'value' ) X-Ref

Return aggregated value alias

param: array $valuedata
param: string $valuename
return: string

bitNot( $field ) X-Ref

param: string $field
return: string

bitAnd( $fieldLeft, $fieldRight ) X-Ref

param: string $fieldLeft
param: string $fieldRight
return: string

bitOr( $fieldLeft, $fieldRight ) X-Ref

param: string $fieldLeft
param: string $fieldRight
return: string

buildConcat( $stringList ) X-Ref

Build a concatenation list to feed into a SQL query

param: array $stringList List of raw SQL expressions; caller is
return: string

buildGroupConcatField($delim, $table, $field, $conds = '', $join_conds = array() X-Ref

Build a GROUP_CONCAT or equivalent statement for a query.

This is useful for combining a field for several rows into a single string.
NULL values will not appear in the output, duplicated values will appear,
and the resulting delimiter-separated values have no defined sort order.
Code using the results may need to use the PHP unique() or sort() methods.

param: string $delim Glue to bind the results together
param: string|array $table Table name
param: string $field Field name
param: string|array $conds Conditions
param: string|array $join_conds Join conditions
return: string SQL text

selectDB( $db ) X-Ref

Change the current database

param: string $db
return: bool Success or failure

getDBname() X-Ref

Get the current DB name

return: string

getServer() X-Ref

Get the server hostname or IP address

return: string

tableName( $name, $format = 'quoted' ) X-Ref

Format a table name ready for use in constructing an SQL query

This does two important things: it quotes the table names to clean them up,
and it adds a table prefix if only given a table name with no quotes.

All functions of this object which require a table name call this function
themselves. Pass the canonical name to such functions. This is only needed
when calling query() directly.

param: string $name Database table name
param: string $format One of:
return: string Full database name

tableNames() X-Ref

Fetch a number of table names into an array
This is handy when you need to construct SQL for joins

Example:
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

tableNamesN() X-Ref

Fetch a number of table names into an zero-indexed numerical array
This is handy when you need to construct SQL for joins

Example:
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

tableNameWithAlias( $name, $alias = false ) X-Ref

Get an aliased table name
e.g. tableName AS newTableName

param: string $name Table name, see tableName()
param: string|bool $alias Alias (optional)
return: string SQL name for aliased table. Will not alias a table to its own name

tableNamesWithAlias( $tables ) X-Ref

Gets an array of aliased table names

param: array $tables Array( [alias] => table )
return: string[] See tableNameWithAlias()

fieldNameWithAlias( $name, $alias = false ) X-Ref

Get an aliased field name
e.g. fieldName AS newFieldName

param: string $name Field name
param: string|bool $alias Alias (optional)
return: string SQL name for aliased field. Will not alias a field to its own name

fieldNamesWithAlias( $fields ) X-Ref

Gets an array of aliased field names

param: array $fields Array( [alias] => field )
return: string[] See fieldNameWithAlias()

tableNamesWithUseIndexOrJOIN($tables, $use_index = array() X-Ref

Get the aliased table name clause for a FROM clause
which might have a JOIN and/or USE INDEX clause

param: array $tables ( [alias] => table )
param: array $use_index Same as for select()
param: array $join_conds Same as for select()
return: string

indexName( $index ) X-Ref

Get the name of an index in a given table

param: string $index
return: string

addQuotes( $s ) X-Ref

Adds quotes and backslashes.

param: string $s
return: string

addIdentifierQuotes( $s ) X-Ref

Quotes an identifier using `backticks` or "double quotes" depending on the database type.
MySQL uses `backticks` while basically everything else uses double quotes.
Since MySQL is the odd one out here the double quotes are our generic
and we implement backticks in DatabaseMysql.

param: string $s
return: string

isQuotedIdentifier( $name ) X-Ref

Returns if the given identifier looks quoted or not according to
the database convention for quoting identifiers .

param: string $name
return: bool

escapeLikeInternal( $s ) X-Ref

param: string $s
return: string

buildLike() X-Ref

LIKE statement wrapper, receives a variable-length argument list with
parts of pattern to match containing either string literals that will be
escaped or tokens returned by anyChar() or anyString(). Alternatively,
the function could be provided with an array of aforementioned
parameters.

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() );
$query .= $dbr->buildLike( $pattern );

return: string Fully built LIKE statement

anyChar() X-Ref

Returns a token for buildLike() that denotes a '_' to be used in a LIKE query

return: LikeMatch

anyString() X-Ref

Returns a token for buildLike() that denotes a '%' to be used in a LIKE query

return: LikeMatch

nextSequenceValue( $seqName ) X-Ref

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.
param: string $seqName
return: null|int

useIndexClause( $index ) X-Ref

USE INDEX clause. Unlikely to be useful for anything but MySQL. This
is only needed because a) MySQL must be as efficient as possible due to
its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
which index to pick. Anyway, other databases might have different
indexes on a given table. So don't bother overriding this unless you're
MySQL.

param: string $index
return: string

replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) X-Ref

REPLACE query wrapper.

REPLACE is a very handy MySQL extension, which functions like an INSERT
except that when there is a duplicate key error, the old row is deleted
and the new row is inserted in its place.

We simulate this with standard SQL with a DELETE followed by INSERT. To
perform the delete, we need to know what the unique indexes are so that
we know how to find the conflicting rows.

It may be more efficient to leave off unique indexes which are unlikely
to collide. However if you do this, you run the risk of encountering
errors which wouldn't have occurred in MySQL.

param: string $table The table to replace the row(s) in.
param: array $uniqueIndexes Is an array of indexes. Each element may be either
param: array $rows Can be either a single row to insert, or multiple rows,
param: string $fname Calling function name (use __METHOD__) for logs/profiling

nativeReplace( $table, $rows, $fname ) X-Ref

REPLACE query wrapper for MySQL and SQLite, which have a native REPLACE
statement.

param: string $table Table name
param: array|string $rows Row(s) to insert
param: string $fname Caller function name
return: ResultWrapper

upsert( $table, array $rows, array $uniqueIndexes, array $set,$fname = __METHOD__) X-Ref

INSERT ON DUPLICATE KEY UPDATE wrapper, upserts an array into a table.

This updates any conflicting rows (according to the unique indexes) using
the provided SET clause and inserts any remaining (non-conflicted) rows.

$rows may be either:
- A single associative array. The array keys are the field names, and
the values are the values to insert. The values are treated as data
and will be quoted appropriately. If NULL is inserted, this will be
converted to a database NULL.
- An array with numeric keys, holding a list of associative arrays.
This causes a multi-row INSERT on DBMSs that support it. The keys in
each subarray must be identical to each other, and in the same order.

It may be more efficient to leave off unique indexes which are unlikely
to collide. However if you do this, you run the risk of encountering
errors which wouldn't have occurred in MySQL.

Usually throws a DBQueryError on failure. If errors are explicitly ignored,
returns success.

param: string $table Table name. This will be passed through DatabaseBase::tableName().
param: array $rows A single row or list of rows to insert
param: array $uniqueIndexes List of single field names or field name tuples
param: array $set An array of values to SET. For each array element, the
param: string $fname Calling function name (use __METHOD__) for logs/profiling
return: bool

deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,$fname = __METHOD__) X-Ref

DELETE where the condition is a join.

MySQL overrides this to use a multi-table DELETE syntax, in other databases
we use sub-selects

For safety, an empty $conds will not delete everything. If you want to
delete all rows where the join condition matches, set $conds='*'.

DO NOT put the join condition in $conds.

param: string $delTable The table to delete from.
param: string $joinTable The other table.
param: string $delVar The variable to join on, in the first table.
param: string $joinVar The variable to join on, in the second table.
param: array $conds Condition array of field names mapped to variables,
param: string $fname Calling function name (use __METHOD__) for logs/profiling

textFieldSize( $table, $field ) X-Ref

Returns the size of a text field, or -1 for "unlimited"

param: string $table
param: string $field
return: int

lowPriorityOption() X-Ref

A string to insert into queries to show that they're low-priority, like
MySQL's LOW_PRIORITY. If no such feature exists, return an empty
string and nothing bad should happen.

return: string Returns the text of the low priority option if it is

delete( $table, $conds, $fname = __METHOD__ ) X-Ref

DELETE query wrapper.

param: array $table Table name
param: string|array $conds Array of conditions. See $conds in DatabaseBase::select()
param: string $fname Name of the calling function
return: bool|ResultWrapper

insertSelect( $destTable, $srcTable, $varMap, $conds,$fname = __METHOD__,$insertOptions = array() X-Ref

INSERT SELECT wrapper. Takes data from a SELECT query and inserts it
into another table.

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
param: array $varMap Must be an associative array of the form
param: array $conds Condition array. See $conds in DatabaseBase::select() for
param: string $fname The function name of the caller, from __METHOD__
param: array $insertOptions Options for the INSERT part of the query, see
param: array $selectOptions Options for the SELECT part of the query, see
return: ResultWrapper

limitResult( $sql, $limit, $offset = false ) X-Ref

Construct a LIMIT query with optional offset. This is used for query
pages. The SQL should be adjusted so that only the first $limit rows
are returned. If $offset is provided as well, then the first $offset
rows should be discarded, and the next $limit rows should be returned.
If the result of the query is not ordered, then the rows to be returned
are theoretically arbitrary.

$sql is expected to be a SELECT, if that makes a difference.

The version provided by default works in MySQL and SQLite. It will very
likely need to be overridden for most other DBMSes.

param: string $sql SQL query we will append the limit too
param: int $limit The SQL limit
param: int|bool $offset The SQL offset (default false)
return: string

unionSupportsOrderAndLimit() X-Ref

Returns true if current database backend supports ORDER BY or LIMIT for separate subqueries
within the UNION construct.

return: bool

unionQueries( $sqls, $all ) X-Ref

Construct a UNION query
This is used for providing overload point for other DB abstractions
not compatible with the MySQL syntax.

param: array $sqls SQL statements to combine
param: bool $all Use UNION ALL
return: string SQL fragment

conditional( $cond, $trueVal, $falseVal ) X-Ref

Returns an SQL expression for a simple conditional. This doesn't need
to be overridden unless CASE isn't supported in your DBMS.

param: string|array $cond SQL expression which will result in a boolean value
param: string $trueVal SQL expression to return if true
param: string $falseVal SQL expression to return if false
return: string SQL fragment

strreplace( $orig, $old, $new ) X-Ref

Returns a comand for str_replace function in SQL query.
Uses REPLACE() in MySQL

param: string $orig Column to modify
param: string $old Column to seek
param: string $new Column to replace with
return: string

getServerUptime() X-Ref

Determines how long the server has been up
STUB

return: int

wasDeadlock() X-Ref

Determines if the last failure was due to a deadlock
STUB

return: bool

wasLockTimeout() X-Ref

Determines if the last failure was due to a lock timeout
STUB

return: bool

wasErrorReissuable() X-Ref

Determines if the last query error was something that should be dealt
with by pinging the connection and reissuing the query.
STUB

return: bool

wasReadOnlyError() X-Ref

Determines if the last failure was due to the database being read-only.
STUB

return: bool

deadlockLoop() X-Ref

Perform a deadlock-prone transaction.

This function invokes a callback function to perform a set of write
queries. If a deadlock occurs during the processing, the transaction
will be rolled back and the callback function will be called again.

Usage:
$dbw->deadlockLoop( callback, ... );

Extra arguments are passed through to the specified callback function.

Returns whatever the callback function returned on its successful,
iteration, or false on error, for example if the retry limit was
reached.

return: bool

masterPosWait( DBMasterPos $pos, $timeout ) X-Ref

Wait for the slave to catch up to a given master position.

param: DBMasterPos $pos
param: int $timeout The maximum number of seconds to wait for
return: int Zero if the slave was past that position already,

getSlavePos() X-Ref

Get the replication position of this slave

return: DBMasterPos|bool False if this is not a slave.

getMasterPos() X-Ref

Get the position of this master

return: DBMasterPos|bool False if this is not a master

onTransactionIdle( $callback ) X-Ref

Run an anonymous function as soon as there is no transaction pending.
If there is a transaction and it is rolled back, then the callback is cancelled.
Queries in the function will run in AUTO-COMMIT mode unless there are begin() calls.
Callbacks must commit any transactions that they begin.

This is useful for updates to different systems or when separate transactions are needed.
For example, one might want to enqueue jobs into a system outside the database, but only
after the database is updated so that the jobs will see the data when they actually run.
It can also be used for updates that easily cause deadlocks if locks are held too long.

param: callable $callback

onTransactionPreCommitOrIdle( $callback ) X-Ref

Run an anonymous function before the current transaction commits or now if there is none.
If there is a transaction and it is rolled back, then the callback is cancelled.
Callbacks must not start nor commit any transactions.

This is useful for updates that easily cause deadlocks if locks are held too long
but where atomicity is strongly desired for these updates and some related updates.

param: callable $callback

runOnTransactionIdleCallbacks() X-Ref

Actually any "on transaction idle" callbacks.

runOnTransactionPreCommitCallbacks() X-Ref

Actually any "on transaction pre-commit" callbacks.

startAtomic( $fname = __METHOD__ ) X-Ref

Begin an atomic section of statements

If a transaction has been started already, just keep track of the given
section name to make sure the transaction is not committed pre-maturely.
This function can be used in layers (with sub-sections), so use a stack
to keep track of the different atomic sections. If there is no transaction,
start one implicitly.

The goal of this function is to create an atomic section of SQL queries
without having to start a new transaction if it already exists.

Atomic sections are more strict than transactions. With transactions,
attempting to begin a new transaction when one is already running results
in MediaWiki issuing a brief warning and doing an implicit commit. All
atomic levels *must* be explicitly closed using DatabaseBase::endAtomic(),
and any database transactions cannot be began or committed until all atomic
levels are closed. There is no such thing as implicitly opening or closing
an atomic section.

param: string $fname

endAtomic( $fname = __METHOD__ ) X-Ref

Ends an atomic section of SQL statements

Ends the next section of atomic SQL statements and commits the transaction
if necessary.

param: string $fname

begin( $fname = __METHOD__ ) X-Ref

Begin a transaction. If a transaction is already in progress,
that transaction will be committed before the new transaction is started.

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.

Nesting of transactions is not supported. Attempts to nest transactions
will cause a warning, unless the current transaction was started
automatically because of the DBO_TRX flag.

param: string $fname

doBegin( $fname ) X-Ref

Issues the BEGIN command to the database server.

param: string $fname

commit( $fname = __METHOD__, $flush = '' ) X-Ref

Commits a transaction previously started using begin().
If no transaction is in progress, a warning is issued.

Nesting of transactions is not supported.

param: string $fname
param: string $flush Flush flag, set to 'flush' to disable warnings about

doCommit( $fname ) X-Ref

Issues the COMMIT command to the database server.

param: string $fname

rollback( $fname = __METHOD__, $flush = '' ) X-Ref

Rollback a transaction previously started using begin().
If no transaction is in progress, a warning is issued.

No-op on non-transactional databases.

param: string $fname
param: string $flush Flush flag, set to 'flush' to disable warnings about

doRollback( $fname ) X-Ref

Issues the ROLLBACK command to the database server.

param: string $fname

duplicateTableStructure( $oldName, $newName, $temporary = false,$fname = __METHOD__) X-Ref

Creates a new table with structure copied from existing table
Note that unlike most database abstraction functions, this function does not
automatically append database prefix, because it works at a lower
abstraction level.
The table names passed to this function shall not be quoted (this
function calls addIdentifierQuotes when needed).

param: string $oldName Name of table whose structure should be copied
param: string $newName Name of table to be created
param: bool $temporary Whether the new table should be temporary
param: string $fname Calling function name
return: bool True if operation was successful

listTables( $prefix = null, $fname = __METHOD__ ) X-Ref

List all tables on the database

param: string $prefix Only show tables with this prefix, e.g. mw_
param: string $fname Calling function name

clearViewsCache() X-Ref

Reset the views process cache set by listViews()

listViews( $prefix = null, $fname = __METHOD__ ) X-Ref

Lists all the VIEWs in the database

For caching purposes the list of all views should be stored in
$this->allViews. The process cache can be cleared with clearViewsCache()

param: string $prefix Only show VIEWs with this prefix, eg. unit_test_
param: string $fname Name of calling function

isView( $name ) X-Ref

Differentiates between a TABLE and a VIEW

param: string $name Name of the database-structure to test.

timestamp( $ts = 0 ) X-Ref

Convert a timestamp in one of the formats accepted by wfTimestamp()
to the format used for inserting into timestamp fields in this DBMS.

The result is unquoted, and needs to be passed through addQuotes()
before it can be included in raw SQL.

param: string|int $ts
return: string

timestampOrNull( $ts = null ) X-Ref

Convert a timestamp in one of the formats accepted by wfTimestamp()
to the format used for inserting into timestamp fields in this DBMS. If
NULL is input, it is passed through, allowing NULL values to be inserted
into timestamp fields.

The result is unquoted, and needs to be passed through addQuotes()
before it can be included in raw SQL.

param: string|int $ts
return: string

resultObject( $result ) X-Ref

Take the result from a query, and wrap it in a ResultWrapper if
necessary. Boolean values are passed through as is, to indicate success
of write queries or failure.

Once upon a time, DatabaseBase::query() returned a bare MySQL result
resource, and it was necessary to call this function to convert it to
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: bool|ResultWrapper|resource $result
return: bool|ResultWrapper

ping() X-Ref

Ping the server and try to reconnect if it there is no connection

return: bool Success or failure

getLag() X-Ref

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: int Database replication lag in seconds

maxListLen() X-Ref

Return the maximum number of items allowed in a list, or 0 for unlimited.

return: int

encodeBlob( $b ) X-Ref

Some DBMSs have a special format for inserting into blob fields, they
don't allow simple quoted strings to be inserted. To insert into such
a field, pass the data through this function before passing it to
DatabaseBase::insert().

param: string $b
return: string

decodeBlob( $b ) X-Ref

Some DBMSs return a special placeholder object representing blob fields
in result objects. Pass the object through this function to return the
original string.

param: string $b
return: string

setSessionOptions( array $options ) X-Ref

Override database's default behavior. $options include:
'connTimeout' : Set the connection timeout value in seconds.
May be useful for very long batch queries such as
full-wiki dumps, where a single query reads out over
hours or days.

param: array $options
return: void

sourceFile($filename, $lineCallback = false, $resultCallback = false, $fname = false, $inputCallback = false) X-Ref

Read and execute SQL commands from a file.

Returns true on success, error string or exception on failure (depending
on object's error ignore settings).

param: string $filename File name to open
param: bool|callable $lineCallback Optional function called before reading each line
param: bool|callable $resultCallback Optional function called for each MySQL result
param: bool|string $fname Calling function name or false if name should be
param: bool|callable $inputCallback Optional function called for each
return: bool|string

patchPath( $patch ) X-Ref

Get the full path of a patch file. Originally based on archive()
from updaters.inc. Keep in mind this always returns a patch, as
it fails back to MySQL if no DB-specific patch can be found

param: string $patch The name of the patch, like patch-something.sql
return: string Full path to patch file

setSchemaVars( $vars ) X-Ref

Set variables to be used in sourceFile/sourceStream, in preference to the
ones in $GLOBALS. If an array is set here, $GLOBALS will not be used at
all. If it's set to false, $GLOBALS will be used.

param: bool|array $vars Mapping variable name to value.

sourceStream( $fp, $lineCallback = false, $resultCallback = false,$fname = __METHOD__, $inputCallback = false) X-Ref

Read and execute commands from an open file handle.

Returns true on success, error string or exception on failure (depending
on object's error ignore settings).

param: resource $fp File handle
param: bool|callable $lineCallback Optional function called before reading each query
param: bool|callable $resultCallback Optional function called for each MySQL result
param: string $fname Calling function name
param: bool|callable $inputCallback Optional function called for each complete query sent
return: bool|string

streamStatementEnd( &$sql, &$newLine ) X-Ref

Called by sourceStream() to check if we've reached a statement end

param: string $sql SQL assembled so far
param: string $newLine New line about to be added to $sql
return: bool Whether $newLine contains end of the statement

replaceSchemaVars( $ins ) X-Ref

Database independent variable replacement. Replaces a set of variables
in an SQL statement with their contents as given by $this->getSchemaVars().

Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables.

- '{$var}' should be used for text and is passed through the database's
addQuotes method.
- `{$var}` should be used for identifiers (eg: table and database names),
it is passed through the database's addIdentifierQuotes method which
can be overridden if the database uses something other than backticks.
- / *$var* / is just encoded, besides traditional table prefix and
table options its use should be avoided.

param: string $ins SQL statement to replace variables in
return: string The new SQL statement with variables replaced

replaceVars( $ins ) X-Ref

Replace variables in sourced SQL

param: string $ins
return: string

getSchemaVars() X-Ref

Get schema variables. If none have been set via setSchemaVars(), then
use some defaults from the current object.

return: array

getDefaultSchemaVars() X-Ref

Get schema variables to use if none have been set via setSchemaVars().

Override this in derived classes to provide variables for tables.sql
and SQL patch files.

return: array

tableNameCallback( $matches ) X-Ref

Table name callback

param: array $matches
return: string

indexNameCallback( $matches ) X-Ref

Index name callback

param: array $matches
return: string

lockIsFree( $lockName, $method ) X-Ref

Check to see if a named lock is available. This is non-blocking.

param: string $lockName Name of lock to poll
param: string $method Name of method calling us
return: bool

lock( $lockName, $method, $timeout = 5 ) X-Ref

Acquire a named lock

Abstracted from Filestore::lock() so child classes can implement for
their own needs.

param: string $lockName Name of lock to aquire
param: string $method Name of method calling us
param: int $timeout
return: bool

unlock( $lockName, $method ) X-Ref

Release a lock.

param: string $lockName Name of lock to release
param: string $method Name of method calling us
return: int Returns 1 if the lock was released, 0 if the lock was not established

lockTables( $read, $write, $method, $lowPriority = true ) X-Ref

Lock specific tables

param: array $read Array of tables to lock for read access
param: array $write Array of tables to lock for write access
param: string $method Name of caller
param: bool $lowPriority Whether to indicate writes to be LOW PRIORITY
return: bool

unlockTables( $method ) X-Ref

Unlock specific tables

param: string $method The caller
return: bool

dropTable( $tableName, $fName = __METHOD__ ) X-Ref

Delete a table

param: string $tableName
param: string $fName
return: bool|ResultWrapper

getSearchEngine() X-Ref

Get search engine class. All subclasses of this need to implement this
if they wish to use searching.

return: string

getInfinity() X-Ref

Find out when 'infinity' is. Most DBMSes support this. This is a special
keyword for timestamps in PostgreSQL, and works with CHAR(14) as well
because "i" sorts after all numbers.

return: string

encodeExpiry( $expiry ) X-Ref

Encode an expiry time into the DBMS dependent format

param: string $expiry Timestamp for expiry, or the 'infinity' string
return: string

decodeExpiry( $expiry, $format = TS_MW ) X-Ref

Decode an expiry time into a DBMS independent format

param: string $expiry DB timestamp field value for expiry
param: int $format TS_* constant, defaults to TS_MW
return: string

setBigSelects( $value = true ) X-Ref

Allow or deny "big selects" for this session only. This is done by setting
the sql_big_selects session variable.

This is a MySQL-specific feature.

param: bool|string $value True for allow, false for deny, or "default" to

__toString() X-Ref

return: string

__destruct() X-Ref

Run a few simple sanity checks

File Size:	4277 lines (126 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of MediaWiki-1.24.0

/includes/db/ -> Database.php (summary)

Defines 2 classes