rdbms: add IDatabase::wasConnectionLoss() method

[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 28a8125..e5e2076 100644 (file)
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -357,7 +357,7 @@ interface IDatabase {
        public function getType();
 
        /**
-        * Open a connection to the database. Usually aborts on failure
+        * Open a new connection to the database (closing any existing one)
         *
         * @param string $server Database server host
         * @param string $user Database user name
@@ -492,8 +492,11 @@ interface IDatabase {
        public function getServerVersion();
 
        /**
-        * Closes a database connection.
-        * if it is open : commits any open transactions
+        * Close the database connection
+        *
+        * This should only be called after any transactions have been resolved,
+        * aside from read-only transactions (assuming no callbacks are registered).
+        * If a transaction is still open anyway, it will be committed if possible.
         *
         * @throws DBError
         * @return bool Operation success. true if already closed.
@@ -510,6 +513,10 @@ interface IDatabase {
         * Run an SQL query and return the result. Normally throws a DBQueryError
         * on failure. If errors are ignored, returns false instead.
         *
+        * If a connection loss is detected, then an attempt to reconnect will be made.
+        * For queries that involve no larger transactions or locks, they will be re-issued
+        * for convenience, provided the connection was re-established.
+        *
         * In new code, the query wrappers select(), insert(), update(), delete(),
         * etc. should be used where possible, since they give much better DBMS
         * independence and automatically quote or validate user input in a variety
@@ -822,11 +829,12 @@ interface IDatabase {
         * @param array|string $conds Filters on the table
         * @param string $fname Function name for profiling
         * @param array $options Options for select
+        * @param array|string $join_conds Join conditions
         * @return int Row count
         * @throws DBError
         */
        public function estimateRowCount(
-               $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = []
+               $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
        );
 
        /**
@@ -1396,6 +1404,8 @@ interface IDatabase {
        /**
         * Determines if the last failure was due to a deadlock
         *
+        * Note that during a deadlock, the prior transaction will have been lost
+        *
         * @return bool
         */
        public function wasDeadlock();
@@ -1403,17 +1413,21 @@ interface IDatabase {
        /**
         * Determines if the last failure was due to a lock timeout
         *
+        * Note that during a lock wait timeout, the prior transaction will have been lost
+        *
         * @return bool
         */
        public function wasLockTimeout();
 
        /**
-        * Determines if the last query error was due to a dropped connection and should
-        * be dealt with by pinging the connection and reissuing the query.
+        * Determines if the last query error was due to a dropped connection
+        *
+        * Note that during a connection loss, the prior transaction will have been lost
         *
         * @return bool
+        * @since 1.31
         */
-       public function wasErrorReissuable();
+       public function wasConnectionLoss();
 
        /**
         * Determines if the last failure was due to the database being read-only.
@@ -1422,6 +1436,15 @@ interface IDatabase {
         */
        public function wasReadOnlyError();
 
+       /**
+        * Determines if the last query error was due to something outside of the query itself
+        *
+        * Note that the transaction may have been lost, discarding prior writes and results
+        *
+        * @return bool
+        */
+       public function wasErrorReissuable();
+
        /**
         * Wait for the replica DB to catch up to a given master position
         *
@@ -1927,6 +1950,21 @@ interface IDatabase {
         * @since 1.28
         */
        public function setTableAliases( array $aliases );
+
+       /**
+        * Convert certain index names to alternative names before querying the DB
+        *
+        * Note that this applies to indexes regardless of the table they belong to.
+        *
+        * This can be employed when an index was renamed X => Y in code, but the new Y-named
+        * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA,
+        * the aliases can be removed, and then the old X-named indexes dropped.
+        *
+        * @param string[] $aliases
+        * @return mixed
+        * @since 1.31
+        */
+       public function setIndexAliases( array $aliases );
 }
 
 class_alias( IDatabase::class, 'IDatabase' );