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