Aaron Schulz has uploaded a new change for review.

  https://gerrit.wikimedia.org/r/312462

Change subject: Add IMaintainableDatabase for non-OLTP type methods
......................................................................

Add IMaintainableDatabase for non-OLTP type methods

Change-Id: I4cbdfd7a40af17269c527df6e1c3c5644672b8a7
---
M autoload.php
M includes/libs/rdbms/database/Database.php
M includes/libs/rdbms/database/IDatabase.php
A includes/libs/rdbms/database/IMaintainableDatabase.php
4 files changed, 200 insertions(+), 116 deletions(-)


  git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core 
refs/changes/62/312462/1

diff --git a/autoload.php b/autoload.php
index a352884..db29f3d 100644
--- a/autoload.php
+++ b/autoload.php
@@ -585,6 +585,7 @@
        'IJobSpecification' => __DIR__ . 
'/includes/jobqueue/JobSpecification.php',
        'ILoadBalancer' => __DIR__ . 
'/includes/libs/rdbms/loadbalancer/ILoadBalancer.php',
        'ILoadMonitor' => __DIR__ . 
'/includes/libs/rdbms/loadmonitor/ILoadMonitor.php',
+       'IMaintainableDatabase' => __DIR__ . 
'/includes/libs/rdbms/database/IMaintainableDatabase.php',
        'IP' => __DIR__ . '/includes/libs/IP.php',
        'IPSet' => __DIR__ . '/includes/compat/IPSetCompat.php',
        'IPTC' => __DIR__ . '/includes/media/IPTC.php',
diff --git a/includes/libs/rdbms/database/Database.php 
b/includes/libs/rdbms/database/Database.php
index f56f380..ae13124 100644
--- a/includes/libs/rdbms/database/Database.php
+++ b/includes/libs/rdbms/database/Database.php
@@ -27,10 +27,12 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * Database abstraction object
+ * Relational database abstraction object
+ *
  * @ingroup Database
+ * @since 1.28
  */
-abstract class Database implements IDatabase, LoggerAwareInterface {
+abstract class Database implements IDatabase, IMaintainableDatabase, 
LoggerAwareInterface {
        /** Number of times to re-try an operation in case of deadlock */
        const DEADLOCK_TRIES = 4;
        /** Minimum time to wait before retry, in microseconds */
@@ -1673,25 +1675,6 @@
                return $this->mServer;
        }
 
-       /**
-        * Format a table name ready for use in constructing an SQL query
-        *
-        * This does two important things: it quotes the table names to clean 
them up,
-        * and it adds a table prefix if only given a table name with no quotes.
-        *
-        * All functions of this object which require a table name call this 
function
-        * themselves. Pass the canonical name to such functions. This is only 
needed
-        * when calling query() directly.
-        *
-        * @note This function does not sanitize user input. It is not safe to 
use
-        *   this function to escape user input.
-        * @param string $name Database table name
-        * @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
-        * @return string Full database name
-        */
        public function tableName( $name, $format = 'quoted' ) {
                # Skip the entire process when we have a string quoted on both 
ends.
                # Note that we check the end so that we will still quote any 
use of
@@ -1772,17 +1755,6 @@
                return $tableName;
        }
 
-       /**
-        * Fetch a number of table names into an array
-        * This is handy when you need to construct SQL for joins
-        *
-        * Example:
-        * extract( $dbr->tableNames( 'user', 'watchlist' ) );
-        * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
-        *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
-        *
-        * @return array
-        */
        public function tableNames() {
                $inArray = func_get_args();
                $retVal = [];
@@ -1794,17 +1766,6 @@
                return $retVal;
        }
 
-       /**
-        * Fetch a number of table names into an zero-indexed numerical array
-        * This is handy when you need to construct SQL for joins
-        *
-        * Example:
-        * list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' );
-        * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
-        *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
-        *
-        * @return array
-        */
        public function tableNamesN() {
                $inArray = func_get_args();
                $retVal = [];
@@ -2238,13 +2199,6 @@
                $this->query( $sql, $fname );
        }
 
-       /**
-        * Returns the size of a text field, or -1 for "unlimited"
-        *
-        * @param string $table
-        * @param string $field
-        * @return int
-        */
        public function textFieldSize( $table, $field ) {
                $table = $this->tableName( $table );
                $sql = "SHOW COLUMNS FROM $table LIKE \"$field\";";
@@ -2443,30 +2397,6 @@
                return false;
        }
 
-       /**
-        * Perform a deadlock-prone transaction.
-        *
-        * This function invokes a callback function to perform a set of write
-        * queries. If a deadlock occurs during the processing, the transaction
-        * will be rolled back and the callback function will be called again.
-        *
-        * Avoid using this method outside of Job or Maintenance classes.
-        *
-        * Usage:
-        *   $dbw->deadlockLoop( callback, ... );
-        *
-        * Extra arguments are passed through to the specified callback 
function.
-        * This method requires that no transactions are already active to avoid
-        * causing premature commits or exceptions.
-        *
-        * Returns whatever the callback function returned on its successful,
-        * iteration, or false on error, for example if the retry limit was
-        * reached.
-        *
-        * @return mixed
-        * @throws DBUnexpectedError
-        * @throws Exception
-        */
        public function deadlockLoop() {
                $args = func_get_args();
                $function = array_shift( $args );
@@ -2941,18 +2871,6 @@
                $this->allViews = null;
        }
 
-       /**
-        * Lists all the VIEWs in the database
-        *
-        * For caching purposes the list of all views should be stored in
-        * $this->allViews. The process cache can be cleared with 
clearViewsCache()
-        *
-        * @param string $prefix Only show VIEWs with this prefix, eg. 
unit_test_
-        * @param string $fname Name of calling function
-        * @throws RuntimeException
-        * @return array
-        * @since 1.22
-        */
        public function listViews( $prefix = null, $fname = __METHOD__ ) {
                throw new RuntimeException( __METHOD__ . ' is not implemented 
in descendant class' );
        }
@@ -3139,22 +3057,6 @@
        public function setSessionOptions( array $options ) {
        }
 
-       /**
-        * Read and execute SQL commands from a file.
-        *
-        * Returns true on success, error string or exception on failure 
(depending
-        * on object's error ignore settings).
-        *
-        * @param string $filename File name to open
-        * @param bool|callable $lineCallback Optional function called before 
reading each line
-        * @param bool|callable $resultCallback Optional function called for 
each MySQL result
-        * @param bool|string $fname Calling function name or false if name 
should be
-        *   generated dynamically using $filename
-        * @param bool|callable $inputCallback Optional function called for each
-        *   complete line sent
-        * @return bool|string
-        * @throws Exception
-        */
        public function sourceFile(
                $filename,
                $lineCallback = false,
@@ -3191,19 +3093,6 @@
                $this->mSchemaVars = $vars;
        }
 
-       /**
-        * Read and execute commands from an open file handle.
-        *
-        * Returns true on success, error string or exception on failure 
(depending
-        * on object's error ignore settings).
-        *
-        * @param resource $fp File handle
-        * @param bool|callable $lineCallback Optional function called before 
reading each query
-        * @param bool|callable $resultCallback Optional function called for 
each MySQL result
-        * @param string $fname Calling function name
-        * @param bool|callable $inputCallback Optional function called for 
each complete query sent
-        * @return bool|string
-        */
        public function sourceStream(
                $fp,
                $lineCallback = false,
diff --git a/includes/libs/rdbms/database/IDatabase.php 
b/includes/libs/rdbms/database/IDatabase.php
index 56eb002..19f4dd8 100644
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -26,7 +26,7 @@
  */
 
 /**
- * Basic database interface for live and lazy-loaded DB handles
+ * Basic database interface for live and lazy-loaded relation database handles
  *
  * @note: IDatabase and DBConnRef should be updated to reflect any changes
  * @ingroup Database
diff --git a/includes/libs/rdbms/database/IMaintainableDatabase.php 
b/includes/libs/rdbms/database/IMaintainableDatabase.php
new file mode 100644
index 0000000..87c06d6
--- /dev/null
+++ b/includes/libs/rdbms/database/IMaintainableDatabase.php
@@ -0,0 +1,194 @@
+<?php
+
+/**
+ * @defgroup Database Database
+ *
+ * This file deals with database interface functions
+ * and query specifics/optimisations.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Database
+ */
+
+/**
+ * Advanced database interface for IDatabase handles that include maintenance 
methods
+ *
+ * This is useful for type-hints used by installer, upgrader, and background 
scripts
+ * that will make use of lower-level and longer-running queries, including 
schema changes.
+ *
+ * @ingroup Database
+ * @since 1.28
+ */
+interface IMaintainableDatabase extends IDatabase {
+       /**
+        * Format a table name ready for use in constructing an SQL query
+        *
+        * This does two important things: it quotes the table names to clean 
them up,
+        * and it adds a table prefix if only given a table name with no quotes.
+        *
+        * All functions of this object which require a table name call this 
function
+        * themselves. Pass the canonical name to such functions. This is only 
needed
+        * when calling query() directly.
+        *
+        * @note This function does not sanitize user input. It is not safe to 
use
+        *   this function to escape user input.
+        * @param string $name Database table name
+        * @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
+        * @return string Full database name
+        */
+       public function tableName( $name, $format = 'quoted' );
+
+       /**
+        * Fetch a number of table names into an array
+        * This is handy when you need to construct SQL for joins
+        *
+        * Example:
+        * extract( $dbr->tableNames( 'user', 'watchlist' ) );
+        * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
+        *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+        *
+        * @return array
+        */
+       public function tableNames();
+
+       /**
+        * Fetch a number of table names into an zero-indexed numerical array
+        * This is handy when you need to construct SQL for joins
+        *
+        * Example:
+        * list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' );
+        * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
+        *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+        *
+        * @return array
+        */
+       public function tableNamesN();
+
+       /**
+        * Returns the size of a text field, or -1 for "unlimited"
+        *
+        * @param string $table
+        * @param string $field
+        * @return int
+        */
+       public function textFieldSize( $table, $field );
+
+       /**
+        * Read and execute SQL commands from a file.
+        *
+        * Returns true on success, error string or exception on failure 
(depending
+        * on object's error ignore settings).
+        *
+        * @param string $filename File name to open
+        * @param bool|callable $lineCallback Optional function called before 
reading each line
+        * @param bool|callable $resultCallback Optional function called for 
each MySQL result
+        * @param bool|string $fname Calling function name or false if name 
should be
+        *   generated dynamically using $filename
+        * @param bool|callable $inputCallback Optional function called for each
+        *   complete line sent
+        * @return bool|string
+        * @throws Exception
+        */
+       public function sourceFile(
+               $filename,
+               $lineCallback = false,
+               $resultCallback = false,
+               $fname = false,
+               $inputCallback = false
+       );
+
+       /**
+        * Read and execute commands from an open file handle.
+        *
+        * Returns true on success, error string or exception on failure 
(depending
+        * on object's error ignore settings).
+        *
+        * @param resource $fp File handle
+        * @param bool|callable $lineCallback Optional function called before 
reading each query
+        * @param bool|callable $resultCallback Optional function called for 
each MySQL result
+        * @param string $fname Calling function name
+        * @param bool|callable $inputCallback Optional function called for 
each complete query sent
+        * @return bool|string
+        */
+       public function sourceStream(
+               $fp,
+               $lineCallback = false,
+               $resultCallback = false,
+               $fname = __METHOD__,
+               $inputCallback = false
+       );
+
+       /**
+        * Called by sourceStream() to check if we've reached a statement end
+        *
+        * @param string &$sql SQL assembled so far
+        * @param string &$newLine New line about to be added to $sql
+        * @return bool Whether $newLine contains end of the statement
+        */
+       public function streamStatementEnd( $sql, &$newLine );
+
+       /**
+        * Delete a table
+        * @param string $tableName
+        * @param string $fName
+        * @return bool|ResultWrapper
+        */
+       public function dropTable( $tableName, $fName = __METHOD__ );
+
+       /**
+        * Perform a deadlock-prone transaction.
+        *
+        * This function invokes a callback function to perform a set of write
+        * queries. If a deadlock occurs during the processing, the transaction
+        * will be rolled back and the callback function will be called again.
+        *
+        * Avoid using this method outside of Job or Maintenance classes.
+        *
+        * Usage:
+        *   $dbw->deadlockLoop( callback, ... );
+        *
+        * Extra arguments are passed through to the specified callback 
function.
+        * This method requires that no transactions are already active to avoid
+        * causing premature commits or exceptions.
+        *
+        * Returns whatever the callback function returned on its successful,
+        * iteration, or false on error, for example if the retry limit was
+        * reached.
+        *
+        * @return mixed
+        * @throws DBUnexpectedError
+        * @throws Exception
+        */
+       public function deadlockLoop();
+
+       /**
+        * Lists all the VIEWs in the database
+        *
+        * For caching purposes the list of all views should be stored in
+        * $this->allViews. The process cache can be cleared with 
clearViewsCache()
+        *
+        * @param string $prefix Only show VIEWs with this prefix, eg. 
unit_test_
+        * @param string $fname Name of calling function
+        * @throws RuntimeException
+        * @return array
+        */
+       public function listViews( $prefix = null, $fname = __METHOD__ );
+}

-- 
To view, visit https://gerrit.wikimedia.org/r/312462
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I4cbdfd7a40af17269c527df6e1c3c5644672b8a7
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Aaron Schulz <asch...@wikimedia.org>

_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits

Reply via email to