aboutsummaryrefslogtreecommitdiffstats
path: root/phpBB/phpbb/db/driver/driver_interface.php
blob: 8b487c5d42ff3a3f0031da613a3f8bf2e845857f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
<?php
/**
*
* This file is part of the phpBB Forum Software package.
*
* @copyright (c) phpBB Limited <https://www.phpbb.com>
* @license GNU General Public License, version 2 (GPL-2.0)
*
* For full copyright and license information, please see
* the docs/CREDITS.txt file.
*
*/

namespace phpbb\db\driver;

interface driver_interface
{
	/**
	* Gets the name of the sql layer.
	*
	* @return string
	*/
	public function get_sql_layer();

	/**
	* Gets the name of the database.
	*
	* @return string
	*/
	public function get_db_name();

	/**
	* Wildcards for matching any (%) character within LIKE expressions
	*
	* @return string
	*/
	public function get_any_char();

	/**
	* Wildcards for matching exactly one (_) character within LIKE expressions
	*
	* @return string
	*/
	public function get_one_char();

	/**
	* Gets the time spent into the queries
	*
	* @return int
	*/
	public function get_sql_time();

	/**
	* Gets the connect ID.
	*
	* @return mixed
	*/
	public function get_db_connect_id();

	/**
	* Indicates if an error was triggered.
	*
	* @return bool
	*/
	public function get_sql_error_triggered();

	/**
	* Gets the last faulty query
	*
	* @return string
	*/
	public function get_sql_error_sql();

	/**
	* Indicates if we are in a transaction.
	*
	* @return bool
	*/
	public function get_transaction();

	/**
	* Gets the returned error.
	*
	* @return array
	*/
	public function get_sql_error_returned();

	/**
	* Indicates if multiple insertion can be used
	*
	* @return bool
	*/
	public function get_multi_insert();

	/**
	* Set if multiple insertion can be used
	*
	* @param bool $multi_insert
	*/
	public function set_multi_insert($multi_insert);

	/**
	* Gets the exact number of rows in a specified table.
	*
	* @param string $table_name Table name
	* @return string	Exact number of rows in $table_name.
	*/
	public function get_row_count($table_name);

	/**
	* Gets the estimated number of rows in a specified table.
	*
	* @param string $table_name Table name
	* @return string	Number of rows in $table_name.
	*					Prefixed with ~ if estimated (otherwise exact).
	*/
	public function get_estimated_row_count($table_name);

	/**
	* Run LOWER() on DB column of type text (i.e. neither varchar nor char).
	*
	* @param string $column_name	The column name to use
	* @return string		A SQL statement like "LOWER($column_name)"
	*/
	public function sql_lower_text($column_name);

	/**
	* Display sql error page
	*
	* @param string		$sql	The SQL query causing the error
	* @return mixed		Returns the full error message, if $this->return_on_error
	*					is set, null otherwise
	*/
	public function sql_error($sql = '');

	/**
	* Returns whether results of a query need to be buffered to run a
	* transaction while iterating over them.
	*
	* @return bool	Whether buffering is required.
	*/
	public function sql_buffer_nested_transactions();

	/**
	* Run binary OR operator on DB column.
	*
	* @param string	$column_name	The column name to use
	* @param int	$bit			The value to use for the OR operator,
	*					will be converted to (1 << $bit). Is used by options,
	*					using the number schema... 0, 1, 2...29
	* @param string	$compare	Any custom SQL code after the check (e.g. "= 0")
	* @return string	A SQL statement like "$column | (1 << $bit) {$compare}"
	*/
	public function sql_bit_or($column_name, $bit, $compare = '');

	/**
	* Version information about used database
	*
	* @param bool $raw			Only return the fetched sql_server_version
	* @param bool $use_cache	Is it safe to retrieve the value from the cache
	* @return string sql server version
	*/
	public function sql_server_info($raw = false, $use_cache = true);

	/**
	* Return on error or display error message
	*
	* @param bool	$fail		Should we return on errors, or stop
	* @return null
	*/
	public function sql_return_on_error($fail = false);

	/**
	* Build sql statement from an array
	*
	* @param	string	$query		Should be on of the following strings:
	*						INSERT, INSERT_SELECT, UPDATE, SELECT, DELETE
	* @param	array	$assoc_ary	Array with "column => value" pairs
	* @return	string		A SQL statement like "c1 = 'a' AND c2 = 'b'"
	*/
	public function sql_build_array($query, $assoc_ary = array());

	/**
	* Fetch all rows
	*
	* @param	mixed	$query_id	Already executed query to get the rows from,
	*								if false, the last query will be used.
	* @return	mixed		Nested array if the query had rows, false otherwise
	*/
	public function sql_fetchrowset($query_id = false);

	/**
	* SQL Transaction
	*
	* @param	string	$status		Should be one of the following strings:
	*								begin, commit, rollback
	* @return	mixed	Buffered, seekable result handle, false on error
	*/
	public function sql_transaction($status = 'begin');

	/**
	* Build a concatenated expression
	*
	* @param	string	$expr1		Base SQL expression where we append the second one
	* @param	string	$expr2		SQL expression that is appended to the first expression
	* @return	string		Concatenated string
	*/
	public function sql_concatenate($expr1, $expr2);

	/**
	* Build a case expression
	*
	* Note: The two statements action_true and action_false must have the same
	* data type (int, vchar, ...) in the database!
	*
	* @param	string	$condition		The condition which must be true,
	*							to use action_true rather then action_else
	* @param	string	$action_true	SQL expression that is used, if the condition is true
	* @param	mixed	$action_false	SQL expression that is used, if the condition is false
	* @return	string		CASE expression including the condition and statements
	*/
	public function sql_case($condition, $action_true, $action_false = false);

	/**
	* Build sql statement from array for select and select distinct statements
	*
	* Possible query values: SELECT, SELECT_DISTINCT
	*
	* @param	string	$query	Should be one of: SELECT, SELECT_DISTINCT
	* @param	array	$array	Array with the query data:
	*					SELECT		A comma imploded list of columns to select
	*					FROM		Array with "table => alias" pairs,
	*								(alias can also be an array)
	*		Optional:	LEFT_JOIN	Array of join entries:
	*						FROM		Table that should be joined
	*						ON			Condition for the join
	*		Optional:	WHERE		Where SQL statement
	*		Optional:	GROUP_BY	Group by SQL statement
	*		Optional:	ORDER_BY	Order by SQL statement
	* @return	string		A SQL statement ready for execution
	*/
	public function sql_build_query($query, $array);

	/**
	* Fetch field
	* if rownum is false, the current row is used, else it is pointing to the row (zero-based)
	*
	* @param	string	$field		Name of the column
	* @param	mixed	$rownum		Row number, if false the current row will be used
	*								and the row curser will point to the next row
	*								Note: $rownum is 0 based
	* @param	mixed	$query_id	Already executed query to get the rows from,
	*								if false, the last query will be used.
	* @return	mixed		String value of the field in the selected row,
	*						false, if the row does not exist
	*/
	public function sql_fetchfield($field, $rownum = false, $query_id = false);

	/**
	* Fetch current row
	*
	* @param	mixed	$query_id	Already executed query to get the rows from,
	*								if false, the last query will be used.
	* @return	mixed		Array with the current row,
	*						false, if the row does not exist
	*/
	public function sql_fetchrow($query_id = false);

	/**
	* Returns SQL string to cast a string expression to an int.
	*
	* @param  string $expression An expression evaluating to string
	* @return string             Expression returning an int
	*/
	public function cast_expr_to_bigint($expression);

	/**
	* Get last inserted id after insert statement
	*
	* @return	string		Autoincrement value of the last inserted row
	*/
	public function sql_nextid();

	/**
	* Add to query count
	*
	* @param bool $cached	Is this query cached?
	* @return null
	*/
	public function sql_add_num_queries($cached = false);

	/**
	* Build LIMIT query
	*
	* @param	string	$query		The SQL query to execute
	* @param	int		$total		The number of rows to select
	* @param	int		$offset
	* @param	int		$cache_ttl	Either 0 to avoid caching or
	*				the time in seconds which the result shall be kept in cache
	* @return	mixed	Buffered, seekable result handle, false on error
	*/
	public function sql_query_limit($query, $total, $offset = 0, $cache_ttl = 0);

	/**
	* Base query method
	*
	* @param	string	$query		The SQL query to execute
	* @param	int		$cache_ttl	Either 0 to avoid caching or
	*				the time in seconds which the result shall be kept in cache
	* @return	mixed	Buffered, seekable result handle, false on error
	*/
	public function sql_query($query = '', $cache_ttl = 0);

	/**
	* Returns SQL string to cast an integer expression to a string.
	*
	* @param	string	$expression		An expression evaluating to int
	* @return string		Expression returning a string
	*/
	public function cast_expr_to_string($expression);

	/**
	 * Connect to server
	 *
	 * @param	string	$sqlserver		Address of the database server
	 * @param	string	$sqluser		User name of the SQL user
	 * @param	string	$sqlpassword	Password of the SQL user
	 * @param	string	$database		Name of the database
	 * @param	mixed	$port			Port of the database server
	 * @param	bool	$persistency
	 * @param	bool	$new_link		Should a new connection be established
	 * @return	mixed	Connection ID on success, string error message otherwise
	 */
	public function sql_connect($sqlserver, $sqluser, $sqlpassword, $database, $port = false, $persistency = false, $new_link = false);

	/**
	* Run binary AND operator on DB column.
	* Results in sql statement: "{$column_name} & (1 << {$bit}) {$compare}"
	*
	* @param string	$column_name	The column name to use
	* @param int	$bit			The value to use for the AND operator,
	*								will be converted to (1 << $bit). Is used by
	*								options, using the number schema: 0, 1, 2...29
	* @param string	$compare		Any custom SQL code after the check (for example "= 0")
	* @return string	A SQL statement like: "{$column} & (1 << {$bit}) {$compare}"
	*/
	public function sql_bit_and($column_name, $bit, $compare = '');

	/**
	* Free sql result
	*
	* @param	mixed	$query_id	Already executed query result,
	*								if false, the last query will be used.
	* @return	null
	*/
	public function sql_freeresult($query_id = false);

	/**
	* Return number of sql queries and cached sql queries used
	*
	* @param	bool	$cached		Should we return the number of cached or normal queries?
	* @return	int		Number of queries that have been executed
	*/
	public function sql_num_queries($cached = false);

	/**
	* Run more than one insert statement.
	*
	* @param string	$table		Table name to run the statements on
	* @param array	$sql_ary	Multi-dimensional array holding the statement data
	* @return bool		false if no statements were executed.
	*/
	public function sql_multi_insert($table, $sql_ary);

	/**
	* Return number of affected rows
	*
	* @return	mixed		Number of the affected rows by the last query
	*						false if no query has been run before
	*/
	public function sql_affectedrows();

	/**
	* DBAL garbage collection, close SQL connection
	*
	* @return	mixed		False if no connection was opened before,
	*						Server response otherwise
	*/
	public function sql_close();

	/**
	* Seek to given row number
	*
	* @param	mixed	$rownum		Row number the curser should point to
	*								Note: $rownum is 0 based
	* @param	mixed	$query_id	ID of the query to set the row cursor on
	*								if false, the last query will be used.
	*								$query_id will then be set correctly
	* @return	bool		False if something went wrong
	*/
	public function sql_rowseek($rownum, &$query_id);

	/**
	* Escape string used in sql query
	*
	* @param	string	$msg	String to be escaped
	* @return	string		Escaped version of $msg
	*/
	public function sql_escape($msg);

	/**
	* Correctly adjust LIKE expression for special characters
	* Some DBMS are handling them in a different way
	*
	* @param	string	$expression	The expression to use. Every wildcard is
	*						escaped, except $this->any_char and $this->one_char
	* @return string	A SQL statement like: "LIKE 'bertie_%'"
	*/
	public function sql_like_expression($expression);

	/**
	* Correctly adjust NOT LIKE expression for special characters
	* Some DBMS are handling them in a different way
	*
	* @param	string	$expression	The expression to use. Every wildcard is
	*						escaped, except $this->any_char and $this->one_char
	* @return string	A SQL statement like: "NOT LIKE 'bertie_%'"
	*/
	public function sql_not_like_expression($expression);

	/**
	* Explain queries
	*
	* @param	string	$mode		Available modes: display, start, stop,
	 *								add_select_row, fromcache, record_fromcache
	* @param	string	$query		The Query that should be explained
	* @return	mixed		Either a full HTML page, boolean or null
	*/
	public function sql_report($mode, $query = '');

	/**
	* Build IN or NOT IN sql comparison string, uses <> or = on single element
	* arrays to improve comparison speed
	*
	* @param	string	$field			Name of the sql column that shall be compared
	* @param	array	$array			Array of values that are (not) allowed
	* @param	bool	$negate			true for NOT IN (), false for IN ()
	* @param	bool	$allow_empty_set	If true, allow $array to be empty,
	*								this function will return 1=1 or 1=0 then.
	* @return string	A SQL statement like: "IN (1, 2, 3, 4)" or "= 1"
	*/
	public function sql_in_set($field, $array, $negate = false, $allow_empty_set = false);
}