From c08ea2e813bd3677f6fced92cac97a2670e4fe55 Mon Sep 17 00:00:00 2001 From: Aaron Schulz Date: Fri, 6 Sep 2024 11:52:31 -0700 Subject: [PATCH] rdbms: make table name parameter comments more complete and uniform Better emphasize that there should only be one string that callers use to reference a given table. This is what ChangedTablesTracker relies on for write queries. For read queries, databases can be vertically sharded on different servers or remapped using virtual domains, so the use of "db.table" notation should be discouraged there as well. Mention that "information_schema." is allowed as well as unqualified table names. Change-Id: I0b6295d0dd58aafd09a5c99aaf0ae9a81641d55a --- includes/libs/rdbms/database/Database.php | 10 ++++----- includes/libs/rdbms/database/IDatabase.php | 16 +++++++------- .../rdbms/database/IMaintainableDatabase.php | 14 ++++++------ .../libs/rdbms/database/IReadableDatabase.php | 21 ++++++++++-------- includes/libs/rdbms/platform/ISQLPlatform.php | 22 ++++++++++++++----- includes/libs/rdbms/platform/SQLPlatform.php | 4 ++-- .../rdbms/querybuilder/DeleteQueryBuilder.php | 6 ++--- .../rdbms/querybuilder/InsertQueryBuilder.php | 6 ++--- .../libs/rdbms/querybuilder/JoinGroupBase.php | 20 ++++++++++------- .../querybuilder/ReplaceQueryBuilder.php | 4 ++-- .../rdbms/querybuilder/UpdateQueryBuilder.php | 4 ++-- 11 files changed, 72 insertions(+), 55 deletions(-) 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 */