MDL-25276 dml - fix/implement sql_cast2int/real() across the 5 drivers. Tests passing.
[moodle.git] / lib / dml / mysqli_native_moodle_database.php
CommitLineData
49926145 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18
19/**
20 * Native mysqli class representing moodle database interface.
21 *
66c0ee78 22 * @package core
f2ed3f05 23 * @subpackage dml
49926145 24 * @copyright 2008 Petr Skoda (http://skodak.org)
25 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 */
7466a42f 27
f2ed3f05
PS
28defined('MOODLE_INTERNAL') || die();
29
7466a42f 30require_once($CFG->libdir.'/dml/moodle_database.php');
31require_once($CFG->libdir.'/dml/mysqli_native_moodle_recordset.php');
3f33c9e2 32require_once($CFG->libdir.'/dml/mysqli_native_moodle_temptables.php');
7466a42f 33
34/**
35 * Native mysqli class representing moodle database interface.
7466a42f 36 */
37class mysqli_native_moodle_database extends moodle_database {
38
0487f9e2 39 protected $mysqli = null;
7466a42f 40
d5a8d9aa
PS
41 private $transactions_supported = null;
42
30d2832d 43 /**
44 * Attempt to create the database
45 * @param string $dbhost
46 * @param string $dbuser
47 * @param string $dbpass
48 * @param string $dbname
49 * @return bool success
50 * @throws dml_exception if error
51 */
3b093310 52 public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
797ffad0 53 $driverstatus = $this->driver_installed();
54
55 if ($driverstatus !== true) {
56 throw new dml_exception('dbdriverproblem', $driverstatus);
57 }
58
30d2832d 59 ob_start();
7f79aaea 60 $conn = new mysqli($dbhost, $dbuser, $dbpass); /// Connect without db
30d2832d 61 $dberr = ob_get_contents();
62 ob_end_clean();
63 $errorno = @$conn->connect_errno;
64
65 if ($errorno !== 0) {
66 throw new dml_connection_exception($dberr);
67 }
68
69 $result = $conn->query("CREATE DATABASE $dbname DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci");
70
71 $conn->close();
72
73 if (!$result) {
74 throw new dml_exception('cannotcreatedb');
75 }
76
77 return true;
78 }
79
7466a42f 80 /**
81 * Detects if all needed PHP stuff installed.
82 * Note: can be used before connect()
83 * @return mixed true if ok, string if something
84 */
85 public function driver_installed() {
86 if (!extension_loaded('mysqli')) {
87 return get_string('mysqliextensionisnotpresentinphp', 'install');
88 }
89 return true;
90 }
91
92 /**
93 * Returns database family type - describes SQL dialect
94 * Note: can be used before connect()
95 * @return string db family name (mysql, postgres, mssql, oracle, etc.)
96 */
97 public function get_dbfamily() {
98 return 'mysql';
99 }
100
101 /**
102 * Returns more specific database driver type
103 * Note: can be used before connect()
4a6c2ab8 104 * @return string db type mysqli, pgsql, oci, mssql, sqlsrv
7466a42f 105 */
106 protected function get_dbtype() {
107 return 'mysqli';
108 }
109
110 /**
111 * Returns general database library name
112 * Note: can be used before connect()
eb123deb 113 * @return string db type pdo, native
7466a42f 114 */
115 protected function get_dblibrary() {
116 return 'native';
117 }
118
d35ece6c
PS
119 /**
120 * Returns the current MySQL db engine.
121 *
122 * This is an ugly workaround for MySQL default engine problems,
123 * Moodle is designed to work best on ACID compliant databases
124 * with full transaction support. Do not use MyISAM.
125 *
126 * @return string or null MySQL engine name
127 */
128 public function get_dbengine() {
129 if (isset($this->dboptions['dbengine'])) {
130 return $this->dboptions['dbengine'];
131 }
132
133 $engine = null;
134
135 if (!$this->external) {
136 // look for current engine of our config table (the first table that gets created),
137 // so that we create all tables with the same engine
138 $sql = "SELECT engine FROM INFORMATION_SCHEMA.TABLES WHERE table_schema = DATABASE() AND table_name = '{$this->prefix}config'";
139 $this->query_start($sql, NULL, SQL_QUERY_AUX);
140 $result = $this->mysqli->query($sql);
141 $this->query_end($result);
142 if ($rec = $result->fetch_assoc()) {
143 $engine = $rec['engine'];
144 }
145 $result->close();
146 }
147
148 if ($engine) {
149 return $engine;
150 }
151
152 // get the default database engine
153 $sql = "SELECT @@storage_engine";
154 $this->query_start($sql, NULL, SQL_QUERY_AUX);
155 $result = $this->mysqli->query($sql);
156 $this->query_end($result);
157 if ($rec = $result->fetch_assoc()) {
158 $engine = $rec['@@storage_engine'];
159 }
160 $result->close();
161
162 if (!$this->external and $engine === 'MyISAM') {
163 // we really do not want MyISAM for Moodle, InnoDB or XtraDB is a reasonable defaults if supported
164 $sql = "SHOW STORAGE ENGINES";
165 $this->query_start($sql, NULL, SQL_QUERY_AUX);
166 $result = $this->mysqli->query($sql);
167 $this->query_end($result);
ed22700d 168 $engines = array();
d35ece6c 169 while ($res = $result->fetch_assoc()) {
ed22700d
PS
170 if ($res['Support'] === 'YES' or $res['Support'] === 'DEFAULT') {
171 $engines[$res['Engine']] = true;
d35ece6c
PS
172 }
173 }
174 $result->close();
ed22700d
PS
175 if (isset($engines['InnoDB'])) {
176 $engine = 'InnoDB';
177 }
178 if (isset($engines['XtraDB'])) {
179 $engine = 'XtraDB';
180 }
d35ece6c
PS
181 }
182
183 return $engine;
184 }
185
7466a42f 186 /**
187 * Returns localised database type name
188 * Note: can be used before connect()
189 * @return string
190 */
191 public function get_name() {
2aeb3bcb 192 return get_string('nativemysqli', 'install');
7466a42f 193 }
194
3b093310 195 /**
196 * Returns localised database configuration help.
197 * Note: can be used before connect()
198 * @return string
199 */
200 public function get_configuration_help() {
201 return get_string('nativemysqlihelp', 'install');
202 }
203
7466a42f 204 /**
205 * Returns localised database description
206 * Note: can be used before connect()
207 * @return string
208 */
209 public function get_configuration_hints() {
2aeb3bcb 210 return get_string('databasesettingssub_mysqli', 'install');
7466a42f 211 }
212
d35ece6c
PS
213 /**
214 * Diagnose database and tables, this function is used
215 * to verify database and driver settings, db engine types, etc.
216 *
217 * @return string null means everything ok, string means problem found.
218 */
219 public function diagnose() {
220 $sloppymyisamfound = false;
221 $prefix = str_replace('_', '\\_', $this->prefix);
222 $sql = "SHOW TABLE STATUS WHERE Name LIKE BINARY '$prefix%'";
223 $this->query_start($sql, null, SQL_QUERY_AUX);
224 $result = $this->mysqli->query($sql);
225 $this->query_end($result);
226 if ($result) {
227 while ($arr = $result->fetch_assoc()) {
228 if ($arr['Engine'] === 'MyISAM') {
229 $sloppymyisamfound = true;
230 break;
231 }
232 }
233 $result->close();
234 }
235
236 if ($sloppymyisamfound) {
237 return get_string('myisamproblem', 'error');
238 } else {
239 return null;
240 }
241 }
242
7466a42f 243 /**
244 * Connect to db
245 * Must be called before other methods.
246 * @param string $dbhost
247 * @param string $dbuser
248 * @param string $dbpass
249 * @param string $dbname
7466a42f 250 * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
251 * @param array $dboptions driver specific options
252 * @return bool success
253 */
beaa43db 254 public function connect($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions=null) {
ce152606 255 $driverstatus = $this->driver_installed();
256
257 if ($driverstatus !== true) {
258 throw new dml_exception('dbdriverproblem', $driverstatus);
259 }
260
beaa43db 261 $this->store_settings($dbhost, $dbuser, $dbpass, $dbname, $prefix, $dboptions);
3b093310 262 unset($this->dboptions['dbsocket']);
7466a42f 263
ce152606 264 ob_start();
7466a42f 265 $this->mysqli = new mysqli($dbhost, $dbuser, $dbpass, $dbname);
ce152606 266 $dberr = ob_get_contents();
267 ob_end_clean();
268 $errorno = @$this->mysqli->connect_errno;
269
270 if ($errorno !== 0) {
271 throw new dml_connection_exception($dberr);
7466a42f 272 }
ce152606 273
a6283e91 274 $this->query_start("--set_charset()", null, SQL_QUERY_AUX);
7466a42f 275 $this->mysqli->set_charset('utf8');
a6283e91 276 $this->query_end(true);
277
77abbc47 278 // If available, enforce strict mode for the session. That guaranties
279 // standard behaviour under some situations, avoiding some MySQL nasty
280 // habits like truncating data or performing some transparent cast losses.
02df9cfd 281 // With strict mode enforced, Moodle DB layer will be consistently throwing
77abbc47 282 // the corresponding exceptions as expected.
283 $si = $this->get_server_info();
284 if (version_compare($si['version'], '5.0.2', '>=')) {
285 $sql = "SET SESSION sql_mode = 'STRICT_ALL_TABLES'";
286 $this->query_start($sql, null, SQL_QUERY_AUX);
287 $result = $this->mysqli->query($sql);
288 $this->query_end($result);
289 }
290
3f33c9e2 291 // Connection stabilished and configured, going to instantiate the temptables controller
292 $this->temptables = new mysqli_native_moodle_temptables($this);
293
7466a42f 294 return true;
295 }
296
297 /**
298 * Close database connection and release all resources
299 * and memory (especially circular memory references).
300 * Do NOT use connect() again, create a new instance if needed.
301 */
302 public function dispose() {
02df9cfd 303 parent::dispose(); // Call parent dispose to write/close session and other common stuff before closing connection
7466a42f 304 if ($this->mysqli) {
305 $this->mysqli->close();
306 $this->mysqli = null;
307 }
7466a42f 308 }
309
310 /**
311 * Returns database server info array
312 * @return array
313 */
314 public function get_server_info() {
315 return array('description'=>$this->mysqli->server_info, 'version'=>$this->mysqli->server_info);
316 }
317
318 /**
319 * Returns supported query parameter types
9331d879 320 * @return int bitmask
7466a42f 321 */
322 protected function allowed_param_types() {
323 return SQL_PARAMS_QM;
324 }
325
326 /**
327 * Returns last error reported by database engine.
9331d879 328 * @return string error message
7466a42f 329 */
330 public function get_last_error() {
331 return $this->mysqli->error;
332 }
333
334 /**
335 * Return tables in database WITHOUT current prefix
336 * @return array of table names in lowercase and without prefix
337 */
117679db 338 public function get_tables($usecache=true) {
339 if ($usecache and $this->tables !== null) {
340 return $this->tables;
341 }
342 $this->tables = array();
a6283e91 343 $sql = "SHOW TABLES";
344 $this->query_start($sql, null, SQL_QUERY_AUX);
345 $result = $this->mysqli->query($sql);
346 $this->query_end($result);
347 if ($result) {
7466a42f 348 while ($arr = $result->fetch_assoc()) {
349 $tablename = reset($arr);
7fdcb779 350 if ($this->prefix !== '') {
351 if (strpos($tablename, $this->prefix) !== 0) {
352 continue;
353 }
354 $tablename = substr($tablename, strlen($this->prefix));
7466a42f 355 }
117679db 356 $this->tables[$tablename] = $tablename;
7466a42f 357 }
358 $result->close();
359 }
3f33c9e2 360
361 // Add the currently available temptables
362 $this->tables = array_merge($this->tables, $this->temptables->get_temptables());
117679db 363 return $this->tables;
7466a42f 364 }
365
366 /**
367 * Return table indexes - everything lowercased
368 * @return array of arrays
369 */
370 public function get_indexes($table) {
7466a42f 371 $indexes = array();
a6283e91 372 $sql = "SHOW INDEXES FROM {$this->prefix}$table";
373 $this->query_start($sql, null, SQL_QUERY_AUX);
374 $result = $this->mysqli->query($sql);
375 $this->query_end($result);
376 if ($result) {
7466a42f 377 while ($res = $result->fetch_object()) {
378 if ($res->Key_name === 'PRIMARY') {
379 continue;
380 }
381 if (!isset($indexes[$res->Key_name])) {
382 $indexes[$res->Key_name] = array('unique'=>empty($res->Non_unique), 'columns'=>array());
383 }
384 $indexes[$res->Key_name]['columns'][$res->Seq_in_index-1] = $res->Column_name;
385 }
386 $result->close();
387 }
388 return $indexes;
389 }
390
391 /**
02df9cfd 392 * Returns detailed information about columns in table. This information is cached internally.
7466a42f 393 * @param string $table name
394 * @param bool $usecache
395 * @return array array of database_column_info objects indexed with column names
396 */
397 public function get_columns($table, $usecache=true) {
398 if ($usecache and isset($this->columns[$table])) {
399 return $this->columns[$table];
400 }
401
402 $this->columns[$table] = array();
403
a6283e91 404 $sql = "SHOW COLUMNS FROM {$this->prefix}$table";
405 $this->query_start($sql, null, SQL_QUERY_AUX);
406 $result = $this->mysqli->query($sql);
407 $this->query_end($result);
408
409 if ($result === false) {
7466a42f 410 return array();
411 }
412
a6283e91 413 while ($rawcolumn = $result->fetch_assoc()) {
414 $rawcolumn = (object)array_change_key_case($rawcolumn, CASE_LOWER);
415
ac6f1a82 416 $info = new stdClass();
7466a42f 417 $info->name = $rawcolumn->field;
418 $matches = null;
419
420 if (preg_match('/varchar\((\d+)\)/i', $rawcolumn->type, $matches)) {
421 $info->type = 'varchar';
422 $info->meta_type = 'C';
423 $info->max_length = $matches[1];
424 $info->scale = null;
425 $info->not_null = ($rawcolumn->null === 'NO');
426 $info->default_value = $rawcolumn->default;
427 $info->has_default = is_null($info->default_value) ? false : true;
428 $info->primary_key = ($rawcolumn->key === 'PRI');
429 $info->binary = false;
430 $info->unsigned = null;
431 $info->auto_increment= false;
432 $info->unique = null;
433
434 } else if (preg_match('/([a-z]*int[a-z]*)\((\d+)\)/i', $rawcolumn->type, $matches)) {
435 $info->type = $matches[1];
436 $info->primary_key = ($rawcolumn->key === 'PRI');
437 if ($info->primary_key) {
438 $info->meta_type = 'R';
439 $info->max_length = $matches[2];
440 $info->scale = null;
441 $info->not_null = ($rawcolumn->null === 'NO');
442 $info->default_value = $rawcolumn->default;
443 $info->has_default = is_null($info->default_value) ? false : true;
444 $info->binary = false;
445 $info->unsigned = (stripos($rawcolumn->type, 'unsigned') !== false);
446 $info->auto_increment= true;
447 $info->unique = true;
448 } else {
449 $info->meta_type = 'I';
450 $info->max_length = $matches[2];
451 $info->scale = null;
452 $info->not_null = ($rawcolumn->null === 'NO');
453 $info->default_value = $rawcolumn->default;
454 $info->has_default = is_null($info->default_value) ? false : true;
455 $info->binary = false;
456 $info->unsigned = (stripos($rawcolumn->type, 'unsigned') !== false);
457 $info->auto_increment= false;
458 $info->unique = null;
459 }
460
c65845cc 461 } else if (preg_match('/(decimal|double|float)\((\d+),(\d+)\)/i', $rawcolumn->type, $matches)) {
462 $info->type = $matches[1];
7466a42f 463 $info->meta_type = 'N';
c65845cc 464 $info->max_length = $matches[2];
465 $info->scale = $matches[3];
7466a42f 466 $info->not_null = ($rawcolumn->null === 'NO');
467 $info->default_value = $rawcolumn->default;
468 $info->has_default = is_null($info->default_value) ? false : true;
469 $info->primary_key = ($rawcolumn->key === 'PRI');
470 $info->binary = false;
471 $info->unsigned = null;
472 $info->auto_increment= false;
473 $info->unique = null;
474
475 } else if (preg_match('/([a-z]*text)/i', $rawcolumn->type, $matches)) {
476 $info->type = $matches[1];
477 $info->meta_type = 'X';
478 $info->max_length = -1;
479 $info->scale = null;
480 $info->not_null = ($rawcolumn->null === 'NO');
481 $info->default_value = $rawcolumn->default;
482 $info->has_default = is_null($info->default_value) ? false : true;
483 $info->primary_key = ($rawcolumn->key === 'PRI');
484 $info->binary = false;
485 $info->unsigned = null;
486 $info->auto_increment= false;
487 $info->unique = null;
488
75dfa4a3 489 } else if (preg_match('/([a-z]*blob)/i', $rawcolumn->type, $matches)) {
490 $info->type = $matches[1];
491 $info->meta_type = 'B';
492 $info->max_length = -1;
493 $info->scale = null;
494 $info->not_null = ($rawcolumn->null === 'NO');
495 $info->default_value = $rawcolumn->default;
496 $info->has_default = is_null($info->default_value) ? false : true;
497 $info->primary_key = false;
498 $info->binary = true;
499 $info->unsigned = null;
500 $info->auto_increment= false;
501 $info->unique = null;
502
7466a42f 503 } else if (preg_match('/enum\((.*)\)/i', $rawcolumn->type, $matches)) {
504 $info->type = 'enum';
505 $info->meta_type = 'C';
506 $info->enums = array();
507 $info->max_length = 0;
508 $values = $matches[1];
509 $values = explode(',', $values);
510 $textlib = textlib_get_instance();
511 foreach ($values as $val) {
512 $val = trim($val, "'");
513 $length = $textlib->strlen($val);
514 $info->enums[] = $val;
515 $info->max_length = ($info->max_length < $length) ? $length : $info->max_length;
516 }
517 $info->scale = null;
518 $info->not_null = ($rawcolumn->null === 'NO');
519 $info->default_value = $rawcolumn->default;
520 $info->has_default = is_null($info->default_value) ? false : true;
521 $info->primary_key = ($rawcolumn->key === 'PRI');
522 $info->binary = false;
523 $info->unsigned = null;
524 $info->auto_increment= false;
525 $info->unique = null;
526 }
527
528 $this->columns[$table][$info->name] = new database_column_info($info);
529 }
530
a6283e91 531 $result->close();
532
7466a42f 533 return $this->columns[$table];
534 }
535
8fb501e9
EL
536 /**
537 * Normalise values based in RDBMS dependencies (booleans, LOBs...)
538 *
539 * @param database_column_info $column column metadata corresponding with the value we are going to normalise
540 * @param mixed $value value we are going to normalise
541 * @return mixed the normalised value
542 */
e3acc8af 543 protected function normalise_value($column, $value) {
8fb501e9
EL
544 if (is_bool($value)) { // Always, convert boolean to int
545 $value = (int)$value;
546
547 } else if ($value === '') {
548 if ($column->meta_type == 'I' or $column->meta_type == 'F' or $column->meta_type == 'N') {
549 $value = 0; // prevent '' problems in numeric fields
550 }
551 }
552 // workaround for problem with wrong enums in mysql - TODO: Out in Moodle 2.1
553 if (!empty($column->enums)) {
554 if (is_null($value) and !$column->not_null) {
555 // ok - nulls allowed
556 } else {
557 if (!in_array((string)$value, $column->enums)) {
558 throw new dml_write_exception('Enum value '.s($value).' not allowed in field '.$field.' table '.$table.'.');
559 }
560 }
561 }
562 return $value;
563 }
564
7466a42f 565 /**
566 * Is db in unicode mode?
567 * @return bool
568 */
569 public function setup_is_unicodedb() {
a6283e91 570 $sql = "SHOW LOCAL VARIABLES LIKE 'character_set_database'";
571 $this->query_start($sql, null, SQL_QUERY_AUX);
572 $result = $this->mysqli->query($sql);
573 $this->query_end($result);
574
cd4f1859 575 $return = false;
a6283e91 576 if ($result) {
cd4f1859
PS
577 while($row = $result->fetch_assoc()) {
578 if (isset($row['Value'])) {
579 $return = (strtoupper($row['Value']) === 'UTF8' or strtoupper($row['Value']) === 'UTF-8');
580 }
581 break;
582 }
7466a42f 583 $result->close();
7466a42f 584 }
cd4f1859
PS
585
586 if (!$return) {
587 return false;
588 }
589
590 $sql = "SHOW LOCAL VARIABLES LIKE 'collation_database'";
591 $this->query_start($sql, null, SQL_QUERY_AUX);
592 $result = $this->mysqli->query($sql);
593 $this->query_end($result);
594
595 $return = false;
596 if ($result) {
597 while($row = $result->fetch_assoc()) {
598 if (isset($row['Value'])) {
599 $return = (strpos($row['Value'], 'latin1') !== 0);
600 }
601 break;
602 }
603 $result->close();
604 }
605
606 return $return;
7466a42f 607 }
608
7466a42f 609 /**
610 * Do NOT use in code, to be used by database_manager only!
611 * @param string $sql query
22d77567 612 * @return bool true
613 * @throws dml_exception if error
7466a42f 614 */
615 public function change_database_structure($sql) {
117679db 616 $this->reset_caches();
a6283e91 617
618 $this->query_start($sql, null, SQL_QUERY_STRUCTURE);
619 $result = $this->mysqli->query($sql);
620 $this->query_end($result);
621
12e09c6b 622 return true;
7466a42f 623 }
624
625 /**
626 * Very ugly hack which emulates bound parameters in queries
627 * because prepared statements do not use query cache.
628 */
629 protected function emulate_bound_params($sql, array $params=null) {
630 if (empty($params)) {
631 return $sql;
632 }
633 /// ok, we have verified sql statement with ? and correct number of params
634 $return = strtok($sql, '?');
635 foreach ($params as $param) {
636 if (is_bool($param)) {
637 $return .= (int)$param;
638 } else if (is_null($param)) {
639 $return .= 'NULL';
70ff13be
PS
640 } else if (is_number($param)) {
641 $return .= "'".$param."'"; // we have to always use strings because mysql is using weird automatic int casting
c1a6529b 642 } else if (is_float($param)) {
7466a42f 643 $return .= $param;
644 } else {
645 $param = $this->mysqli->real_escape_string($param);
646 $return .= "'$param'";
647 }
648 $return .= strtok('?');
649 }
650 return $return;
651 }
652
653 /**
654 * Execute general sql query. Should be used only when no other method suitable.
655 * Do NOT use this to make changes in db structure, use database_manager::execute_sql() instead!
656 * @param string $sql query
657 * @param array $params query parameters
22d77567 658 * @return bool true
659 * @throws dml_exception if error
7466a42f 660 */
661 public function execute($sql, array $params=null) {
662 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
663
664 if (strpos($sql, ';') !== false) {
22d77567 665 throw new coding_exception('moodle_database::execute() Multiple sql statements found or bound parameters not used properly in query!');
7466a42f 666 }
667
668 $rawsql = $this->emulate_bound_params($sql, $params);
669
a6283e91 670 $this->query_start($sql, $params, SQL_QUERY_UPDATE);
7466a42f 671 $result = $this->mysqli->query($rawsql);
a6283e91 672 $this->query_end($result);
7466a42f 673
22d77567 674 if ($result === true) {
7466a42f 675 return true;
676
677 } else {
678 $result->close();
679 return true;
680 }
681 }
682
683 /**
684 * Get a number of records as a moodle_recordset using a SQL statement.
685 *
686 * Since this method is a little less readable, use of it should be restricted to
687 * code where it's possible there might be large datasets being returned. For known
688 * small datasets use get_records_sql - it leads to simpler code.
689 *
690 * The return type is as for @see function get_recordset.
691 *
692 * @param string $sql the SQL select query to execute.
693 * @param array $params array of sql parameters
694 * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
695 * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
5212b07f 696 * @return moodle_recordset instance
22d77567 697 * @throws dml_exception if error
7466a42f 698 */
699 public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
088a4df8 700 $limitfrom = (int)$limitfrom;
701 $limitnum = (int)$limitnum;
3ff8bf26 702 $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
703 $limitnum = ($limitnum < 0) ? 0 : $limitnum;
704
7466a42f 705 if ($limitfrom or $limitnum) {
7466a42f 706 if ($limitnum < 1) {
707 $limitnum = "18446744073709551615";
708 }
0487f9e2 709 $sql .= " LIMIT $limitfrom, $limitnum";
7466a42f 710 }
711
0487f9e2 712 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
713 $rawsql = $this->emulate_bound_params($sql, $params);
714
a6283e91 715 $this->query_start($sql, $params, SQL_QUERY_SELECT);
7466a42f 716 // no MYSQLI_USE_RESULT here, it would block write ops on affected tables
e0eda209 717 $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
718 $this->query_end($result);
7466a42f 719
e0eda209 720 return $this->create_recordset($result);
7466a42f 721 }
722
723 protected function create_recordset($result) {
724 return new mysqli_native_moodle_recordset($result);
725 }
726
727 /**
728 * Get a number of records as an array of objects using a SQL statement.
729 *
730 * Return value as for @see function get_records.
731 *
732 * @param string $sql the SQL select query to execute. The first column of this SELECT statement
733 * must be a unique value (usually the 'id' field), as it will be used as the key of the
734 * returned array.
735 * @param array $params array of sql parameters
736 * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
737 * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
3503dcad 738 * @return array of objects, or empty array if no records were found
22d77567 739 * @throws dml_exception if error
7466a42f 740 */
741 public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
088a4df8 742 $limitfrom = (int)$limitfrom;
743 $limitnum = (int)$limitnum;
3ff8bf26 744 $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
745 $limitnum = ($limitnum < 0) ? 0 : $limitnum;
746
7466a42f 747 if ($limitfrom or $limitnum) {
7466a42f 748 if ($limitnum < 1) {
749 $limitnum = "18446744073709551615";
750 }
0487f9e2 751 $sql .= " LIMIT $limitfrom, $limitnum";
7466a42f 752 }
753
0487f9e2 754 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
755 $rawsql = $this->emulate_bound_params($sql, $params);
756
a6283e91 757 $this->query_start($sql, $params, SQL_QUERY_SELECT);
7466a42f 758 $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
a6283e91 759 $this->query_end($result);
7466a42f 760
7466a42f 761 $return = array();
a6283e91 762
7466a42f 763 while($row = $result->fetch_assoc()) {
764 $row = array_change_key_case($row, CASE_LOWER);
765 $id = reset($row);
758ba89a 766 if (isset($return[$id])) {
767 $colname = key($row);
768 debugging("Did you remember to make the first column something unique in your call to get_records? Duplicate value '$id' found in column '$colname'.", DEBUG_DEVELOPER);
769 }
7466a42f 770 $return[$id] = (object)$row;
771 }
772 $result->close();
a6283e91 773
7466a42f 774 return $return;
775 }
776
777 /**
778 * Selects records and return values (first field) as an array using a SQL statement.
779 *
780 * @param string $sql The SQL query
781 * @param array $params array of sql parameters
3503dcad 782 * @return array of values
22d77567 783 * @throws dml_exception if error
7466a42f 784 */
785 public function get_fieldset_sql($sql, array $params=null) {
786 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
787 $rawsql = $this->emulate_bound_params($sql, $params);
788
a6283e91 789 $this->query_start($sql, $params, SQL_QUERY_SELECT);
7466a42f 790 $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
a6283e91 791 $this->query_end($result);
7466a42f 792
7466a42f 793 $return = array();
a6283e91 794
7466a42f 795 while($row = $result->fetch_assoc()) {
796 $return[] = reset($row);
797 }
798 $result->close();
a6283e91 799
7466a42f 800 return $return;
801 }
802
803 /**
804 * Insert new record into database, as fast as possible, no safety checks, lobs not supported.
805 * @param string $table name
806 * @param mixed $params data record as object or array
807 * @param bool $returnit return it of inserted record
808 * @param bool $bulk true means repeated inserts expected
809 * @param bool $customsequence true if 'id' included in $params, disables $returnid
3503dcad 810 * @return bool|int true or new id
22d77567 811 * @throws dml_exception if error
7466a42f 812 */
813 public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
814 if (!is_array($params)) {
815 $params = (array)$params;
816 }
817
818 if ($customsequence) {
819 if (!isset($params['id'])) {
22d77567 820 throw new coding_exception('moodle_database::insert_record_raw() id field must be specified if custom sequences used.');
7466a42f 821 }
822 $returnid = false;
823 } else {
824 unset($params['id']);
825 }
826
827 if (empty($params)) {
22d77567 828 throw new coding_exception('moodle_database::insert_record_raw() no fields found.');
7466a42f 829 }
830
7466a42f 831 $fields = implode(',', array_keys($params));
832 $qms = array_fill(0, count($params), '?');
833 $qms = implode(',', $qms);
834
835 $sql = "INSERT INTO {$this->prefix}$table ($fields) VALUES($qms)";
76b6daf2 836
837 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
7466a42f 838 $rawsql = $this->emulate_bound_params($sql, $params);
839
a6283e91 840 $this->query_start($sql, $params, SQL_QUERY_INSERT);
7466a42f 841 $result = $this->mysqli->query($rawsql);
b4154c2d 842 $id = @$this->mysqli->insert_id; // must be called before query_end() which may insert log into db
a6283e91 843 $this->query_end($result);
7466a42f 844
b4154c2d 845 if (!$id) {
22d77567 846 throw new dml_write_exception('unknown error fetching inserted id');
7466a42f 847 }
848
849 if (!$returnid) {
850 return true;
851 } else {
852 return (int)$id;
853 }
854 }
855
856 /**
857 * Insert a record into a table and return the "id" field if required.
858 *
859 * Some conversions and safety checks are carried out. Lobs are supported.
860 * If the return ID isn't required, then this just reports success as true/false.
861 * $data is an object containing needed data
862 * @param string $table The database table to be inserted into
863 * @param object $data A data object with values for one or more fields in the record
864 * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
3503dcad 865 * @return bool|int true or new id
22d77567 866 * @throws dml_exception if error
7466a42f 867 */
868 public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
d8fa8e40 869 $dataobject = (array)$dataobject;
7466a42f 870
871 $columns = $this->get_columns($table);
7466a42f 872 $cleaned = array();
873
874 foreach ($dataobject as $field=>$value) {
d8fa8e40
PS
875 if ($field === 'id') {
876 continue;
877 }
7466a42f 878 if (!isset($columns[$field])) {
879 continue;
880 }
881 $column = $columns[$field];
8fb501e9 882 $cleaned[$field] = $this->normalise_value($column, $value);
7466a42f 883 }
884
7466a42f 885 return $this->insert_record_raw($table, $cleaned, $returnid, $bulk);
886 }
887
888 /**
889 * Import a record into a table, id field is required.
890 * Safety checks are NOT carried out. Lobs are supported.
891 *
892 * @param string $table name of database table to be inserted into
893 * @param object $dataobject A data object with values for one or more fields in the record
22d77567 894 * @return bool true
895 * @throws dml_exception if error
7466a42f 896 */
897 public function import_record($table, $dataobject) {
d8fa8e40 898 $dataobject = (array)$dataobject;
7466a42f 899
7466a42f 900 $columns = $this->get_columns($table);
901 $cleaned = array();
902
903 foreach ($dataobject as $field=>$value) {
904 if (!isset($columns[$field])) {
905 continue;
906 }
907 $cleaned[$field] = $value;
908 }
909
910 return $this->insert_record_raw($table, $cleaned, false, true, true);
911 }
912
913 /**
914 * Update record in database, as fast as possible, no safety checks, lobs not supported.
915 * @param string $table name
916 * @param mixed $params data record as object or array
917 * @param bool true means repeated updates expected
22d77567 918 * @return bool true
919 * @throws dml_exception if error
7466a42f 920 */
921 public function update_record_raw($table, $params, $bulk=false) {
d8fa8e40
PS
922 $params = (array)$params;
923
7466a42f 924 if (!isset($params['id'])) {
22d77567 925 throw new coding_exception('moodle_database::update_record_raw() id field must be specified.');
7466a42f 926 }
927 $id = $params['id'];
928 unset($params['id']);
929
930 if (empty($params)) {
22d77567 931 throw new coding_exception('moodle_database::update_record_raw() no fields found.');
7466a42f 932 }
933
7466a42f 934 $sets = array();
935 foreach ($params as $field=>$value) {
936 $sets[] = "$field = ?";
937 }
938
939 $params[] = $id; // last ? in WHERE condition
940
941 $sets = implode(',', $sets);
942 $sql = "UPDATE {$this->prefix}$table SET $sets WHERE id=?";
76b6daf2 943
944 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
7466a42f 945 $rawsql = $this->emulate_bound_params($sql, $params);
946
a6283e91 947 $this->query_start($sql, $params, SQL_QUERY_UPDATE);
7466a42f 948 $result = $this->mysqli->query($rawsql);
a6283e91 949 $this->query_end($result);
7466a42f 950
7466a42f 951 return true;
952 }
953
954 /**
955 * Update a record in a table
956 *
957 * $dataobject is an object containing needed data
958 * Relies on $dataobject having a variable "id" to
959 * specify the record to update
960 *
961 * @param string $table The database table to be checked against.
962 * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
963 * @param bool true means repeated updates expected
22d77567 964 * @return bool true
965 * @throws dml_exception if error
7466a42f 966 */
967 public function update_record($table, $dataobject, $bulk=false) {
d8fa8e40 968 $dataobject = (array)$dataobject;
7466a42f 969
7466a42f 970 $columns = $this->get_columns($table);
971 $cleaned = array();
972
973 foreach ($dataobject as $field=>$value) {
974 if (!isset($columns[$field])) {
975 continue;
976 }
8fb501e9
EL
977 $column = $columns[$field];
978 $cleaned[$field] = $this->normalise_value($column, $value);
7466a42f 979 }
980
981 return $this->update_record_raw($table, $cleaned, $bulk);
982 }
983
984 /**
985 * Set a single field in every table record which match a particular WHERE clause.
986 *
987 * @param string $table The database table to be checked against.
988 * @param string $newfield the field to set.
989 * @param string $newvalue the value to set the field to.
990 * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
991 * @param array $params array of sql parameters
22d77567 992 * @return bool true
993 * @throws dml_exception if error
7466a42f 994 */
995 public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
996 if ($select) {
997 $select = "WHERE $select";
998 }
999 if (is_null($params)) {
1000 $params = array();
1001 }
1002 list($select, $params, $type) = $this->fix_sql_params($select, $params);
1003
8fb501e9
EL
1004 // Get column metadata
1005 $columns = $this->get_columns($table);
1006 $column = $columns[$newfield];
1007
1008 $normalised_value = $this->normalise_value($column, $newvalue);
1009
1010 if (is_null($normalised_value)) {
7466a42f 1011 $newfield = "$newfield = NULL";
1012 } else {
1013 $newfield = "$newfield = ?";
8fb501e9 1014 array_unshift($params, $normalised_value);
7466a42f 1015 }
1016 $sql = "UPDATE {$this->prefix}$table SET $newfield $select";
1017 $rawsql = $this->emulate_bound_params($sql, $params);
1018
a6283e91 1019 $this->query_start($sql, $params, SQL_QUERY_UPDATE);
7466a42f 1020 $result = $this->mysqli->query($rawsql);
a6283e91 1021 $this->query_end($result);
7466a42f 1022
7466a42f 1023 return true;
1024 }
1025
1026 /**
1027 * Delete one or more records from a table which match a particular WHERE clause.
1028 *
1029 * @param string $table The database table to be checked against.
1030 * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
1031 * @param array $params array of sql parameters
22d77567 1032 * @return bool true
1033 * @throws dml_exception if error
7466a42f 1034 */
1035 public function delete_records_select($table, $select, array $params=null) {
1036 if ($select) {
1037 $select = "WHERE $select";
1038 }
1039 $sql = "DELETE FROM {$this->prefix}$table $select";
1040
1041 list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
1042 $rawsql = $this->emulate_bound_params($sql, $params);
1043
a6283e91 1044 $this->query_start($sql, $params, SQL_QUERY_UPDATE);
7466a42f 1045 $result = $this->mysqli->query($rawsql);
a6283e91 1046 $this->query_end($result);
7466a42f 1047
7466a42f 1048 return true;
1049 }
1050
1051 public function sql_cast_char2int($fieldname, $text=false) {
1052 return ' CAST(' . $fieldname . ' AS SIGNED) ';
9882b2c8
EL
1053 }
1054
1055 public function sql_cast_char2real($fieldname, $text=false) {
1056 return ' CAST(' . $fieldname . ' AS DECIMAL) ';
7466a42f 1057 }
1058
6055f89d
PS
1059 /**
1060 * Returns 'LIKE' part of a query.
1061 *
1062 * @param string $fieldname usually name of the table column
1063 * @param string $param usually bound query parameter (?, :named)
1064 * @param bool $casesensitive use case sensitive search
1065 * @param bool $accensensitive use accent sensitive search (not all databases support accent insensitive)
16114b9d 1066 * @param bool $notlike true means "NOT LIKE"
6055f89d
PS
1067 * @param string $escapechar escape char for '%' and '_'
1068 * @return string SQL code fragment
1069 */
16114b9d 1070 public function sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = '\\') {
6055f89d
PS
1071 if (strpos($param, '%') !== false) {
1072 debugging('Potential SQL injection detected, sql_ilike() expects bound parameters (? or :named)');
1073 }
1074 $escapechar = $this->mysqli->real_escape_string($escapechar); // prevents problems with C-style escapes of enclosing '\'
1075
16114b9d 1076 $LIKE = $notlike ? 'NOT LIKE' : 'LIKE';
6055f89d 1077 if ($casesensitive) {
16114b9d 1078 return "$fieldname $LIKE $param COLLATE utf8_bin ESCAPE '$escapechar'";
6055f89d
PS
1079 } else {
1080 if ($accentsensitive) {
16114b9d 1081 return "LOWER($fieldname) $LIKE LOWER($param) COLLATE utf8_bin ESCAPE '$escapechar'";
6055f89d 1082 } else {
16114b9d 1083 return "$fieldname $LIKE $param ESCAPE '$escapechar'";
6055f89d
PS
1084 }
1085 }
1086 }
1087
215d7cb8
SH
1088 /**
1089 * Returns the proper SQL to do CONCAT between the elements passed
1090 * Can take many parameters
1091 *
1092 * @param string $str,... 1 or more fields/strings to concat
1093 *
1094 * @return string The concat sql
1095 */
7466a42f 1096 public function sql_concat() {
1097 $arr = func_get_args();
082ae821 1098 $s = implode(', ', $arr);
7466a42f 1099 if ($s === '') {
d5d0890c 1100 return "''";
7466a42f 1101 }
1102 return "CONCAT($s)";
1103 }
1104
215d7cb8
SH
1105 /**
1106 * Returns the proper SQL to do CONCAT between the elements passed
1107 * with a given separator
1108 *
1109 * @param string $separator The string to use as the separator
1110 * @param array $elements An array of items to concatenate
1111 * @return string The concat SQL
1112 */
7466a42f 1113 public function sql_concat_join($separator="' '", $elements=array()) {
082ae821 1114 $s = implode(', ', $elements);
1115
7466a42f 1116 if ($s === '') {
d5d0890c 1117 return "''";
7466a42f 1118 }
082ae821 1119 return "CONCAT_WS($separator, $s)";
7466a42f 1120 }
1121
7e0db2e2 1122 /**
1123 * Returns the SQL text to be used to calculate the length in characters of one expression.
1124 * @param string fieldname or expression to calculate its length in characters.
1125 * @return string the piece of SQL code to be used in the statement.
1126 */
1127 public function sql_length($fieldname) {
1128 return ' CHAR_LENGTH(' . $fieldname . ')';
1129 }
1130
7466a42f 1131 /**
02df9cfd 1132 * Does this driver support regex syntax when searching
7466a42f 1133 */
1134 public function sql_regex_supported() {
1135 return true;
1136 }
1137
1138 /**
1139 * Return regex positive or negative match sql
1140 * @param bool $positivematch
1141 * @return string or empty if not supported
1142 */
1143 public function sql_regex($positivematch=true) {
1144 return $positivematch ? 'REGEXP' : 'NOT REGEXP';
1145 }
fa76662b 1146
adff97c5 1147 public function sql_cast_2signed($fieldname) {
1148 return ' CAST(' . $fieldname . ' AS SIGNED) ';
1149 }
1150
7f79aaea 1151/// session locking
5e9dd017 1152 public function session_lock_supported() {
1153 return true;
1154 }
1155
3b1a9849 1156 public function get_session_lock($rowid) {
5e9dd017 1157 parent::get_session_lock($rowid);
3b1a9849 1158 $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
1159 $sql = "SELECT GET_LOCK('$fullname',120)";
1160 $this->query_start($sql, null, SQL_QUERY_AUX);
1161 $result = $this->mysqli->query($sql);
7f79aaea 1162 $this->query_end($result);
1163
1164 if ($result) {
1165 $arr = $result->fetch_assoc();
1166 $result->close();
1167
1168 if (reset($arr) == 1) {
5e9dd017 1169 return;
3b1a9849 1170 } else {
1171 // try again!
5e9dd017 1172 $this->get_session_lock($rowid);
7f79aaea 1173 }
1174 }
7f79aaea 1175 }
1176
3b1a9849 1177 public function release_session_lock($rowid) {
5e9dd017 1178 parent::release_session_lock($rowid);
3b1a9849 1179 $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
1180 $sql = "SELECT RELEASE_LOCK('$fullname')";
1181 $this->query_start($sql, null, SQL_QUERY_AUX);
1182 $result = $this->mysqli->query($sql);
7f79aaea 1183 $this->query_end($result);
1184
1185 if ($result) {
7f79aaea 1186 $result->close();
7f79aaea 1187 }
7f79aaea 1188 }
1189
fa76662b 1190/// transactions
1191 /**
d5a8d9aa
PS
1192 * Are transactions supported?
1193 * It is not responsible to run productions servers
1194 * on databases without transaction support ;-)
1195 *
1196 * MyISAM does not support support transactions.
fa76662b 1197 *
d35ece6c
PS
1198 * You can override this via the dbtransactions option.
1199 *
d5a8d9aa 1200 * @return bool
fa76662b 1201 */
d5a8d9aa
PS
1202 protected function transactions_supported() {
1203 if (!is_null($this->transactions_supported)) {
1204 return $this->transactions_supported;
1205 }
1206
d35ece6c
PS
1207 // this is all just guessing, might be better to just specify it in config.php
1208 if (isset($this->dboptions['dbtransactions'])) {
1209 $this->transactions_supported = $this->dboptions['dbtransactions'];
1210 return $this->transactions_supported;
1211 }
1212
d5a8d9aa
PS
1213 $this->transactions_supported = false;
1214
d35ece6c 1215 $engine = $this->get_dbengine();
d5a8d9aa 1216
d35ece6c
PS
1217 // Only will accept transactions if using compatible storage engine (more engines can be added easily BDB, Falcon...)
1218 if (in_array($engine, array('InnoDB', 'INNOBASE', 'BDB', 'XtraDB', 'Aria', 'Falcon'))) {
1219 $this->transactions_supported = true;
dd67e10c 1220 }
dd67e10c 1221
d5a8d9aa
PS
1222 return $this->transactions_supported;
1223 }
1224
1225 /**
1226 * Driver specific start of real database transaction,
1227 * this can not be used directly in code.
1228 * @return void
1229 */
1230 protected function begin_transaction() {
1231 if (!$this->transactions_supported()) {
1232 return;
a1dda107 1233 }
dd67e10c 1234
a6283e91 1235 $sql = "SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED";
1236 $this->query_start($sql, NULL, SQL_QUERY_AUX);
1237 $result = $this->mysqli->query($sql);
1238 $this->query_end($result);
1239
dd67e10c 1240 $sql = "START TRANSACTION";
a6283e91 1241 $this->query_start($sql, NULL, SQL_QUERY_AUX);
1242 $result = $this->mysqli->query($sql);
1243 $this->query_end($result);
fa76662b 1244 }
1245
1246 /**
d5a8d9aa
PS
1247 * Driver specific commit of real database transaction,
1248 * this can not be used directly in code.
1249 * @return void
fa76662b 1250 */
d5a8d9aa
PS
1251 protected function commit_transaction() {
1252 if (!$this->transactions_supported()) {
1253 return;
a1dda107 1254 }
d5a8d9aa 1255
a6283e91 1256 $sql = "COMMIT";
1257 $this->query_start($sql, NULL, SQL_QUERY_AUX);
1258 $result = $this->mysqli->query($sql);
1259 $this->query_end($result);
fa76662b 1260 }
1261
1262 /**
d5a8d9aa
PS
1263 * Driver specific abort of real database transaction,
1264 * this can not be used directly in code.
1265 * @return void
fa76662b 1266 */
d5a8d9aa
PS
1267 protected function rollback_transaction() {
1268 if (!$this->transactions_supported()) {
1269 return;
a1dda107 1270 }
d5a8d9aa 1271
a6283e91 1272 $sql = "ROLLBACK";
1273 $this->query_start($sql, NULL, SQL_QUERY_AUX);
1274 $result = $this->mysqli->query($sql);
1275 $this->query_end($result);
1276
fa76662b 1277 return true;
1278 }
7466a42f 1279}