diff --git a/includes/libs/rdbms/database/Database.php b/includes/libs/rdbms/database/Database.php index 1a19856b94b..07d8408a16c 100644 --- a/includes/libs/rdbms/database/Database.php +++ b/includes/libs/rdbms/database/Database.php @@ -1455,7 +1455,7 @@ abstract class Database implements Stringable, IDatabaseForOwner, IMaintainableD /** * Get information about an index into an object * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $index Index name * @param string $fname Calling function name * @return array|false Index info map; false if it does not exist @@ -1681,7 +1681,7 @@ abstract class Database implements Stringable, IDatabaseForOwner, IMaintainableD } /** - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @return string|null The AUTO_INCREMENT/SERIAL column; null if not needed */ protected function getInsertIdColumnForUpsert( $table ) { @@ -1689,7 +1689,7 @@ abstract class Database implements Stringable, IDatabaseForOwner, IMaintainableD } /** - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @return array Map of (column => type); [] if not needed */ protected function getValueTypesForWithClause( $table ) { @@ -1842,8 +1842,8 @@ abstract class Database implements Stringable, IDatabaseForOwner, IMaintainableD * we don't want to select everything into memory * * @see IDatabase::insertSelect() - * @param string $destTable Unqualified name of destination table - * @param string|array $srcTable Unqualified name of source table + * @param string $destTable The unqualified name of destination table + * @param string|array $srcTable The unqualified name of source table * @param array $varMap * @param array $conds * @param string $fname diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php index 0f9ff7ae244..3641112020c 100644 --- a/includes/libs/rdbms/database/IDatabase.php +++ b/includes/libs/rdbms/database/IDatabase.php @@ -258,7 +258,7 @@ interface IDatabase extends IReadableDatabase { /** * Lock all rows meeting the given conditions/options FOR UPDATE * - * @param string|string[] $table Unqualified name of table(s) (use an array for a join) + * @param string|string[] $table The unqualified name of table(s) (use an array for a join) * @param string|IExpression|array|RawSQLValue>|array $conds * Condition in the format of IDatabase::select() conditions * @param string $fname Function name for profiling @@ -281,7 +281,7 @@ interface IDatabase extends IReadableDatabase { * * @internal callers outside of rdbms library should use InsertQueryBuilder instead. * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param array|array[] $rows Row(s) to insert, as either: * - A string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. @@ -307,7 +307,7 @@ interface IDatabase extends IReadableDatabase { * * @internal callers outside of rdbms library should use UpdateQueryBuilder instead. * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @param array|array $set * Combination map/list where each string-keyed entry maps a column @@ -359,7 +359,7 @@ interface IDatabase extends IReadableDatabase { * * @internal callers outside of rdbms library should use ReplaceQueryBuilder instead. * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string|string[]|string[][] $uniqueKeys Column name or non-empty list of column * name lists that define all applicable unique keys on the table. There must only be * one such key. Each unique key on the table is "applicable" unless either: @@ -389,7 +389,7 @@ interface IDatabase extends IReadableDatabase { * * @internal callers outside of rdbms library should use InsertQueryBuilder instead. * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param array|array[] $rows Row(s) to insert, in the form of either: * - A string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. @@ -432,8 +432,8 @@ interface IDatabase extends IReadableDatabase { * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * - * @param string $delTable Unqualified name of table to delete rows from. - * @param string $joinTable Unqualified name of reference table to join on. + * @param string $delTable The unqualified name of the table to delete rows from. + * @param string $joinTable The unqualified name of the reference table to join on. * @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 string|IExpression|array|RawSQLValue>|array $conds @@ -459,7 +459,7 @@ interface IDatabase extends IReadableDatabase { * * @internal callers outside of rdbms library should use DeleteQueryBuilder instead. * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @param string|IExpression|array|RawSQLValue>|array $conds * Array of conditions. See $conds in IDatabase::select() diff --git a/includes/libs/rdbms/database/IMaintainableDatabase.php b/includes/libs/rdbms/database/IMaintainableDatabase.php index f90fb9cc24a..04ce2af513d 100644 --- a/includes/libs/rdbms/database/IMaintainableDatabase.php +++ b/includes/libs/rdbms/database/IMaintainableDatabase.php @@ -89,7 +89,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Delete a table * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $fname * @return bool Whether the table already existed * @throws DBError If an error occurs @@ -99,7 +99,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Delete all data in a table and reset any sequences owned by that table * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $fname * @throws DBError If an error occurs * @since 1.42 @@ -141,7 +141,7 @@ interface IMaintainableDatabase extends IDatabase { * Get information about a field * Returns false if the field doesn't exist * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $field Field name * * @return false|Field @@ -151,7 +151,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Determines whether a field exists in a table * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $field Field to check on that table * @param string $fname Calling function name (optional) * @return bool Whether $table has field $field @@ -162,7 +162,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Determines whether an index exists * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $index * @param string $fname * @return bool @@ -173,7 +173,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Determines if a given index is unique * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $index * @param string $fname Calling function name * @return bool|null Returns null if the index does not exist @@ -184,7 +184,7 @@ interface IMaintainableDatabase extends IDatabase { /** * Query whether a given table exists * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string $fname * @return bool * @throws DBError If an error occurs, {@see query} diff --git a/includes/libs/rdbms/database/IReadableDatabase.php b/includes/libs/rdbms/database/IReadableDatabase.php index 907866465ec..083e603dfa7 100644 --- a/includes/libs/rdbms/database/IReadableDatabase.php +++ b/includes/libs/rdbms/database/IReadableDatabase.php @@ -167,8 +167,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * * @internal callers outside of rdbms library should use SelectQueryBuilder instead. * - * @param string|array $tables Table reference(s) using unqualified table names. - * {@see select} for details. + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param-taint $tables exec_sql * @param string|array $var The field name to select. This must be a valid SQL fragment: do not * use unvalidated user input. Can be an array, but must contain exactly 1 element then. @@ -201,8 +201,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * * @internal callers outside of rdbms library should use SelectQueryBuilder instead. * - * @param string|array $tables Table reference(s) using unqualified table names. - * {@see select} for details. + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param-taint $tables exec_sql * @param string $var The field name to select. This must be a valid SQL * fragment: do not use unvalidated user input. @@ -232,7 +232,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchResultSet} * instead, which is more readable and less error-prone. * - * @param string|array $tables Table reference(s) using unqualified table names. + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". * @param-taint $tables exec_sql * * Each table reference assigns a table name to a specified collection of rows @@ -451,8 +452,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * instead, which is more readable and less error-prone. * * @internal - * @param string|array $tables Table reference(s) using unqualified table names. - * {@see select} for details. + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param-taint $tables exec_sql * @param string|array $vars Field names * @param-taint $vars exec_sql @@ -495,7 +496,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * instead, which is more readable and less error-prone. * * @internal - * @param string|string[] $tables Unqualified name of table(s) + * @param string|string[] $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param string $var Column for which NULL values are not counted [default "*"] * @param string|IExpression|array|RawSQLValue>|array $conds * Filters on the table @@ -522,7 +524,8 @@ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabas * @since 1.27 Added $join_conds parameter * * @internal - * @param string|string[] $tables Unqualified name of table(s) + * @param string|string[] $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param-taint $tables exec_sql * @param string $var Column for which NULL values are not counted [default "*"] * @param-taint $var exec_sql diff --git a/includes/libs/rdbms/platform/ISQLPlatform.php b/includes/libs/rdbms/platform/ISQLPlatform.php index 6816522dc6f..0a990def14e 100644 --- a/includes/libs/rdbms/platform/ISQLPlatform.php +++ b/includes/libs/rdbms/platform/ISQLPlatform.php @@ -486,7 +486,7 @@ interface ISQLPlatform { * 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. * - * @param array[] $aliases Map of (unqualified table name => (dbname, schema, prefix) map) + * @param array[] $aliases Map of (unqualified name of table => (dbname, schema, prefix) map) * @since 1.28 in IDatabase, moved to ISQLPlatform in 1.39 */ public function setTableAliases( array $aliases ); @@ -521,7 +521,8 @@ interface ISQLPlatform { * * @see IDatabase::select() * - * @param string|array $tables Table reference(s) using unqualified table names + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". * @param-taint $tables exec_sql * @param string|array $vars Field names * @param-taint $vars exec_sql @@ -556,13 +557,20 @@ interface ISQLPlatform { * themselves. Pass the canonical name to such functions. This is only needed * when calling {@link query()} directly. * + * The provided name should not qualify the database nor the schema, unless the name + * is of the form "information_schema.". Unlike information_schema tables, + * regular tables can receive writes and are subject to configuration regarding table + * aliases, virtual domains, and LBFactory sharding. Callers needing to access remote + * databases should use appropriate connection factory methods. + * * @note This function does not sanitize user input. It is not safe to use * this function to escape user input. - * @param string $name Unqualified name of table (no quotes, db, schema, nor table prefix) + * @param string $name The unqualified name of a table (no quotes, db, schema, nor table + * prefix), or a table name of the form "information_schema.". * @param string $format One of: * quoted - Automatically pass the table name through addIdentifierQuotes() * so that it can be used in a query. - * raw - Do not add identifier quotes to the table name + * raw - Do not add identifier quotes to the table name. * @return string Qualified table name (includes any applicable prefix or foreign db/schema) */ public function tableName( string $name, $format = 'quoted' ); @@ -621,7 +629,8 @@ interface ISQLPlatform { * 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 $tables Table reference(s) using unqualified table names + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param string $field Field name * @param string|IExpression|array|RawSQLValue>|array $conds * Conditions @@ -638,7 +647,8 @@ interface ISQLPlatform { * * @see IDatabase::selectSQLText() * - * @param string|array $tables Table reference(s) using unqualified table names + * @param string|array $tables Table reference(s), using the unqualified name of tables + * or of the form "information_schema.". {@see select} for details. * @param string|array $vars Field names * @param string|array $conds Conditions * @param string $fname Caller function name diff --git a/includes/libs/rdbms/platform/SQLPlatform.php b/includes/libs/rdbms/platform/SQLPlatform.php index eeeded6ca50..8dbfdbee2a1 100644 --- a/includes/libs/rdbms/platform/SQLPlatform.php +++ b/includes/libs/rdbms/platform/SQLPlatform.php @@ -1014,7 +1014,7 @@ class SQLPlatform implements ISQLPlatform { * and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables) * * @see Database::tableName() - * @param string|Subquery $table Unqualified table name or subquery + * @param string|Subquery $table The unqualified name of a table, or Subquery * @param string|false $alias Table alias (optional) * @return string SQL name for aliased table. Will not alias a table to its own name */ @@ -1577,7 +1577,7 @@ class SQLPlatform implements ISQLPlatform { } /** - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param string|array $conds * @return Query */ diff --git a/includes/libs/rdbms/querybuilder/DeleteQueryBuilder.php b/includes/libs/rdbms/querybuilder/DeleteQueryBuilder.php index 6de48063580..25733f93138 100644 --- a/includes/libs/rdbms/querybuilder/DeleteQueryBuilder.php +++ b/includes/libs/rdbms/querybuilder/DeleteQueryBuilder.php @@ -95,7 +95,7 @@ class DeleteQueryBuilder { /** * Manually set the table name to be passed to IDatabase::delete() * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -107,7 +107,7 @@ class DeleteQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -118,7 +118,7 @@ class DeleteQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ diff --git a/includes/libs/rdbms/querybuilder/InsertQueryBuilder.php b/includes/libs/rdbms/querybuilder/InsertQueryBuilder.php index 8999b79a209..70de83463da 100644 --- a/includes/libs/rdbms/querybuilder/InsertQueryBuilder.php +++ b/includes/libs/rdbms/querybuilder/InsertQueryBuilder.php @@ -130,7 +130,7 @@ class InsertQueryBuilder { /** * Manually set the table name to be passed to IDatabase::insert() * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -142,7 +142,7 @@ class InsertQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -153,7 +153,7 @@ class InsertQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ diff --git a/includes/libs/rdbms/querybuilder/JoinGroupBase.php b/includes/libs/rdbms/querybuilder/JoinGroupBase.php index e59e69bb8fe..99d0864fe52 100644 --- a/includes/libs/rdbms/querybuilder/JoinGroupBase.php +++ b/includes/libs/rdbms/querybuilder/JoinGroupBase.php @@ -21,8 +21,9 @@ abstract class JoinGroupBase { /** * Add a single table or a single parenthesized group. * - * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, a - * JoinGroup containing multiple tables, or a SelectQueryBuilder representing a subquery. + * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, + * a table name of the form "information_schema.", a JoinGroup + * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param-taint $table exec_sql * @param string|null $alias The table alias, or null for no alias * @param-taint $alias exec_sql @@ -57,8 +58,9 @@ abstract class JoinGroupBase { /** * Left join a table or group of tables. This should be called after table(). * - * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, a - * JoinGroup containing multiple tables, or a SelectQueryBuilder representing a subquery. + * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, + * a table name of the form "information_schema.", a JoinGroup + * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause @@ -72,8 +74,9 @@ abstract class JoinGroupBase { /** * Inner join a table or group of tables. This should be called after table(). * - * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, a - * JoinGroup containing multiple tables, or a SelectQueryBuilder representing a subquery. + * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, + * a table name of the form "information_schema.", a JoinGroup + * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause @@ -87,8 +90,9 @@ abstract class JoinGroupBase { /** * Straight join a table or group of tables. This should be called after table(). * - * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, a - * JoinGroup containing multiple tables, or a SelectQueryBuilder representing a subquery. + * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, + * a table name of the form "information_schema.", a JoinGroup + * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause diff --git a/includes/libs/rdbms/querybuilder/ReplaceQueryBuilder.php b/includes/libs/rdbms/querybuilder/ReplaceQueryBuilder.php index c666c10fcb6..154d56de407 100644 --- a/includes/libs/rdbms/querybuilder/ReplaceQueryBuilder.php +++ b/includes/libs/rdbms/querybuilder/ReplaceQueryBuilder.php @@ -103,7 +103,7 @@ class ReplaceQueryBuilder { /** * Manually set the table name to be passed to IDatabase::replace() * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -115,7 +115,7 @@ class ReplaceQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ diff --git a/includes/libs/rdbms/querybuilder/UpdateQueryBuilder.php b/includes/libs/rdbms/querybuilder/UpdateQueryBuilder.php index fdfc2334d97..63b07c56155 100644 --- a/includes/libs/rdbms/querybuilder/UpdateQueryBuilder.php +++ b/includes/libs/rdbms/querybuilder/UpdateQueryBuilder.php @@ -115,7 +115,7 @@ class UpdateQueryBuilder { /** * Manually set the table name to be passed to IDatabase::update() * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ @@ -127,7 +127,7 @@ class UpdateQueryBuilder { /** * Set table for the query. Alias for table(). * - * @param string $table Unqualified name of table + * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */