includes/libs/rdbms/database/IMaintainableDatabase.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20 namespace Wikimedia\Rdbms;
  21
  22 use Exception;
  23 use RuntimeException;
  24
  25 /**
  26  * Advanced database interface for IDatabase handles that include maintenance methods
  27  *
  28  * This is useful for type-hints used by installer, upgrader, and background scripts
  29  * that will make use of lower-level and longer-running queries, including schema changes.
  30  *
  31  * @ingroup Database
  32  * @since 1.28
  33  */
  34 interface IMaintainableDatabase extends IDatabase {
  35         /**
  36          * Read and execute SQL commands from a file.
  37          *
  38          * Returns true on success, error string or exception on failure (depending
  39          * on object's error ignore settings).
  40          *
  41          * @param string $filename File name to open
  42          * @param callable|null $lineCallback Optional function called before reading each line
  43          * @param callable|null $resultCallback Optional function called for each MySQL result
  44          * @param string|false $fname Calling function name or false if name should be
  45          *   generated dynamically using $filename
  46          * @param callable|null $inputCallback Optional function called for each
  47          *   complete line sent
  48          * @return bool|string
  49          * @throws Exception
  50          */
  51         public function sourceFile(
  52                 $filename,
  53                 ?callable $lineCallback = null,
  54                 ?callable $resultCallback = null,
  55                 $fname = false,
  56                 ?callable $inputCallback = null
  57         );
  58
  59         /**
  60          * Read and execute commands from an open file handle.
  61          *
  62          * Returns true on success, error string or exception on failure (depending
  63          * on object's error ignore settings).
  64          *
  65          * @param resource $fp File handle
  66          * @param callable|null $lineCallback Optional function called before reading each query
  67          * @param callable|null $resultCallback Optional function called for each MySQL result
  68          * @param string $fname Calling function name @phan-mandatory-param
  69          * @param callable|null $inputCallback Optional function called for each complete query sent
  70          * @return bool|string
  71          */
  72         public function sourceStream(
  73                 $fp,
  74                 ?callable $lineCallback = null,
  75                 ?callable $resultCallback = null,
  76                 $fname = __METHOD__,
  77                 ?callable $inputCallback = null
  78         );
  79
  80         /**
  81          * Called by sourceStream() to check if we've reached a statement end
  82          *
  83          * @param string &$sql SQL assembled so far
  84          * @param string &$newLine New line about to be added to $sql
  85          * @return bool Whether $newLine contains end of the statement
  86          */
  87         public function streamStatementEnd( &$sql, &$newLine );
  88
  89         /**
  90          * Delete a table
  91          *
  92          * @param string $table The unqualified name of a table
  93          * @param string $fname @phan-mandatory-param
  94          * @return bool Whether the table already existed
  95          * @throws DBError If an error occurs
  96          */
  97         public function dropTable( $table, $fname = __METHOD__ );
  98
  99         /**
 100          * Delete all data in a table and reset any sequences owned by that table
 101          *
 102          * @param string $table The unqualified name of a table
 103          * @param string $fname @phan-mandatory-param
 104          * @throws DBError If an error occurs
 105          * @since 1.42
 106          */
 107         public function truncateTable( $table, $fname = __METHOD__ );
 108
 109         /**
 110          * Creates a new table with structure copied from existing table
 111          *
 112          * Note that unlike most database abstraction functions, this function does not
 113          * automatically append database prefix, because it works at a lower abstraction level.
 114          * The table names passed to this function shall not be quoted (this function calls
 115          * addIdentifierQuotes() when needed).
 116          *
 117          * @param string $oldName Name of table whose structure should be copied
 118          * @param string $newName Name of table to be created
 119          * @param bool $temporary Whether the new table should be temporary
 120          * @param string $fname Calling function name @phan-mandatory-param
 121          * @return bool True if operation was successful
 122          * @throws RuntimeException
 123          */
 124         public function duplicateTableStructure(
 125                 $oldName, $newName, $temporary = false, $fname = __METHOD__
 126         );
 127
 128         /**
 129          * List all tables on the database.
 130          *
 131          * Since MW 1.42, this will no longer include MySQL views.
 132          *
 133          * @param string|null $prefix Only show tables with this prefix, e.g. mw_
 134          * @param string $fname Calling function name @phan-mandatory-param
 135          * @throws DBError
 136          * @return array
 137          */
 138         public function listTables( $prefix = null, $fname = __METHOD__ );
 139
 140         /**
 141          * Get information about a field
 142          * Returns false if the field doesn't exist
 143          *
 144          * @param string $table The unqualified name of a table
 145          * @param string $field Field name
 146          *
 147          * @return false|Field
 148          */
 149         public function fieldInfo( $table, $field );
 150
 151         /**
 152          * Determines whether a field exists in a table
 153          *
 154          * @param string $table The unqualified name of a table
 155          * @param string $field Field to check on that table
 156          * @param string $fname Calling function name @phan-mandatory-param
 157          * @return bool Whether $table has field $field
 158          * @throws DBError If an error occurs, {@see query}
 159          */
 160         public function fieldExists( $table, $field, $fname = __METHOD__ );
 161
 162         /**
 163          * Determines whether an index exists
 164          *
 165          * @param string $table The unqualified name of a table
 166          * @param string $index
 167          * @param string $fname @phan-mandatory-param
 168          * @return bool
 169          * @throws DBError If an error occurs, {@see query}
 170          */
 171         public function indexExists( $table, $index, $fname = __METHOD__ );
 172
 173         /**
 174          * Determines if a given index is unique
 175          *
 176          * @param string $table The unqualified name of a table
 177          * @param string $index
 178          * @param string $fname Calling function name @phan-mandatory-param
 179          * @return bool|null Returns null if the index does not exist
 180          * @throws DBError If an error occurs, {@see query}
 181          */
 182         public function indexUnique( $table, $index, $fname = __METHOD__ );
 183
 184         /**
 185          * Query whether a given table exists
 186          *
 187          * @param string $table The unqualified name of a table
 188          * @param string $fname @phan-mandatory-param
 189          * @return bool
 190          * @throws DBError If an error occurs, {@see query}
 191          */
 192         public function tableExists( $table, $fname = __METHOD__ );
 193 }