Merge "Add wfWaitForSlaves() to maintenance/migrateComments.php"

[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 78889e5..bbf88dc 100644 (file)
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -346,6 +346,7 @@ interface IDatabase {
         * Alias for getDomainID()
         *
         * @return string
+        * @deprecated 1.30
         */
        public function getWikiID();
 
@@ -568,7 +569,8 @@ interface IDatabase {
         * @param string|array $options The query options. See IDatabase::select() for details.
         * @param string|array $join_conds The query join conditions. See IDatabase::select() for details.
         *
-        * @return bool|mixed The value from the field, or false on failure.
+        * @return mixed The value from the field
+        * @throws DBQueryError
         */
        public function selectField(
                $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
@@ -590,7 +592,8 @@ interface IDatabase {
         * @param string|array $options The query options. See IDatabase::select() for details.
         * @param string|array $join_conds The query join conditions. See IDatabase::select() for details.
         *
-        * @return bool|array The values from the field, or false on failure
+        * @return array The values from the field
+        * @throws DBQueryError
         * @since 1.25
         */
        public function selectFieldValues(
@@ -619,6 +622,19 @@ interface IDatabase {
         * This includes the user table in the query, with the alias "a" available
         * for use in field names (e.g. a.user_name).
         *
+        * Joins using parentheses for grouping (since MediaWiki 1.31) may be
+        * constructed using nested arrays. For example,
+        *
+        *    [ 'tableA', 'nestedB' => [ 'tableB', 'b2' => 'tableB2' ] ]
+        *
+        * along with `$join_conds` like
+        *
+        *    [ 'b2' => [ 'JOIN', 'b_id = b2_id' ], 'nestedB' => [ 'LEFT JOIN', 'b_a = a_id' ] ]
+        *
+        * will produce SQL something like
+        *
+        *    FROM tableA LEFT JOIN (tableB JOIN tableB2 AS b2 ON (b_id = b2_id)) ON (b_a = a_id)
+        *
         * All of the table names given here are automatically run through
         * Database::tableName(), which causes the table prefix (if any) to be
         * added, and various other table name mappings to be performed.
@@ -741,10 +757,8 @@ interface IDatabase {
         *
         *    [ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ]
         *
-        * @return IResultWrapper|bool If the query returned no rows, a IResultWrapper
-        *   with no rows in it will be returned. If there was a query error, a
-        *   DBQueryError exception will be thrown, except if the "ignore errors"
-        *   option was set, in which case false will be returned.
+        * @return IResultWrapper Resulting rows
+        * @throws DBQueryError
         */
        public function select(
                $table, $vars, $conds = '', $fname = __METHOD__,
@@ -785,6 +799,7 @@ interface IDatabase {
         * @param array|string $join_conds Join conditions
         *
         * @return stdClass|bool
+        * @throws DBQueryError
         */
        public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
                $options = [], $join_conds = []
@@ -809,6 +824,7 @@ interface IDatabase {
         * @param string $fname Function name for profiling
         * @param array $options Options for select
         * @return int Row count
+        * @throws DBQueryError
         */
        public function estimateRowCount(
                $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = []
@@ -830,6 +846,7 @@ interface IDatabase {
         * @param array $options Options for select
         * @param array $join_conds Join conditions (since 1.27)
         * @return int Row count
+        * @throws DBQueryError
         */
        public function selectRowCount(
                $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
@@ -1593,6 +1610,8 @@ interface IDatabase {
         * throwing an Exception is preferrable, using a pre-installed error handler to trigger
         * rollback (in any case, failure to issue COMMIT will cause rollback server-side).
         *
+        * Query, connection, and onTransaction* callback errors will be suppressed and logged.
+        *
         * @param string $fname Calling function name
         * @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_*
         *   constant to disable warnings about calling rollback when no transaction is in