MediaWiki  master
Wikimedia\Rdbms\Platform\SQLPlatform Class Reference

Sql abstraction object. More...

Inheritance diagram for Wikimedia\Rdbms\Platform\SQLPlatform:
Collaboration diagram for Wikimedia\Rdbms\Platform\SQLPlatform:

Public Member Functions

 __construct (DbQuoter $quoter, LoggerInterface $logger=null, DatabaseDomain $currentDomain=null, $errorLogger=null)
 
 addIdentifierQuotes ( $s)
 Escape a SQL identifier (e.g.table, column, database) for use in a SQL queryDepending on the database this will either be backticks or "double quotes"
Parameters
string$s
Returns
string
Since
1.33
More...
 
 anyChar ()
 Returns a token for buildLike() that denotes a '_' to be used in a LIKE query. More...
 
 anyString ()
 Returns a token for buildLike() that denotes a '' to be used in a LIKE query. More...
 
 assertValidUpsertSetArray (array $set, array $identityKey, array $rows)
 
 bitAnd ( $fieldLeft, $fieldRight)
 
Parameters
string | int$fieldLeft
string | int$fieldRight
Returns
string
More...
 
 bitNot ( $field)
 
Parameters
string | int$field
Returns
string
More...
 
 bitOr ( $fieldLeft, $fieldRight)
 
Parameters
string | int$fieldLeft
string | int$fieldRight
Returns
string
More...
 
 buildComparison (string $op, array $conds)
 Build a condition comparing multiple values, for use with indexes that cover multiple fields, common when e.g. More...
 
 buildConcat ( $stringList)
 Build a concatenation list to feed into a SQL query.
Parameters
string[]$stringListRaw SQL expression list; caller is responsible for escaping
Returns
string
More...
 
 buildExcludedValue ( $column)
 Build a reference to a column value from the conflicting proposed upsert() row. More...
 
 buildGreatest ( $fields, $values)
 Build a GREATEST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.
Parameters
string | string[]$fieldsName(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]$valuesValues to compare
Returns
mixed
Since
1.35 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 buildGroupConcatField ( $delim, $table, $field, $conds='', $join_conds=[])
 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.
Parameters
string$delimGlue to bind the results together
string | array$tableTable name
string$fieldField name
string | array$condsConditions
string | array$join_condsJoin conditions
Returns
string SQL text
Since
1.23
More...
 
 buildIntegerCast ( $field)
 
Parameters
string$fieldField or column to cast
Returns
string
Since
1.31 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 buildLeast ( $fields, $values)
 Build a LEAST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.
Parameters
string | string[]$fieldsName(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]$valuesValues to compare
Returns
mixed
Since
1.35 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 buildLike ( $param,... $params)
 LIKE statement wrapper.This takes 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 = [ 'My_page_title/', $dbr->anyString() ]; $query .= $dbr->buildLike( $pattern );
Since
1.16 in IDatabase, moved to ISQLPlatform in 1.39
Parameters
array[] | string | LikeMatch$param
string|LikeMatch...$params
Returns
string Fully built LIKE statement
More...
 
 buildSelectSubquery ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery. More...
 
 buildStringCast ( $field)
 
Parameters
string$fieldField or column to cast
Returns
string
Since
1.28 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 buildSubstring ( $input, $startPosition, $length=null)
 
 conditional ( $cond, $caseTrueExpression, $caseFalseExpression)
 Returns an SQL expression for a simple conditional.This doesn't need to be overridden unless CASE isn't supported in the RDBMS.
Parameters
string | array$condSQL condition expression (yields a boolean)
string$caseTrueExpressionSQL expression to return when the condition is true
string$caseFalseExpressionSQL expression to return when the condition is false
Returns
string SQL fragment
More...
 
 decodeExpiry ( $expiry, $format=TS_MW)
 Decode an expiry time into a DBMS independent format. More...
 
 deleteJoinSqlText ( $delTable, $joinTable, $delVar, $joinVar, $conds)
 
 deleteSqlText ( $table, $conds)
 
 dispatchingInsertSqlText ( $table, $rows, $options)
 
 dropTableSqlText ( $table)
 
 encodeExpiry ( $expiry)
 Encode an expiry time into the DBMS dependent format. More...
 
 escapeLikeInternal ( $s, $escapeChar='`')
 
 extractSingleFieldFromList ( $var)
 
 factorConds ( $condsArray)
 Given an array of condition arrays representing an OR list of AND lists, for example: More...
 
 fieldNameWithAlias ( $name, $alias=false)
 Get an aliased field name e.g. More...
 
 getInfinity ()
 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.
Returns
string
More...
 
 getQueryVerb ( $sql)
 
 getTableAliases ()
 
 ignoreIndexClause ( $index)
 IGNORE INDEX clause. More...
 
 implicitOrderby ()
 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.
Returns
bool
More...
 
 indexName ( $index)
 Allows for index remapping in queries where this is not consistent across DBMS. More...
 
 insertNonConflictingSqlText ( $table, array $rows)
 
 insertSelectNativeSqlText ( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds)
 
 insertSqlText ( $table, array $rows)
 
 isFlagInOptions ( $option, array $options)
 
 isQuotedIdentifier ( $name)
 Returns if the given identifier looks quoted or not according to the database convention for quoting identifiers. More...
 
 isTransactableQuery ( $sql)
 Determine whether a SQL statement is sensitive to isolation level. More...
 
 isWriteQuery ( $sql, $flags)
 Determine whether a query writes to the DB. More...
 
 limitResult ( $sql, $limit, $offset=false)
 Construct a LIMIT query with optional offset.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.
Parameters
string$sqlSQL query we will append the limit too
int$limitThe SQL limit
int | false$offsetThe SQL offset (default false)
Returns
string
Since
1.34 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 lockIsFreeSQLText ( $lockName)
 
 lockSQLText ( $lockName, $timeout)
 
 makeInsertLists (array $rows, $aliasPrefix='', array $typeByColumn=[])
 Make SQL lists of columns, row tuples, and column aliases for INSERT/VALUES expressions. More...
 
 makeKeyCollisionCondition (array $rows, array $uniqueKey)
 Build an SQL condition to find rows with matching key values to those in $rows. More...
 
 makeList (array $a, $mode=self::LIST_COMMA)
 Makes an encoded list of strings from an array. More...
 
 makeWhereFrom2d ( $data, $baseKey, $subKey)
 Build a partial where clause from a 2-d array such as used for LinkBatch. More...
 
 normalizeConditions ( $conds, $fname)
 
 normalizeOptions ( $options)
 
 normalizeUpsertParams ( $uniqueKeys, &$rows)
 Validate and normalize parameters to upsert() or replace() More...
 
 qualifiedTableComponents ( $name)
 Get the table components needed for a query given the currently selected database. More...
 
 releaseSavepointSqlText ( $identifier)
 
 replaceVars ( $ins)
 Database-independent variable replacement. More...
 
 rollbackSqlText ()
 
 rollbackToSavepointSqlText ( $identifier)
 
 savepointSqlText ( $identifier)
 
 selectSQLText ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Take the same arguments as IDatabase::select() and return the SQL it would use.This can be useful for making UNION queries, where the SQL text of each query is needed. In general, however, callers outside of Database classes should just use select().
See also
IDatabase::select()
Parameters
string | array$tableTable name(s)
string | array$varsField names
string | array$condsConditions
string$fnameCaller function name
string | array$optionsQuery options
string | array$join_condsJoin conditions
Returns
string SQL query string
More...
 
 setCurrentDomain (DatabaseDomain $currentDomain)
 
 setIndexAliases (array $aliases)
 Convert certain index names to alternative names before querying the DB.Note that this applies to indexes regardless of the table they belong to.This can be employed when an index was renamed X => Y in code, but the new Y-named indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA, the aliases can be removed, and then the old X-named indexes dropped.
Parameters
string[]$aliases
Since
1.31 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 setPrefix ( $prefix)
 
 setSchemaVars ( $vars)
 Set schema variables to be used when streaming commands from SQL files or stdin. More...
 
 setTableAliases (array $aliases)
 Make certain table names use their own database, schema, and table prefix when passed into SQL queries pre-escaped and without a qualified database name.For example, "user" can be converted to "myschema.mydbname.user" for convenience. Appearances like user, somedb.user, somedb.someschema.user will used literally.Calling this twice will completely clear any old table aliases. Also, note that callers are responsible for making sure the schemas and databases actually exist.
Parameters
array[]$aliasesMap of (table => (dbname, schema, prefix) map)
Since
1.28 in IDatabase, moved to ISQLPlatform in 1.39
More...
 
 strreplace ( $orig, $old, $new)
 Returns a SQL expression for simple string replacement (e.g.REPLACE() in mysql)
Parameters
string$origColumn to modify
string$oldColumn to seek
string$newColumn to replace with
Returns
string
More...
 
 tableName ( $name, $format='quoted')
 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.
Note
This function does not sanitize user input. It is not safe to use this function to escape user input.
Parameters
string$nameDatabase table name
string$formatOne 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
Returns
string Full database name
More...
 
 tableNames (... $tables)
 Fetch a number of table names into an associative array. More...
 
 tableNamesN (... $tables)
 Fetch a number of table names into a zero-indexed numerical array. More...
 
 timestamp ( $ts=0)
 Convert a timestamp in one of the formats accepted by ConvertibleTimestamp 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.
Parameters
string | int$ts
Returns
string
More...
 
 timestampOrNull ( $ts=null)
 Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for inserting into timestamp fields in this DBMS. More...
 
 unionConditionPermutations ( $table, $vars, array $permute_conds, $extra_conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Construct a UNION query for permutations of conditions. More...
 
 unionQueries ( $sqls, $all)
 Construct a UNION query.This is used for providing overload point for other DB abstractions not compatible with the MySQL syntax.

Parameters
array$sqlsSQL statements to combine
bool$allEither IDatabase::UNION_ALL or IDatabase::UNION_DISTINCT
Returns
string SQL fragment
More...
 
 unionSupportsOrderAndLimit ()
 Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION.
Returns
bool
More...
 
 unlockSQLText ( $lockName)
 
 updateSqlText ( $table, $set, $conds, $options)
 
 useIndexClause ( $index)
 USE INDEX clause. More...
 
- Public Member Functions inherited from Wikimedia\Rdbms\Platform\ISQLPlatform
 buildSubString ( $input, $startPosition, $length=null)
 Build a SUBSTRING function. More...
 

Protected Member Functions

 assertBuildSubstringParams ( $startPosition, $length)
 Check type and bounds for parameters to self::buildSubstring() More...
 
 assertConditionIsNotEmpty ( $conds, string $fname, bool $deprecate)
 Check type and bounds conditions parameters for update. More...
 
 assertValidUpsertRowArray (array $rows, array $identityKey)
 
 buildSuperlative ( $sqlfunc, $fields, $values)
 Build a superlative function statement comparing columns/values. More...
 
 fieldHasBit (int $flags, int $bit)
 
 fieldNamesWithAlias ( $fields)
 Gets an array of aliased field names. More...
 
 getDefaultSchemaVars ()
 Get schema variables to use if none have been set via setSchemaVars(). More...
 
 getSchemaVars ()
 Get schema variables. More...
 
 makeGroupByWithHaving ( $options)
 Returns an optional GROUP BY with an optional HAVING. More...
 
 makeInsertNonConflictingVerbAndOptions ()
 
 makeOrderBy ( $options)
 Returns an optional ORDER BY. More...
 
 makeSelectOptions (array $options)
 Returns an optional USE INDEX clause to go after the table, and a string to go at the end of the query. More...
 
 makeUpdateOptions ( $options)
 Make UPDATE options for the Database::update function. More...
 
 makeUpdateOptionsArray ( $options)
 Make UPDATE options array for Database::makeUpdateOptions. More...
 
 normalizeJoinType (string $joinType)
 Validate and normalize a join type. More...
 
 normalizeRowArray (array $rowOrRows)
 
 relationSchemaQualifier ()
 
 tableNamesWithIndexClauseOrJOIN ( $tables, $use_index=[], $ignore_index=[], $join_conds=[])
 Get the aliased table name clause for a FROM clause which might have a JOIN and/or USE INDEX or IGNORE INDEX clause. More...
 
 tableNameWithAlias ( $table, $alias=false)
 Get an aliased table name. More...
 

Protected Attributes

DatabaseDomain null $currentDomain
 
callable $errorLogger
 Error logging callback. More...
 
string[] $indexAliases = []
 Current map of (index alias => index) More...
 
LoggerInterface $logger
 
DbQuoter $quoter
 
array null $schemaVars
 Current variables use for schema element placeholders. More...
 
array[] $tableAliases = []
 Current map of (table => (dbname, schema, prefix) map) More...
 

Additional Inherited Members

- Public Attributes inherited from Wikimedia\Rdbms\Platform\ISQLPlatform
const QUERY_PSEUDO_PERMANENT = 2
 Track a TEMPORARY table CREATE as if it was for a permanent table (for testing) More...
 

Detailed Description

Sql abstraction object.

This class nor any of its subclasses shouldn't create a db connection. It also should not become stateful. The constructor should only rely on addQuotes() method in Database. Later that should be replaced with an implementation that doesn't use db connections.

Since
1.39

Definition at line 42 of file SQLPlatform.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\Platform\SQLPlatform::__construct ( DbQuoter  $quoter,
LoggerInterface  $logger = null,
DatabaseDomain  $currentDomain = null,
  $errorLogger = null 
)

Member Function Documentation

◆ addIdentifierQuotes()

Wikimedia\Rdbms\Platform\SQLPlatform::addIdentifierQuotes (   $s)

Escape a SQL identifier (e.g.table, column, database) for use in a SQL queryDepending on the database this will either be backticks or "double quotes"

Parameters
string$s
Returns
string
Since
1.33

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 101 of file SQLPlatform.php.

References $s.

Referenced by Wikimedia\Rdbms\Platform\SQLPlatform\buildSuperlative().

◆ anyChar()

Wikimedia\Rdbms\Platform\SQLPlatform::anyChar ( )

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

Returns
LikeMatch

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 451 of file SQLPlatform.php.

◆ anyString()

Wikimedia\Rdbms\Platform\SQLPlatform::anyString ( )

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

Returns
LikeMatch

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 455 of file SQLPlatform.php.

◆ assertBuildSubstringParams()

Wikimedia\Rdbms\Platform\SQLPlatform::assertBuildSubstringParams (   $startPosition,
  $length 
)
protected

Check type and bounds for parameters to self::buildSubstring()

All supported databases have substring functions that behave the same for positive $startPosition and non-negative $length, but behaviors differ when given negative $startPosition or negative $length. The simplest solution to that is to just forbid those values.

Parameters
int$startPosition
int | null$length
Since
1.31 in Database, moved to SQLPlatform in 1.39

Definition at line 562 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SqlitePlatform\buildSubstring().

◆ assertConditionIsNotEmpty()

Wikimedia\Rdbms\Platform\SQLPlatform::assertConditionIsNotEmpty (   $conds,
string  $fname,
bool  $deprecate 
)
protected

Check type and bounds conditions parameters for update.

In order to prevent possible performance or replication issues, empty condition for 'update' and 'delete' queries isn't allowed

Parameters
array | string$condsconditions to be validated on emptiness
string$fnamecaller's function name to be passed to exception
bool$deprecatedefine the assertion type. If true then wfDeprecated will be called, otherwise DBUnexpectedError will be raised.
Since
1.35, moved to SQLPlatform in 1.39

Definition at line 1614 of file SQLPlatform.php.

References wfDeprecated().

◆ assertValidUpsertRowArray()

Wikimedia\Rdbms\Platform\SQLPlatform::assertValidUpsertRowArray ( array  $rows,
array  $identityKey 
)
finalprotected
Parameters
array<int,array>$rows Normalized list of rows to insert
string[]$identityKeyColumns of the (unique) identity key to UPSERT upon
Returns
bool Whether all the rows have NULL/absent values for all identity key columns
Since
1.37

Definition at line 1963 of file SQLPlatform.php.

◆ assertValidUpsertSetArray()

Wikimedia\Rdbms\Platform\SQLPlatform::assertValidUpsertSetArray ( array  $set,
array  $identityKey,
array  $rows 
)
final
Parameters
array$setCombined column/literal assignment map and SQL assignment list
string[]$identityKeyColumns of the (unique) identity key to UPSERT upon
array<int,array>$rows List of rows to upsert
Since
1.37

Definition at line 1989 of file SQLPlatform.php.

◆ bitAnd()

Wikimedia\Rdbms\Platform\SQLPlatform::bitAnd (   $fieldLeft,
  $fieldRight 
)

Parameters
string | int$fieldLeft
string | int$fieldRight
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 85 of file SQLPlatform.php.

◆ bitNot()

Wikimedia\Rdbms\Platform\SQLPlatform::bitNot (   $field)

Parameters
string | int$field
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 77 of file SQLPlatform.php.

◆ bitOr()

Wikimedia\Rdbms\Platform\SQLPlatform::bitOr (   $fieldLeft,
  $fieldRight 
)

Parameters
string | int$fieldLeft
string | int$fieldRight
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 93 of file SQLPlatform.php.

◆ buildComparison()

Wikimedia\Rdbms\Platform\SQLPlatform::buildComparison ( string  $op,
array  $conds 
)

Build a condition comparing multiple values, for use with indexes that cover multiple fields, common when e.g.

paging through results or doing batch operations.

For example, you might be displaying a list of people ordered alphabetically by their last and first name, split across multiple pages. The first page of the results ended at Jane Doe. When building the query for the next page, you would use:

$queryBuilder->where( $db->buildComparison( '>', [ 'last' => 'Doe', 'first' => 'Jane' ] ) );

This will return people whose last name follows Doe, or whose last name is Doe and first name follows Jane.

Note that the order of keys in the associative array $conds is significant, and must match the order of fields used by the index.

You might also use it to generate a simple comparison without writing raw SQL:

$db->buildComparison( '<=', [ 'key' => $val ] )
// equivalent to:
'key <= ' . $db->addQuotes( $val )
Parameters
string$opComparison operator, one of '>', '>=', '<', '<='
array$condsMap of field names to their values to use in the comparison
Returns
string SQL code

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 160 of file SQLPlatform.php.

◆ buildConcat()

Wikimedia\Rdbms\Platform\SQLPlatform::buildConcat (   $stringList)

Build a concatenation list to feed into a SQL query.

Parameters
string[]$stringListRaw SQL expression list; caller is responsible for escaping
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, and Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 385 of file SQLPlatform.php.

◆ buildExcludedValue()

Wikimedia\Rdbms\Platform\SQLPlatform::buildExcludedValue (   $column)

Build a reference to a column value from the conflicting proposed upsert() row.

The reference comes in the form of an alias, function, or parenthesized SQL expression. It can be used in upsert() SET expressions to handle the merging of column values between each conflicting pair of existing and proposed rows. Such proposed rows are said to have been "excluded" from insertion in favor of updating the existing row.

This is useful for multi-row upserts() since the proposed values cannot just be included as literals in the SET expressions.

See also
IDatabase::upsert()
Parameters
string$columnColumn name
Returns
string SQL expression returning a scalar
Since
1.39

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1792 of file SQLPlatform.php.

◆ buildGreatest()

Wikimedia\Rdbms\Platform\SQLPlatform::buildGreatest (   $fields,
  $values 
)

Build a GREATEST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Parameters
string | string[]$fieldsName(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]$valuesValues to compare
Returns
mixed
Since
1.35 in IDatabase, moved to ISQLPlatform in 1.39

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 108 of file SQLPlatform.php.

References Wikimedia\Rdbms\Platform\SQLPlatform\buildSuperlative().

◆ buildGroupConcatField()

Wikimedia\Rdbms\Platform\SQLPlatform::buildGroupConcatField (   $delim,
  $table,
  $field,
  $conds = '',
  $join_conds = [] 
)

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.

Parameters
string$delimGlue to bind the results together
string | array$tableTable name
string$fieldField name
string | array$condsConditions
string | array$join_condsJoin conditions
Returns
string SQL text
Since
1.23

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, and Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1380 of file SQLPlatform.php.

◆ buildIntegerCast()

Wikimedia\Rdbms\Platform\SQLPlatform::buildIntegerCast (   $field)

Parameters
string$fieldField or column to cast
Returns
string
Since
1.31 in IDatabase, moved to ISQLPlatform in 1.39

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 593 of file SQLPlatform.php.

◆ buildLeast()

Wikimedia\Rdbms\Platform\SQLPlatform::buildLeast (   $fields,
  $values 
)

Build a LEAST function statement comparing columns/values.Integer and float values in $values will not be quotedIf $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Parameters
string | string[]$fieldsName(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]$valuesValues to compare
Returns
mixed
Since
1.35 in IDatabase, moved to ISQLPlatform in 1.39

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 115 of file SQLPlatform.php.

References Wikimedia\Rdbms\Platform\SQLPlatform\buildSuperlative().

◆ buildLike()

Wikimedia\Rdbms\Platform\SQLPlatform::buildLike (   $param,
  $params 
)

LIKE statement wrapper.This takes 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 = [ 'My_page_title/', $dbr->anyString() ]; $query .= $dbr->buildLike( $pattern );

Since
1.16 in IDatabase, moved to ISQLPlatform in 1.39
Parameters
array[] | string | LikeMatch$param
string|LikeMatch...$params
Returns
string Fully built LIKE statement

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 424 of file SQLPlatform.php.

References $s.

◆ buildSelectSubquery()

Wikimedia\Rdbms\Platform\SQLPlatform::buildSelectSubquery (   $table,
  $vars,
  $conds = '',
  $fname = __METHOD__,
  $options = [],
  $join_conds = [] 
)

Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery.

See also
IDatabase::selectSQLText()
Parameters
string | array$tableTable name
string | array$varsField names
string | array$condsConditions
string$fnameCaller function name
string | array$optionsQuery options
string | array$join_condsJoin conditions
Returns
Subquery
Since
1.31

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 1388 of file SQLPlatform.php.

◆ buildStringCast()

Wikimedia\Rdbms\Platform\SQLPlatform::buildStringCast (   $field)

Parameters
string$fieldField or column to cast
Returns
string
Since
1.28 in IDatabase, moved to ISQLPlatform in 1.39

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, Wikimedia\Rdbms\Platform\PostgresPlatform, and Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 583 of file SQLPlatform.php.

◆ buildSubstring()

Wikimedia\Rdbms\Platform\SQLPlatform::buildSubstring (   $input,
  $startPosition,
  $length = null 
)

Stability: stable
to override

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 541 of file SQLPlatform.php.

◆ buildSuperlative()

Wikimedia\Rdbms\Platform\SQLPlatform::buildSuperlative (   $sqlfunc,
  $fields,
  $values 
)
protected

Build a superlative function statement comparing columns/values.

Integer and float values in $values will not be quoted

If $fields is an array, then each value with a string key is treated as an expression (which must be manually quoted); such string keys do not appear in the SQL and are only descriptive aliases.

Parameters
string$sqlfuncName of a SQL function
string | string[]$fieldsName(s) of column(s) with values to compare
string | int | float | string[] | int[] | float[]$valuesValues to compare
Returns
string

Definition at line 133 of file SQLPlatform.php.

References Wikimedia\Rdbms\Platform\SQLPlatform\addIdentifierQuotes().

Referenced by Wikimedia\Rdbms\Platform\SqlitePlatform\buildGreatest(), Wikimedia\Rdbms\Platform\SQLPlatform\buildGreatest(), Wikimedia\Rdbms\Platform\SqlitePlatform\buildLeast(), and Wikimedia\Rdbms\Platform\SQLPlatform\buildLeast().

◆ conditional()

Wikimedia\Rdbms\Platform\SQLPlatform::conditional (   $cond,
  $caseTrueExpression,
  $caseFalseExpression 
)

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

Parameters
string | array$condSQL condition expression (yields a boolean)
string$caseTrueExpressionSQL expression to return when the condition is true
string$caseFalseExpressionSQL expression to return when the condition is false
Returns
string SQL fragment

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 481 of file SQLPlatform.php.

References LIST_AND.

◆ decodeExpiry()

Wikimedia\Rdbms\Platform\SQLPlatform::decodeExpiry (   $expiry,
  $format = TS_MW 
)

Decode an expiry time into a DBMS independent format.

Parameters
string$expiryDB timestamp field value for expiry
int$formatTS_* constant, defaults to TS_MW
Returns
string

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 529 of file SQLPlatform.php.

◆ deleteJoinSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::deleteJoinSqlText (   $delTable,
  $joinTable,
  $delVar,
  $joinVar,
  $conds 
)

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1553 of file SQLPlatform.php.

References LIST_AND.

◆ deleteSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::deleteSqlText (   $table,
  $conds 
)

Definition at line 1569 of file SQLPlatform.php.

References LIST_AND.

◆ dispatchingInsertSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::dispatchingInsertSqlText (   $table,
  $rows,
  $options 
)

Definition at line 1814 of file SQLPlatform.php.

◆ dropTableSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::dropTableSqlText (   $table)

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 1672 of file SQLPlatform.php.

◆ encodeExpiry()

Wikimedia\Rdbms\Platform\SQLPlatform::encodeExpiry (   $expiry)

Encode an expiry time into the DBMS dependent format.

Parameters
string$expiryTimestamp for expiry, or the 'infinity' string
Returns
string

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 523 of file SQLPlatform.php.

◆ escapeLikeInternal()

Wikimedia\Rdbms\Platform\SQLPlatform::escapeLikeInternal (   $s,
  $escapeChar = '`' 
)
Stability: stable
to override
Parameters
string$s
string$escapeChar
Returns
string

Definition at line 412 of file SQLPlatform.php.

References $s.

◆ extractSingleFieldFromList()

Wikimedia\Rdbms\Platform\SQLPlatform::extractSingleFieldFromList (   $var)
final
Parameters
array | string$varField parameter in the style of select()
Returns
string|null Column name or null; ignores aliases

Definition at line 2037 of file SQLPlatform.php.

◆ factorConds()

Wikimedia\Rdbms\Platform\SQLPlatform::factorConds (   $condsArray)

Given an array of condition arrays representing an OR list of AND lists, for example:

(A=1 AND B=2) OR (A=1 AND B=3)

produce an SQL expression in which the conditions are factored:

(A=1 AND (B=2 OR B=3))

We also use IN() to simplify further:

(A=1 AND (B IN (2,3))

More compactly, in boolean algebra notation, a sum of products, e.g. AB + AC is factored to produce A(B+C). Factoring proceeds recursively to reduce expressions with any number of variables, for example AEP + AEQ + AFP + AFQ = A(E(P+Q) + F(P+Q))

The algorithm is simple and will not necessarily find the shortest possible expression. For the best results, fields should be given in a consistent order, and the fields with values likely to be shared should be leftmost in the associative arrays.

Parameters
array$condsArrayAn array of associative arrays. The associative array keys represent field names, and the values represent the field values to compare against.
Returns
string SQL expression fragment

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 299 of file SQLPlatform.php.

◆ fieldHasBit()

Wikimedia\Rdbms\Platform\SQLPlatform::fieldHasBit ( int  $flags,
int  $bit 
)
finalprotected
Parameters
int$flagsA bitfield of flags
int$bitBit flag constant
Returns
bool Whether the bit field has the specified bit flag set

Definition at line 1788 of file SQLPlatform.php.

◆ fieldNamesWithAlias()

Wikimedia\Rdbms\Platform\SQLPlatform::fieldNamesWithAlias (   $fields)
protected

Gets an array of aliased field names.

Parameters
array$fields[ [alias] => field ]
Returns
string[] See fieldNameWithAlias()

Definition at line 806 of file SQLPlatform.php.

◆ fieldNameWithAlias()

Wikimedia\Rdbms\Platform\SQLPlatform::fieldNameWithAlias (   $name,
  $alias = false 
)

Get an aliased field name e.g.

fieldName AS newFieldName

Stability: stable
to override
Parameters
string$nameField name
string | false$aliasAlias (optional)
Returns
string SQL name for aliased field. Will not alias a field to its own name

Definition at line 827 of file SQLPlatform.php.

◆ getDefaultSchemaVars()

Wikimedia\Rdbms\Platform\SQLPlatform::getDefaultSchemaVars ( )
protected

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.

Stability: stable
to override
Returns
array

Definition at line 2076 of file SQLPlatform.php.

◆ getInfinity()

Wikimedia\Rdbms\Platform\SQLPlatform::getInfinity ( )

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.

Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 519 of file SQLPlatform.php.

◆ getQueryVerb()

Wikimedia\Rdbms\Platform\SQLPlatform::getQueryVerb (   $sql)
Parameters
string$sqlSQL query
Returns
string|null

Definition at line 1683 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SqlitePlatform\isTransactableQuery().

◆ getSchemaVars()

Wikimedia\Rdbms\Platform\SQLPlatform::getSchemaVars ( )
protected

Get schema variables.

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

Returns
array

Definition at line 2063 of file SQLPlatform.php.

◆ getTableAliases()

Wikimedia\Rdbms\Platform\SQLPlatform::getTableAliases ( )
Returns
array[]

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 636 of file SQLPlatform.php.

◆ ignoreIndexClause()

Wikimedia\Rdbms\Platform\SQLPlatform::ignoreIndexClause (   $index)

IGNORE INDEX clause.

The inverse of Database::useIndexClause.

Stability: stable
to override
Parameters
string$index
Returns
string

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1187 of file SQLPlatform.php.

◆ implicitOrderby()

Wikimedia\Rdbms\Platform\SQLPlatform::implicitOrderby ( )

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.

Returns
bool

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 601 of file SQLPlatform.php.

◆ indexName()

Wikimedia\Rdbms\Platform\SQLPlatform::indexName (   $index)

Allows for index remapping in queries where this is not consistent across DBMS.

TODO: Make it protected once all the code is moved over.

Parameters
string$index
Returns
string

Definition at line 613 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\MySQLPlatform\ignoreIndexClause(), and Wikimedia\Rdbms\Platform\MySQLPlatform\useIndexClause().

◆ insertNonConflictingSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::insertNonConflictingSqlText (   $table,
array  $rows 
)

Definition at line 1450 of file SQLPlatform.php.

◆ insertSelectNativeSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::insertSelectNativeSqlText (   $destTable,
  $srcTable,
array  $varMap,
  $conds,
  $fname,
array  $insertOptions,
array  $selectOptions,
  $selectJoinConds 
)

Definition at line 1467 of file SQLPlatform.php.

◆ insertSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::insertSqlText (   $table,
array  $rows 
)

Definition at line 1397 of file SQLPlatform.php.

◆ isFlagInOptions()

Wikimedia\Rdbms\Platform\SQLPlatform::isFlagInOptions (   $option,
array  $options 
)
Parameters
string$optionQuery option flag (e.g. "IGNORE" or "FOR UPDATE")
array$optionsCombination option/value map and boolean option list
Returns
bool Whether the option appears as an integer-keyed value in the options
Since
1.35

Definition at line 1500 of file SQLPlatform.php.

◆ isQuotedIdentifier()

Wikimedia\Rdbms\Platform\SQLPlatform::isQuotedIdentifier (   $name)

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

Stability: stable
to override
Note
Do not use this to determine if untrusted input is safe. A malicious user can trick this function.
Parameters
string$name
Returns
bool

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1157 of file SQLPlatform.php.

◆ isTransactableQuery()

Wikimedia\Rdbms\Platform\SQLPlatform::isTransactableQuery (   $sql)

Determine whether a SQL statement is sensitive to isolation level.

A SQL statement is considered transactable if its result could vary depending on the transaction isolation level. Operational commands such as 'SET' and 'SHOW' are not considered to be transactable.

Main purpose: Used by query() to decide whether to begin a transaction before the current query (in DBO_TRX mode, on by default).

Stability: stable
to override
Parameters
string$sql
Returns
bool

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, Wikimedia\Rdbms\Platform\PostgresPlatform, and Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1706 of file SQLPlatform.php.

◆ isWriteQuery()

Wikimedia\Rdbms\Platform\SQLPlatform::isWriteQuery (   $sql,
  $flags 
)

Determine whether a query writes to the DB.

When in doubt, this returns true.

Main use cases:

  • Subsequent web requests should not need to wait for replication from the primary position seen by this web request, unless this request made changes to the primary DB. This is handled by ChronologyProtector by checking doneWrites() at the end of the request. doneWrites() returns true if any query set lastWriteTime; which query() does based on isWriteQuery().
  • Reject write queries to replica DBs, in query().
Parameters
string$sqlSQL query
int$flagsQuery flags to query()
Returns
bool

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 1742 of file SQLPlatform.php.

◆ limitResult()

Wikimedia\Rdbms\Platform\SQLPlatform::limitResult (   $sql,
  $limit,
  $offset = false 
)

Construct a LIMIT query with optional offset.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.

Parameters
string$sqlSQL query we will append the limit too
int$limitThe SQL limit
int | false$offsetThe SQL offset (default false)
Returns
string
Since
1.34 in IDatabase, moved to ISQLPlatform in 1.39

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 393 of file SQLPlatform.php.

◆ lockIsFreeSQLText()

Wikimedia\Rdbms\Platform\SQLPlatform::lockIsFreeSQLText (   $lockName)

◆ lockSQLText()

Wikimedia\Rdbms\Platform\SQLPlatform::lockSQLText (   $lockName,
  $timeout 
)

◆ makeGroupByWithHaving()

Wikimedia\Rdbms\Platform\SQLPlatform::makeGroupByWithHaving (   $options)
protected

Returns an optional GROUP BY with an optional HAVING.

Parameters
array$optionsAssociative array of options
Returns
string
See also
Database::select()
Since
1.21

Definition at line 1262 of file SQLPlatform.php.

References LIST_AND.

◆ makeInsertLists()

Wikimedia\Rdbms\Platform\SQLPlatform::makeInsertLists ( array  $rows,
  $aliasPrefix = '',
array  $typeByColumn = [] 
)

Make SQL lists of columns, row tuples, and column aliases for INSERT/VALUES expressions.

The tuple column order is that of the columns of the first provided row. The provided rows must have exactly the same keys and ordering thereof.

Parameters
array[]$rowsNon-empty list of (column => value) maps
string$aliasPrefixOptional prefix to prepend to the magic alias names
string[]$typeByColumnOptional map of (column => data type)
Returns
array (comma-separated columns, comma-separated tuples, comma-separated aliases)
Since
1.35

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1416 of file SQLPlatform.php.

References LIST_COMMA, and LIST_NAMES.

◆ makeInsertNonConflictingVerbAndOptions()

Wikimedia\Rdbms\Platform\SQLPlatform::makeInsertNonConflictingVerbAndOptions ( )
protected
Stability: stable
to override
Returns
string[] ("INSERT"-style SQL verb, "ON CONFLICT"-style clause or "")
Since
1.35

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, and Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1463 of file SQLPlatform.php.

◆ makeKeyCollisionCondition()

Wikimedia\Rdbms\Platform\SQLPlatform::makeKeyCollisionCondition ( array  $rows,
array  $uniqueKey 
)

Build an SQL condition to find rows with matching key values to those in $rows.

Parameters
array[]$rowsNon-empty list of rows
string[]$uniqueKeyList of columns that define a single unique index
Returns
string

Definition at line 1517 of file SQLPlatform.php.

References LIST_AND, and LIST_OR.

◆ makeList()

Wikimedia\Rdbms\Platform\SQLPlatform::makeList ( array  $a,
  $mode = self::LIST_COMMA 
)

Makes an encoded list of strings from an array.

These can be used to make conjunctions or disjunctions on SQL condition strings derived from an array ({

See also
IDatabase::select} $conds documentation).

Example usage:

$sql = $db->makeList( [
'rev_page' => $id,
$db->makeList( [ 'rev_minor' => 1, 'rev_len < 500' ], $db::LIST_OR )
const LIST_OR
Definition: Defines.php:46
const LIST_AND
Definition: Defines.php:43

This would set $sql to "rev_page = '$id' AND (rev_minor = 1 OR rev_len < 500)"

Parameters
array$aContaining the data
int$modeIDatabase class constant:
  • IDatabase::LIST_COMMA: Comma separated, no field names
  • IDatabase::LIST_AND: ANDed WHERE clause (without the WHERE).
  • IDatabase::LIST_OR: ORed WHERE clause (without the WHERE)
  • IDatabase::LIST_SET: Comma separated with field names, like a SET clause
  • IDatabase::LIST_NAMES: Comma separated field names
Exceptions
DBErrorIf an error occurs, {
See also
IDatabase::query}
Returns
string

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 203 of file SQLPlatform.php.

References LIST_AND, LIST_NAMES, LIST_OR, and LIST_SET.

Referenced by Wikimedia\Rdbms\Platform\MySQLPlatform\deleteJoinSqlText().

◆ makeOrderBy()

Wikimedia\Rdbms\Platform\SQLPlatform::makeOrderBy (   $options)
protected

Returns an optional ORDER BY.

Parameters
array$optionsAssociative array of options
Returns
string
See also
Database::select()
Since
1.21

Definition at line 1288 of file SQLPlatform.php.

◆ makeSelectOptions()

Wikimedia\Rdbms\Platform\SQLPlatform::makeSelectOptions ( array  $options)
protected

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

See also
Database::select()
Stability: stable
to override
Parameters
array$optionsAssociative array of options to be turned into an SQL query, valid keys are listed in the function.
Returns
string[] (START OPTIONS, PRE-LIMIT TAIL, POST-LIMIT TAIL)

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, and Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1202 of file SQLPlatform.php.

◆ makeUpdateOptions()

Wikimedia\Rdbms\Platform\SQLPlatform::makeUpdateOptions (   $options)
protected

Make UPDATE options for the Database::update function.

Stability: stable
to override
Parameters
array$optionsThe options passed to Database::update
Returns
string

Definition at line 1632 of file SQLPlatform.php.

◆ makeUpdateOptionsArray()

Wikimedia\Rdbms\Platform\SQLPlatform::makeUpdateOptionsArray (   $options)
protected

Make UPDATE options array for Database::makeUpdateOptions.

Stability: stable
to override
Parameters
array$options
Returns
array

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform, and Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1645 of file SQLPlatform.php.

◆ makeWhereFrom2d()

Wikimedia\Rdbms\Platform\SQLPlatform::makeWhereFrom2d (   $data,
  $baseKey,
  $subKey 
)

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, however it's assumed that $baseKey is probably an integer-typed column (i.e. integer keys are unquoted in the SQL) and $subKey is string-typed (i.e. integer keys are quoted as strings in the SQL).

Todo:
Does this actually belong in the library? It seems overly MW-specific.
Parameters
array$dataOrganized as 2-d [ baseKeyVal => [ subKeyVal => [ignored], ... ], ... ]
string$baseKeyField name to match the base-level keys to (eg 'pl_namespace')
string$subKeyField name to match the sub-level keys to (eg 'pl_title')
Returns
string|false SQL fragment, or false if no items in array

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 279 of file SQLPlatform.php.

References $base, LIST_AND, and LIST_OR.

◆ normalizeConditions()

Wikimedia\Rdbms\Platform\SQLPlatform::normalizeConditions (   $conds,
  $fname 
)
final
Parameters
array | string$conds
string$fname
Returns
array
Since
1.31

Definition at line 1903 of file SQLPlatform.php.

◆ normalizeJoinType()

Wikimedia\Rdbms\Platform\SQLPlatform::normalizeJoinType ( string  $joinType)
protected

Validate and normalize a join type.

Subclasses may override this to add supported join types.

Parameters
string$joinType
Returns
string

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 946 of file SQLPlatform.php.

◆ normalizeOptions()

Wikimedia\Rdbms\Platform\SQLPlatform::normalizeOptions (   $options)
final
Parameters
string | array$options
Returns
array Combination option/value map and boolean option list
Since
1.35, moved to SQLPlatform in 1.39

Definition at line 1662 of file SQLPlatform.php.

◆ normalizeRowArray()

Wikimedia\Rdbms\Platform\SQLPlatform::normalizeRowArray ( array  $rowOrRows)
finalprotected
Parameters
array$rowOrRowsA single (field => value) map or a list of such maps
Returns
array[] List of (field => value) maps
Since
1.35

Definition at line 1833 of file SQLPlatform.php.

◆ normalizeUpsertParams()

Wikimedia\Rdbms\Platform\SQLPlatform::normalizeUpsertParams (   $uniqueKeys,
$rows 
)
final

Validate and normalize parameters to upsert() or replace()

Parameters
string | string[] | string[][]$uniqueKeysUnique indexes (only one is allowed)
array[]&$rowsThe row array, which will be replaced with a normalized version.
Returns
string[]|null List of columns that defines a single unique index, or null for a legacy fallback to plain insert.
Since
1.35

Definition at line 1862 of file SQLPlatform.php.

◆ qualifiedTableComponents()

Wikimedia\Rdbms\Platform\SQLPlatform::qualifiedTableComponents (   $name)

Get the table components needed for a query given the currently selected database.

Parameters
string$nameTable name in the form of db.schema.table, db.table, or table
Returns
array (DB name or "" for default, schema name, table prefix, table name)

Definition at line 1060 of file SQLPlatform.php.

◆ relationSchemaQualifier()

Wikimedia\Rdbms\Platform\SQLPlatform::relationSchemaQualifier ( )
protected
Stability: stable
to override
Returns
string|null Schema to use to qualify relations in queries

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 1103 of file SQLPlatform.php.

◆ releaseSavepointSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::releaseSavepointSqlText (   $identifier)

Definition at line 1802 of file SQLPlatform.php.

◆ replaceVars()

Wikimedia\Rdbms\Platform\SQLPlatform::replaceVars (   $ins)

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 (e.g. 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.
  • / *_* / or / $wgDBprefix / passes the name that follows through the database's tableName method.
  • / i / passes the name that follows through the database's indexName method.
  • In all other cases, / $var / is left unencoded. Except for table options, its use should be avoided. In 1.24 and older, string encoding was applied.
Stability: stable
to override
Parameters
string$insSQL statement to replace variables in
Returns
string The new SQL statement with variables replaced

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 2101 of file SQLPlatform.php.

◆ rollbackSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::rollbackSqlText ( )

Definition at line 1810 of file SQLPlatform.php.

◆ rollbackToSavepointSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::rollbackToSavepointSqlText (   $identifier)

Definition at line 1806 of file SQLPlatform.php.

◆ savepointSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::savepointSqlText (   $identifier)

Definition at line 1798 of file SQLPlatform.php.

◆ selectSQLText()

Wikimedia\Rdbms\Platform\SQLPlatform::selectSQLText (   $table,
  $vars,
  $conds = '',
  $fname = __METHOD__,
  $options = [],
  $join_conds = [] 
)

Take the same arguments as IDatabase::select() and return the SQL it would use.This can be useful for making UNION queries, where the SQL text of each query is needed. In general, however, callers outside of Database classes should just use select().

See also
IDatabase::select()
Parameters
string | array$tableTable name(s)
string | array$varsField names
string | array$condsConditions
string$fnameCaller function name
string | array$optionsQuery options
string | array$join_condsJoin conditions
Returns
string SQL query string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 656 of file SQLPlatform.php.

References LIST_AND.

Referenced by Wikimedia\Rdbms\Platform\SqlitePlatform\buildGroupConcatField().

◆ setCurrentDomain()

Wikimedia\Rdbms\Platform\SQLPlatform::setCurrentDomain ( DatabaseDomain  $currentDomain)

Definition at line 648 of file SQLPlatform.php.

◆ setIndexAliases()

Wikimedia\Rdbms\Platform\SQLPlatform::setIndexAliases ( array  $aliases)

Convert certain index names to alternative names before querying the DB.Note that this applies to indexes regardless of the table they belong to.This can be employed when an index was renamed X => Y in code, but the new Y-named indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA, the aliases can be removed, and then the old X-named indexes dropped.

Parameters
string[]$aliases
Since
1.31 in IDatabase, moved to ISQLPlatform in 1.39

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 629 of file SQLPlatform.php.

◆ setPrefix()

Wikimedia\Rdbms\Platform\SQLPlatform::setPrefix (   $prefix)

Definition at line 640 of file SQLPlatform.php.

◆ setSchemaVars()

Wikimedia\Rdbms\Platform\SQLPlatform::setSchemaVars (   $vars)

Set schema variables to be used when streaming commands from SQL files or stdin.

Variables appear as SQL comments and are substituted by their corresponding values

Parameters
array | null$varsMap of (variable => value) or null to use the defaults

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 2053 of file SQLPlatform.php.

◆ setTableAliases()

Wikimedia\Rdbms\Platform\SQLPlatform::setTableAliases ( array  $aliases)

Make certain table names use their own database, schema, and table prefix when passed into SQL queries pre-escaped and without a qualified database name.For example, "user" can be converted to "myschema.mydbname.user" for convenience. Appearances like user, somedb.user, somedb.someschema.user will used literally.Calling this twice will completely clear any old table aliases. Also, note that callers are responsible for making sure the schemas and databases actually exist.

Parameters
array[]$aliasesMap of (table => (dbname, schema, prefix) map)
Since
1.28 in IDatabase, moved to ISQLPlatform in 1.39

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 621 of file SQLPlatform.php.

◆ strreplace()

Wikimedia\Rdbms\Platform\SQLPlatform::strreplace (   $orig,
  $old,
  $new 
)

Returns a SQL expression for simple string replacement (e.g.REPLACE() in mysql)

Parameters
string$origColumn to modify
string$oldColumn to seek
string$newColumn to replace with
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 493 of file SQLPlatform.php.

◆ tableName()

Wikimedia\Rdbms\Platform\SQLPlatform::tableName (   $name,
  $format = 'quoted' 
)

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.

Note
This function does not sanitize user input. It is not safe to use this function to escape user input.
Parameters
string$nameDatabase table name
string$formatOne 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
Returns
string Full database name

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 1000 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\MySQLPlatform\deleteJoinSqlText().

◆ tableNames()

Wikimedia\Rdbms\Platform\SQLPlatform::tableNames (   $tables)

Fetch a number of table names into an associative array.

Much like tableName(), this is only needed when calling query() directly. Prefer calling other methods, or using SelectQueryBuilder.

Theoretical example (which really does not require raw SQL): [ 'user' => $user, 'watchlist' => $watchlist ] = $dbr->tableNames( 'user', 'watchlist' ); $sql = "SELECT wl_namespace, wl_title FROM $watchlist, $user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Parameters
string...$tables
Returns
array
Deprecated:
since 1.39; if you must format table names, write several calls to tableName or use tableNamesN instead of calling this function.

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 1127 of file SQLPlatform.php.

◆ tableNamesN()

Wikimedia\Rdbms\Platform\SQLPlatform::tableNamesN (   $tables)

Fetch a number of table names into a zero-indexed numerical array.

Much like tableName(), this is only needed when calling query() directly. It is slightly more convenient than tableNames(), but you should still prefer calling other methods, or using SelectQueryBuilder.

Theoretical example (which really does not require raw SQL): [ $user, $watchlist ] = $dbr->tableNamesN( 'user', 'watchlist' ); $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Parameters
string...$tables
Returns
array

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 1137 of file SQLPlatform.php.

◆ tableNamesWithIndexClauseOrJOIN()

Wikimedia\Rdbms\Platform\SQLPlatform::tableNamesWithIndexClauseOrJOIN (   $tables,
  $use_index = [],
  $ignore_index = [],
  $join_conds = [] 
)
protected

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

Parameters
array$tables( [alias] => table )
array$use_indexSame as for select()
array$ignore_indexSame as for select()
array$join_condsSame as for select()
Returns
string

Definition at line 845 of file SQLPlatform.php.

References LIST_AND.

◆ tableNameWithAlias()

Wikimedia\Rdbms\Platform\SQLPlatform::tableNameWithAlias (   $table,
  $alias = false 
)
protected

Get an aliased table name.

This returns strings like "tableName AS newTableName" for aliased tables and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables)

See also
Database::tableName()
Parameters
string | Subquery$tableTable name or object with a 'sql' field
string | false$aliasTable alias (optional)
Returns
string SQL name for aliased table. Will not alias a table to its own name

Definition at line 976 of file SQLPlatform.php.

◆ timestamp()

Wikimedia\Rdbms\Platform\SQLPlatform::timestamp (   $ts = 0)

Convert a timestamp in one of the formats accepted by ConvertibleTimestamp 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.

Parameters
string | int$ts
Returns
string

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\PostgresPlatform.

Definition at line 501 of file SQLPlatform.php.

References $t.

◆ timestampOrNull()

Wikimedia\Rdbms\Platform\SQLPlatform::timestampOrNull (   $ts = null)

Convert a timestamp in one of the formats accepted by ConvertibleTimestamp 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.

Parameters
string | int | null$ts
Returns
string|null

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 507 of file SQLPlatform.php.

◆ unionConditionPermutations()

Wikimedia\Rdbms\Platform\SQLPlatform::unionConditionPermutations (   $table,
  $vars,
array  $permute_conds,
  $extra_conds = '',
  $fname = __METHOD__,
  $options = [],
  $join_conds = [] 
)

Construct a UNION query for permutations of conditions.

Databases sometimes have trouble with queries that have multiple values for multiple condition parameters combined with limits and ordering. This method constructs queries for the Cartesian product of the conditions and unions them all together.

See also
IDatabase::select()
Parameters
string | array$tableTable name
string | array$varsField names
array$permute_condsConditions for the Cartesian product. Keys are field names, values are arrays of the possible values for that field.
string | array$extra_condsAdditional conditions to include in the query.
string$fnameCaller function name
string | array$optionsQuery options. In addition to the options recognized by IDatabase::select(), the following may be used:
  • NOTALL: Set to use UNION instead of UNION ALL.
  • INNER ORDER BY: If specified and supported, subqueries will use this instead of ORDER BY.
string | array$join_condsJoin conditions
Returns
string SQL query string.
Since
1.30

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Definition at line 1300 of file SQLPlatform.php.

◆ unionQueries()

Wikimedia\Rdbms\Platform\SQLPlatform::unionQueries (   $sqls,
  $all 
)

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

Parameters
array$sqlsSQL statements to combine
bool$allEither IDatabase::UNION_ALL or IDatabase::UNION_DISTINCT
Returns
string SQL fragment

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 471 of file SQLPlatform.php.

◆ unionSupportsOrderAndLimit()

Wikimedia\Rdbms\Platform\SQLPlatform::unionSupportsOrderAndLimit ( )

Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION.

Returns
bool

Stability: stable
to override

Implements Wikimedia\Rdbms\Platform\ISQLPlatform.

Reimplemented in Wikimedia\Rdbms\Platform\SqlitePlatform.

Definition at line 463 of file SQLPlatform.php.

◆ unlockSQLText()

Wikimedia\Rdbms\Platform\SQLPlatform::unlockSQLText (   $lockName)

◆ updateSqlText()

Wikimedia\Rdbms\Platform\SQLPlatform::updateSqlText (   $table,
  $set,
  $conds,
  $options 
)

Definition at line 1585 of file SQLPlatform.php.

References LIST_AND, and LIST_SET.

◆ useIndexClause()

Wikimedia\Rdbms\Platform\SQLPlatform::useIndexClause (   $index)

USE INDEX clause.

This can be used as optimisation in queries that affect tables with multiple indexes if the database does not pick the most optimal one by default. The "right" index might vary between database backends and versions thereof, as such in practice this is biased toward specifically improving performance of large wiki farms that use MySQL or MariaDB (like Wikipedia).

Stability: stable
to override
Parameters
string$index
Returns
string

Reimplemented in Wikimedia\Rdbms\Platform\MySQLPlatform.

Definition at line 1174 of file SQLPlatform.php.

Member Data Documentation

◆ $currentDomain

DatabaseDomain null Wikimedia\Rdbms\Platform\SQLPlatform::$currentDomain
protected

Definition at line 48 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SQLPlatform\__construct().

◆ $errorLogger

callable Wikimedia\Rdbms\Platform\SQLPlatform::$errorLogger
protected

Error logging callback.

Definition at line 56 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SQLPlatform\__construct().

◆ $indexAliases

string [] Wikimedia\Rdbms\Platform\SQLPlatform::$indexAliases = []
protected

Current map of (index alias => index)

Definition at line 46 of file SQLPlatform.php.

◆ $logger

LoggerInterface Wikimedia\Rdbms\Platform\SQLPlatform::$logger
protected

Definition at line 54 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SQLPlatform\__construct().

◆ $quoter

DbQuoter Wikimedia\Rdbms\Platform\SQLPlatform::$quoter
protected

Definition at line 52 of file SQLPlatform.php.

Referenced by Wikimedia\Rdbms\Platform\SQLPlatform\__construct().

◆ $schemaVars

array null Wikimedia\Rdbms\Platform\SQLPlatform::$schemaVars
protected

Current variables use for schema element placeholders.

Definition at line 50 of file SQLPlatform.php.

◆ $tableAliases

array [] Wikimedia\Rdbms\Platform\SQLPlatform::$tableAliases = []
protected

Current map of (table => (dbname, schema, prefix) map)

Definition at line 44 of file SQLPlatform.php.


The documentation for this class was generated from the following file: