Merge "rdbms: make table name parameter comments more complete and uniform"

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<string,mixed>|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<string,string> 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

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<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $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<string,?scalar|RawSQLValue>|array<int,string> $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<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $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<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds
 	 *   Array of conditions. See $conds in IDatabase::select()

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}

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.<identifier>". {@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.<identifier>". {@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.<identifier>".
 	 * @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.<identifier>". {@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.<identifier>". {@see select} for details.
 	 * @param string $var Column for which NULL values are not counted [default "*"]
 	 * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $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.<identifier>". {@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

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.<identifier>".
 	 * @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.<identifier>". 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.<unquoted identifier>".
 	 * @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.<identifier>". {@see select} for details.
 	 * @param string $field Field name
 	 * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $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.<identifier>". {@see select} for details.
 	 * @param string|array $vars Field names
 	 * @param string|array $conds Conditions
 	 * @param string $fname Caller function name

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
 	 */

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
 	 */

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
 	 */

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.<unquoted identifier>", 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.<unquoted identifier>", 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.<unquoted identifier>", 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.<unquoted identifier>", 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

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
 	 */

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
 	 */