4 * This file deals with database interface functions
5 * and query specifics/optimisations.
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License along
18 * with this program; if not, write to the Free Software Foundation, Inc.,
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 * http://www.gnu.org/copyleft/gpl.html
27 * Advanced database interface for IDatabase handles that include maintenance methods
29 * This is useful for type-hints used by installer, upgrader, and background scripts
30 * that will make use of lower-level and longer-running queries, including schema changes.
35 interface IMaintainableDatabase
extends IDatabase
{
37 * Format a table name ready for use in constructing an SQL query
39 * This does two important things: it quotes the table names to clean them up,
40 * and it adds a table prefix if only given a table name with no quotes.
42 * All functions of this object which require a table name call this function
43 * themselves. Pass the canonical name to such functions. This is only needed
44 * when calling query() directly.
46 * @note This function does not sanitize user input. It is not safe to use
47 * this function to escape user input.
48 * @param string $name Database table name
49 * @param string $format One of:
50 * quoted - Automatically pass the table name through addIdentifierQuotes()
51 * so that it can be used in a query.
52 * raw - Do not add identifier quotes to the table name
53 * @return string Full database name
55 public function tableName( $name, $format = 'quoted' );
58 * Fetch a number of table names into an array
59 * This is handy when you need to construct SQL for joins
62 * extract( $dbr->tableNames( 'user', 'watchlist' ) );
63 * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
64 * WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
68 public function tableNames();
71 * Fetch a number of table names into an zero-indexed numerical array
72 * This is handy when you need to construct SQL for joins
75 * list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' );
76 * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
77 * WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
81 public function tableNamesN();
84 * Returns the size of a text field, or -1 for "unlimited"
86 * @param string $table
87 * @param string $field
90 public function textFieldSize( $table, $field );
93 * Read and execute SQL commands from a file.
95 * Returns true on success, error string or exception on failure (depending
96 * on object's error ignore settings).
98 * @param string $filename File name to open
99 * @param callable|null $lineCallback Optional function called before reading each line
100 * @param callable|null $resultCallback Optional function called for each MySQL result
101 * @param bool|string $fname Calling function name or false if name should be
102 * generated dynamically using $filename
103 * @param callable|null $inputCallback Optional function called for each
105 * @return bool|string
108 public function sourceFile(
110 callable
$lineCallback = null,
111 callable
$resultCallback = null,
113 callable
$inputCallback = null
117 * Read and execute commands from an open file handle.
119 * Returns true on success, error string or exception on failure (depending
120 * on object's error ignore settings).
122 * @param resource $fp File handle
123 * @param callable|null $lineCallback Optional function called before reading each query
124 * @param callable|null $resultCallback Optional function called for each MySQL result
125 * @param string $fname Calling function name
126 * @param callable|null $inputCallback Optional function called for each complete query sent
127 * @return bool|string
129 public function sourceStream(
131 callable
$lineCallback = null,
132 callable
$resultCallback = null,
134 callable
$inputCallback = null
138 * Called by sourceStream() to check if we've reached a statement end
140 * @param string &$sql SQL assembled so far
141 * @param string &$newLine New line about to be added to $sql
142 * @return bool Whether $newLine contains end of the statement
144 public function streamStatementEnd( &$sql, &$newLine );
148 * @param string $tableName
149 * @param string $fName
150 * @return bool|ResultWrapper
152 public function dropTable( $tableName, $fName = __METHOD__
);
155 * Perform a deadlock-prone transaction.
157 * This function invokes a callback function to perform a set of write
158 * queries. If a deadlock occurs during the processing, the transaction
159 * will be rolled back and the callback function will be called again.
161 * Avoid using this method outside of Job or Maintenance classes.
164 * $dbw->deadlockLoop( callback, ... );
166 * Extra arguments are passed through to the specified callback function.
167 * This method requires that no transactions are already active to avoid
168 * causing premature commits or exceptions.
170 * Returns whatever the callback function returned on its successful,
171 * iteration, or false on error, for example if the retry limit was
175 * @throws DBUnexpectedError
178 public function deadlockLoop();
181 * Lists all the VIEWs in the database
183 * @param string $prefix Only show VIEWs with this prefix, eg. unit_test_
184 * @param string $fname Name of calling function
185 * @throws RuntimeException
188 public function listViews( $prefix = null, $fname = __METHOD__
);