Make addIdentifierQuotes part of IDatabase

[lhc/web/wiklou.git] / includes / libs / rdbms / database / IDatabase.php

diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index 4cbe586..7d9eac1 100644 (file)
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -924,8 +924,7 @@ interface IDatabase {
         * @param array $a Array of rows to insert
         * @param string $fname Calling function name (use __METHOD__) for logs/profiling
         * @param array $options Array of options
-        *
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function insert( $table, $a, $fname = __METHOD__, $options = [] );
@@ -948,7 +947,7 @@ interface IDatabase {
         * @param array $options An array of UPDATE options, can be:
         *   - IGNORE: Ignore unique key conflicts
         *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] );
@@ -1113,11 +1112,13 @@ interface IDatabase {
        /**
         * Change the current database
         *
+        * This should not be called outside LoadBalancer for connections managed by a LoadBalancer
+        *
         * @param string $db
         * @return bool True unless an exception was thrown
         * @throws DBConnectionError If databasesAreIndependent() is true and an error occurs
         * @throws DBError
-        * @deprecated Since 1.32
+        * @deprecated Since 1.32 Use selectDomain() instead
         */
        public function selectDB( $db );
 
@@ -1126,6 +1127,8 @@ interface IDatabase {
         *
         * This will throw an error for some database types if the database unspecified
         *
+        * This should not be called outside LoadBalancer for connections managed by a LoadBalancer
+        *
         * @param string|DatabaseDomain $domain
         * @since 1.32
         * @throws DBConnectionError
@@ -1152,6 +1155,17 @@ interface IDatabase {
         */
        public function addQuotes( $s );
 
+       /**
+        * Quotes an identifier, in order to make user controlled input safe
+        *
+        * Depending on the database this will either be `backticks` or "double quotes"
+        *
+        * @param string $s
+        * @return string
+        * @since 1.33
+        */
+       public function addIdentifierQuotes( $s );
+
        /**
         * LIKE statement wrapper, receives a variable-length argument list with
         * parts of pattern to match containing either string literals that will be
@@ -1262,7 +1276,7 @@ interface IDatabase {
         *   things like "field = field + 1" or similar computed values.
         * @param string $fname Calling function name (use __METHOD__) for logs/profiling
         * @throws DBError
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         */
        public function upsert(
                $table, array $rows, array $uniqueIndexes, array $set, $fname = __METHOD__
@@ -1300,7 +1314,7 @@ interface IDatabase {
         *   for the format. Use $conds == "*" to delete all rows
         * @param string $fname Name of the calling function
         * @throws DBUnexpectedError
-        * @return bool|IResultWrapper
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function delete( $table, $conds, $fname = __METHOD__ );
@@ -1338,7 +1352,7 @@ interface IDatabase {
         * @param array $selectJoinConds Join conditions for the SELECT part of the query, see
         *    IDatabase::select() for details.
         *
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function insertSelect( $destTable, $srcTable, $varMap, $conds,
@@ -1472,6 +1486,10 @@ interface IDatabase {
        /**
         * Wait for the replica DB to catch up to a given master position
         *
+        * Note that this does not start any new transactions. If any existing transaction
+        * is flushed, and this is called, then queries will reflect the point the DB was synced
+        * up to (on success) without interference from REPEATABLE-READ snapshots.
+        *
         * @param DBMasterPos $pos
         * @param int $timeout The maximum number of seconds to wait for synchronisation
         * @return int|null Zero if the replica DB was past that position already,