MDL-25276 dml - completed sql_cast_char2int/real tests to reveal some problems
[moodle.git] / lib / dml / mysqli_native_moodle_database.php
1 <?php
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/>.
19 /**
20  * Native mysqli class representing moodle database interface.
21  *
22  * @package    core
23  * @subpackage dml
24  * @copyright  2008 Petr Skoda (http://skodak.org)
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
28 defined('MOODLE_INTERNAL') || die();
30 require_once($CFG->libdir.'/dml/moodle_database.php');
31 require_once($CFG->libdir.'/dml/mysqli_native_moodle_recordset.php');
32 require_once($CFG->libdir.'/dml/mysqli_native_moodle_temptables.php');
34 /**
35  * Native mysqli class representing moodle database interface.
36  */
37 class mysqli_native_moodle_database extends moodle_database {
39     protected $mysqli = null;
41     private $transactions_supported = null;
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      */
52     public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
53         $driverstatus = $this->driver_installed();
55         if ($driverstatus !== true) {
56             throw new dml_exception('dbdriverproblem', $driverstatus);
57         }
59         ob_start();
60         $conn = new mysqli($dbhost, $dbuser, $dbpass); /// Connect without db
61         $dberr = ob_get_contents();
62         ob_end_clean();
63         $errorno = @$conn->connect_errno;
65         if ($errorno !== 0) {
66             throw new dml_connection_exception($dberr);
67         }
69         $result = $conn->query("CREATE DATABASE $dbname DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci");
71         $conn->close();
73         if (!$result) {
74             throw new dml_exception('cannotcreatedb');
75         }
77         return true;
78     }
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     }
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     }
101     /**
102      * Returns more specific database driver type
103      * Note: can be used before connect()
104      * @return string db type mysqli, pgsql, oci, mssql, sqlsrv
105      */
106     protected function get_dbtype() {
107         return 'mysqli';
108     }
110     /**
111      * Returns general database library name
112      * Note: can be used before connect()
113      * @return string db type pdo, native
114      */
115     protected function get_dblibrary() {
116         return 'native';
117     }
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         }
133         $engine = null;
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         }
148         if ($engine) {
149             return $engine;
150         }
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();
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);
168             $engines = array();
169             while ($res = $result->fetch_assoc()) {
170                 if ($res['Support'] === 'YES' or $res['Support'] === 'DEFAULT') {
171                     $engines[$res['Engine']] = true;
172                 }
173             }
174             $result->close();
175             if (isset($engines['InnoDB'])) {
176                 $engine = 'InnoDB';
177             }
178             if (isset($engines['XtraDB'])) {
179                 $engine = 'XtraDB';
180             }
181         }
183         return $engine;
184     }
186     /**
187      * Returns localised database type name
188      * Note: can be used before connect()
189      * @return string
190      */
191     public function get_name() {
192         return get_string('nativemysqli', 'install');
193     }
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     }
204     /**
205      * Returns localised database description
206      * Note: can be used before connect()
207      * @return string
208      */
209     public function get_configuration_hints() {
210         return get_string('databasesettingssub_mysqli', 'install');
211     }
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         }
236         if ($sloppymyisamfound) {
237             return get_string('myisamproblem', 'error');
238         } else {
239             return null;
240         }
241     }
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
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      */
254     public function connect($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions=null) {
255         $driverstatus = $this->driver_installed();
257         if ($driverstatus !== true) {
258             throw new dml_exception('dbdriverproblem', $driverstatus);
259         }
261         $this->store_settings($dbhost, $dbuser, $dbpass, $dbname, $prefix, $dboptions);
262         unset($this->dboptions['dbsocket']);
264         ob_start();
265         $this->mysqli = new mysqli($dbhost, $dbuser, $dbpass, $dbname);
266         $dberr = ob_get_contents();
267         ob_end_clean();
268         $errorno = @$this->mysqli->connect_errno;
270         if ($errorno !== 0) {
271             throw new dml_connection_exception($dberr);
272         }
274         $this->query_start("--set_charset()", null, SQL_QUERY_AUX);
275         $this->mysqli->set_charset('utf8');
276         $this->query_end(true);
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.
281         // With strict mode enforced, Moodle DB layer will be consistently throwing
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         }
291         // Connection stabilished and configured, going to instantiate the temptables controller
292         $this->temptables = new mysqli_native_moodle_temptables($this);
294         return true;
295     }
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() {
303         parent::dispose(); // Call parent dispose to write/close session and other common stuff before closing connection
304         if ($this->mysqli) {
305             $this->mysqli->close();
306             $this->mysqli = null;
307         }
308     }
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     }
318     /**
319      * Returns supported query parameter types
320      * @return int bitmask
321      */
322     protected function allowed_param_types() {
323         return SQL_PARAMS_QM;
324     }
326     /**
327      * Returns last error reported by database engine.
328      * @return string error message
329      */
330     public function get_last_error() {
331         return $this->mysqli->error;
332     }
334     /**
335      * Return tables in database WITHOUT current prefix
336      * @return array of table names in lowercase and without prefix
337      */
338     public function get_tables($usecache=true) {
339         if ($usecache and $this->tables !== null) {
340             return $this->tables;
341         }
342         $this->tables = array();
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) {
348             while ($arr = $result->fetch_assoc()) {
349                 $tablename = reset($arr);
350                 if ($this->prefix !== '') {
351                     if (strpos($tablename, $this->prefix) !== 0) {
352                         continue;
353                     }
354                     $tablename = substr($tablename, strlen($this->prefix));
355                 }
356                 $this->tables[$tablename] = $tablename;
357             }
358             $result->close();
359         }
361         // Add the currently available temptables
362         $this->tables = array_merge($this->tables, $this->temptables->get_temptables());
363         return $this->tables;
364     }
366     /**
367      * Return table indexes - everything lowercased
368      * @return array of arrays
369      */
370     public function get_indexes($table) {
371         $indexes = array();
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) {
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     }
391     /**
392      * Returns detailed information about columns in table. This information is cached internally.
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         }
402         $this->columns[$table] = array();
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);
409         if ($result === false) {
410             return array();
411         }
413         while ($rawcolumn = $result->fetch_assoc()) {
414             $rawcolumn = (object)array_change_key_case($rawcolumn, CASE_LOWER);
416             $info = new stdClass();
417             $info->name = $rawcolumn->field;
418             $matches = null;
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;
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                 }
461             } else if (preg_match('/(decimal|double|float)\((\d+),(\d+)\)/i', $rawcolumn->type, $matches)) {
462                 $info->type          = $matches[1];
463                 $info->meta_type     = 'N';
464                 $info->max_length    = $matches[2];
465                 $info->scale         = $matches[3];
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;
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;
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;
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             }
528             $this->columns[$table][$info->name] = new database_column_info($info);
529         }
531         $result->close();
533         return $this->columns[$table];
534     }
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      */
543     protected function normalise_value($column, $value) {
544         if (is_bool($value)) { // Always, convert boolean to int
545             $value = (int)$value;
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     }
565     /**
566      * Is db in unicode mode?
567      * @return bool
568      */
569     public function setup_is_unicodedb() {
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);
575         $return = false;
576         if ($result) {
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             }
583             $result->close();
584         }
586         if (!$return) {
587             return false;
588         }
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);
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         }
606         return $return;
607     }
609     /**
610      * Do NOT use in code, to be used by database_manager only!
611      * @param string $sql query
612      * @return bool true
613      * @throws dml_exception if error
614      */
615     public function change_database_structure($sql) {
616         $this->reset_caches();
618         $this->query_start($sql, null, SQL_QUERY_STRUCTURE);
619         $result = $this->mysqli->query($sql);
620         $this->query_end($result);
622         return true;
623     }
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';
640             } else if (is_number($param)) {
641                 $return .= "'".$param."'"; // we have to always use strings because mysql is using weird automatic int casting
642             } else if (is_float($param)) {
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     }
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
658      * @return bool true
659      * @throws dml_exception if error
660      */
661     public function execute($sql, array $params=null) {
662         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
664         if (strpos($sql, ';') !== false) {
665             throw new coding_exception('moodle_database::execute() Multiple sql statements found or bound parameters not used properly in query!');
666         }
668         $rawsql = $this->emulate_bound_params($sql, $params);
670         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
671         $result = $this->mysqli->query($rawsql);
672         $this->query_end($result);
674         if ($result === true) {
675             return true;
677         } else {
678             $result->close();
679             return true;
680         }
681     }
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).
696      * @return moodle_recordset instance
697      * @throws dml_exception if error
698      */
699     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
700         $limitfrom = (int)$limitfrom;
701         $limitnum  = (int)$limitnum;
702         $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
703         $limitnum  = ($limitnum < 0)  ? 0 : $limitnum;
705         if ($limitfrom or $limitnum) {
706             if ($limitnum < 1) {
707                 $limitnum = "18446744073709551615";
708             }
709             $sql .= " LIMIT $limitfrom, $limitnum";
710         }
712         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
713         $rawsql = $this->emulate_bound_params($sql, $params);
715         $this->query_start($sql, $params, SQL_QUERY_SELECT);
716         // no MYSQLI_USE_RESULT here, it would block write ops on affected tables
717         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
718         $this->query_end($result);
720         return $this->create_recordset($result);
721     }
723     protected function create_recordset($result) {
724         return new mysqli_native_moodle_recordset($result);
725     }
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).
738      * @return array of objects, or empty array if no records were found
739      * @throws dml_exception if error
740      */
741     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
742         $limitfrom = (int)$limitfrom;
743         $limitnum  = (int)$limitnum;
744         $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
745         $limitnum  = ($limitnum < 0)  ? 0 : $limitnum;
747         if ($limitfrom or $limitnum) {
748             if ($limitnum < 1) {
749                 $limitnum = "18446744073709551615";
750             }
751             $sql .= " LIMIT $limitfrom, $limitnum";
752         }
754         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
755         $rawsql = $this->emulate_bound_params($sql, $params);
757         $this->query_start($sql, $params, SQL_QUERY_SELECT);
758         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
759         $this->query_end($result);
761         $return = array();
763         while($row = $result->fetch_assoc()) {
764             $row = array_change_key_case($row, CASE_LOWER);
765             $id  = reset($row);
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             }
770             $return[$id] = (object)$row;
771         }
772         $result->close();
774         return $return;
775     }
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
782      * @return array of values
783      * @throws dml_exception if error
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);
789         $this->query_start($sql, $params, SQL_QUERY_SELECT);
790         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
791         $this->query_end($result);
793         $return = array();
795         while($row = $result->fetch_assoc()) {
796             $return[] = reset($row);
797         }
798         $result->close();
800         return $return;
801     }
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
810      * @return bool|int true or new id
811      * @throws dml_exception if error
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         }
818         if ($customsequence) {
819             if (!isset($params['id'])) {
820                 throw new coding_exception('moodle_database::insert_record_raw() id field must be specified if custom sequences used.');
821             }
822             $returnid = false;
823         } else {
824             unset($params['id']);
825         }
827         if (empty($params)) {
828             throw new coding_exception('moodle_database::insert_record_raw() no fields found.');
829         }
831         $fields = implode(',', array_keys($params));
832         $qms    = array_fill(0, count($params), '?');
833         $qms    = implode(',', $qms);
835         $sql = "INSERT INTO {$this->prefix}$table ($fields) VALUES($qms)";
837         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
838         $rawsql = $this->emulate_bound_params($sql, $params);
840         $this->query_start($sql, $params, SQL_QUERY_INSERT);
841         $result = $this->mysqli->query($rawsql);
842         $id = @$this->mysqli->insert_id; // must be called before query_end() which may insert log into db
843         $this->query_end($result);
845         if (!$id) {
846             throw new dml_write_exception('unknown error fetching inserted id');
847         }
849         if (!$returnid) {
850             return true;
851         } else {
852             return (int)$id;
853         }
854     }
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.
865      * @return bool|int true or new id
866      * @throws dml_exception if error
867      */
868     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
869         $dataobject = (array)$dataobject;
871         $columns = $this->get_columns($table);
872         $cleaned = array();
874         foreach ($dataobject as $field=>$value) {
875             if ($field === 'id') {
876                 continue;
877             }
878             if (!isset($columns[$field])) {
879                 continue;
880             }
881             $column = $columns[$field];
882             $cleaned[$field] = $this->normalise_value($column, $value);
883         }
885         return $this->insert_record_raw($table, $cleaned, $returnid, $bulk);
886     }
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
894      * @return bool true
895      * @throws dml_exception if error
896      */
897     public function import_record($table, $dataobject) {
898         $dataobject = (array)$dataobject;
900         $columns = $this->get_columns($table);
901         $cleaned = array();
903         foreach ($dataobject as $field=>$value) {
904             if (!isset($columns[$field])) {
905                 continue;
906             }
907             $cleaned[$field] = $value;
908         }
910         return $this->insert_record_raw($table, $cleaned, false, true, true);
911     }
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
918      * @return bool true
919      * @throws dml_exception if error
920      */
921     public function update_record_raw($table, $params, $bulk=false) {
922         $params = (array)$params;
924         if (!isset($params['id'])) {
925             throw new coding_exception('moodle_database::update_record_raw() id field must be specified.');
926         }
927         $id = $params['id'];
928         unset($params['id']);
930         if (empty($params)) {
931             throw new coding_exception('moodle_database::update_record_raw() no fields found.');
932         }
934         $sets = array();
935         foreach ($params as $field=>$value) {
936             $sets[] = "$field = ?";
937         }
939         $params[] = $id; // last ? in WHERE condition
941         $sets = implode(',', $sets);
942         $sql = "UPDATE {$this->prefix}$table SET $sets WHERE id=?";
944         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
945         $rawsql = $this->emulate_bound_params($sql, $params);
947         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
948         $result = $this->mysqli->query($rawsql);
949         $this->query_end($result);
951         return true;
952     }
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
964      * @return bool true
965      * @throws dml_exception if error
966      */
967     public function update_record($table, $dataobject, $bulk=false) {
968         $dataobject = (array)$dataobject;
970         $columns = $this->get_columns($table);
971         $cleaned = array();
973         foreach ($dataobject as $field=>$value) {
974             if (!isset($columns[$field])) {
975                 continue;
976             }
977             $column = $columns[$field];
978             $cleaned[$field] = $this->normalise_value($column, $value);
979         }
981         return $this->update_record_raw($table, $cleaned, $bulk);
982     }
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
992      * @return bool true
993      * @throws dml_exception if error
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);
1004         // Get column metadata
1005         $columns = $this->get_columns($table);
1006         $column = $columns[$newfield];
1008         $normalised_value = $this->normalise_value($column, $newvalue);
1010         if (is_null($normalised_value)) {
1011             $newfield = "$newfield = NULL";
1012         } else {
1013             $newfield = "$newfield = ?";
1014             array_unshift($params, $normalised_value);
1015         }
1016         $sql = "UPDATE {$this->prefix}$table SET $newfield $select";
1017         $rawsql = $this->emulate_bound_params($sql, $params);
1019         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
1020         $result = $this->mysqli->query($rawsql);
1021         $this->query_end($result);
1023         return true;
1024     }
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
1032      * @return bool true
1033      * @throws dml_exception if error
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";
1041         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
1042         $rawsql = $this->emulate_bound_params($sql, $params);
1044         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
1045         $result = $this->mysqli->query($rawsql);
1046         $this->query_end($result);
1048         return true;
1049     }
1051     public function sql_cast_char2int($fieldname, $text=false) {
1052         return ' CAST(' . $fieldname . ' AS SIGNED) ';
1053     }
1055     /**
1056      * Returns 'LIKE' part of a query.
1057      *
1058      * @param string $fieldname usually name of the table column
1059      * @param string $param usually bound query parameter (?, :named)
1060      * @param bool $casesensitive use case sensitive search
1061      * @param bool $accensensitive use accent sensitive search (not all databases support accent insensitive)
1062      * @param bool $notlike true means "NOT LIKE"
1063      * @param string $escapechar escape char for '%' and '_'
1064      * @return string SQL code fragment
1065      */
1066     public function sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = '\\') {
1067         if (strpos($param, '%') !== false) {
1068             debugging('Potential SQL injection detected, sql_ilike() expects bound parameters (? or :named)');
1069         }
1070         $escapechar = $this->mysqli->real_escape_string($escapechar); // prevents problems with C-style escapes of enclosing '\'
1072         $LIKE = $notlike ? 'NOT LIKE' : 'LIKE';
1073         if ($casesensitive) {
1074             return "$fieldname $LIKE $param COLLATE utf8_bin ESCAPE '$escapechar'";
1075         } else {
1076             if ($accentsensitive) {
1077                 return "LOWER($fieldname) $LIKE LOWER($param) COLLATE utf8_bin ESCAPE '$escapechar'";
1078             } else {
1079                 return "$fieldname $LIKE $param ESCAPE '$escapechar'";
1080             }
1081         }
1082     }
1084     /**
1085      * Returns the proper SQL to do CONCAT between the elements passed
1086      * Can take many parameters
1087      *
1088      * @param string $str,... 1 or more fields/strings to concat
1089      *
1090      * @return string The concat sql
1091      */
1092     public function sql_concat() {
1093         $arr = func_get_args();
1094         $s = implode(', ', $arr);
1095         if ($s === '') {
1096             return "''";
1097         }
1098         return "CONCAT($s)";
1099     }
1101     /**
1102      * Returns the proper SQL to do CONCAT between the elements passed
1103      * with a given separator
1104      *
1105      * @param string $separator The string to use as the separator
1106      * @param array $elements An array of items to concatenate
1107      * @return string The concat SQL
1108      */
1109     public function sql_concat_join($separator="' '", $elements=array()) {
1110         $s = implode(', ', $elements);
1112         if ($s === '') {
1113             return "''";
1114         }
1115         return "CONCAT_WS($separator, $s)";
1116     }
1118     /**
1119      * Returns the SQL text to be used to calculate the length in characters of one expression.
1120      * @param string fieldname or expression to calculate its length in characters.
1121      * @return string the piece of SQL code to be used in the statement.
1122      */
1123     public function sql_length($fieldname) {
1124         return ' CHAR_LENGTH(' . $fieldname . ')';
1125     }
1127     /**
1128      * Does this driver support regex syntax when searching
1129      */
1130     public function sql_regex_supported() {
1131         return true;
1132     }
1134     /**
1135      * Return regex positive or negative match sql
1136      * @param bool $positivematch
1137      * @return string or empty if not supported
1138      */
1139     public function sql_regex($positivematch=true) {
1140         return $positivematch ? 'REGEXP' : 'NOT REGEXP';
1141     }
1143     public function sql_cast_2signed($fieldname) {
1144         return ' CAST(' . $fieldname . ' AS SIGNED) ';
1145     }
1147 /// session locking
1148     public function session_lock_supported() {
1149         return true;
1150     }
1152     public function get_session_lock($rowid) {
1153         parent::get_session_lock($rowid);
1154         $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
1155         $sql = "SELECT GET_LOCK('$fullname',120)";
1156         $this->query_start($sql, null, SQL_QUERY_AUX);
1157         $result = $this->mysqli->query($sql);
1158         $this->query_end($result);
1160         if ($result) {
1161             $arr = $result->fetch_assoc();
1162             $result->close();
1164             if (reset($arr) == 1) {
1165                 return;
1166             } else {
1167                 // try again!
1168                 $this->get_session_lock($rowid);
1169             }
1170         }
1171     }
1173     public function release_session_lock($rowid) {
1174         parent::release_session_lock($rowid);
1175         $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
1176         $sql = "SELECT RELEASE_LOCK('$fullname')";
1177         $this->query_start($sql, null, SQL_QUERY_AUX);
1178         $result = $this->mysqli->query($sql);
1179         $this->query_end($result);
1181         if ($result) {
1182             $result->close();
1183         }
1184     }
1186 /// transactions
1187     /**
1188      * Are transactions supported?
1189      * It is not responsible to run productions servers
1190      * on databases without transaction support ;-)
1191      *
1192      * MyISAM does not support support transactions.
1193      *
1194      * You can override this via the dbtransactions option.
1195      *
1196      * @return bool
1197      */
1198     protected function transactions_supported() {
1199         if (!is_null($this->transactions_supported)) {
1200             return $this->transactions_supported;
1201         }
1203         // this is all just guessing, might be better to just specify it in config.php
1204         if (isset($this->dboptions['dbtransactions'])) {
1205             $this->transactions_supported = $this->dboptions['dbtransactions'];
1206             return $this->transactions_supported;
1207         }
1209         $this->transactions_supported = false;
1211         $engine = $this->get_dbengine();
1213         // Only will accept transactions if using compatible storage engine (more engines can be added easily BDB, Falcon...)
1214         if (in_array($engine, array('InnoDB', 'INNOBASE', 'BDB', 'XtraDB', 'Aria', 'Falcon'))) {
1215             $this->transactions_supported = true;
1216         }
1218         return $this->transactions_supported;
1219     }
1221     /**
1222      * Driver specific start of real database transaction,
1223      * this can not be used directly in code.
1224      * @return void
1225      */
1226     protected function begin_transaction() {
1227         if (!$this->transactions_supported()) {
1228             return;
1229         }
1231         $sql = "SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED";
1232         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1233         $result = $this->mysqli->query($sql);
1234         $this->query_end($result);
1236         $sql = "START TRANSACTION";
1237         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1238         $result = $this->mysqli->query($sql);
1239         $this->query_end($result);
1240     }
1242     /**
1243      * Driver specific commit of real database transaction,
1244      * this can not be used directly in code.
1245      * @return void
1246      */
1247     protected function commit_transaction() {
1248         if (!$this->transactions_supported()) {
1249             return;
1250         }
1252         $sql = "COMMIT";
1253         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1254         $result = $this->mysqli->query($sql);
1255         $this->query_end($result);
1256     }
1258     /**
1259      * Driver specific abort of real database transaction,
1260      * this can not be used directly in code.
1261      * @return void
1262      */
1263     protected function rollback_transaction() {
1264         if (!$this->transactions_supported()) {
1265             return;
1266         }
1268         $sql = "ROLLBACK";
1269         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1270         $result = $this->mysqli->query($sql);
1271         $this->query_end($result);
1273         return true;
1274     }