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