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	}