comment typos again
[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    moodlecore
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 require_once($CFG->libdir.'/dml/moodle_database.php');
29 require_once($CFG->libdir.'/dml/mysqli_native_moodle_recordset.php');
30 require_once($CFG->libdir.'/dml/mysqli_native_moodle_temptables.php');
32 /**
33  * Native mysqli class representing moodle database interface.
34  */
35 class mysqli_native_moodle_database extends moodle_database {
37     protected $mysqli = null;
39     private $transactions_supported = null;
41     /**
42      * Attempt to create the database
43      * @param string $dbhost
44      * @param string $dbuser
45      * @param string $dbpass
46      * @param string $dbname
47      * @return bool success
48      * @throws dml_exception if error
49      */
50     public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
51         $driverstatus = $this->driver_installed();
53         if ($driverstatus !== true) {
54             throw new dml_exception('dbdriverproblem', $driverstatus);
55         }
57         ob_start();
58         $conn = new mysqli($dbhost, $dbuser, $dbpass); /// Connect without db
59         $dberr = ob_get_contents();
60         ob_end_clean();
61         $errorno = @$conn->connect_errno;
63         if ($errorno !== 0) {
64             throw new dml_connection_exception($dberr);
65         }
67         $result = $conn->query("CREATE DATABASE $dbname DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci");
69         $conn->close();
71         if (!$result) {
72             throw new dml_exception('cannotcreatedb');
73         }
75         return true;
76     }
78     /**
79      * Detects if all needed PHP stuff installed.
80      * Note: can be used before connect()
81      * @return mixed true if ok, string if something
82      */
83     public function driver_installed() {
84         if (!extension_loaded('mysqli')) {
85             return get_string('mysqliextensionisnotpresentinphp', 'install');
86         }
87         return true;
88     }
90     /**
91      * Returns database family type - describes SQL dialect
92      * Note: can be used before connect()
93      * @return string db family name (mysql, postgres, mssql, oracle, etc.)
94      */
95     public function get_dbfamily() {
96         return 'mysql';
97     }
99     /**
100      * Returns more specific database driver type
101      * Note: can be used before connect()
102      * @return string db type mysql, mysqli, postgres7
103      */
104     protected function get_dbtype() {
105         return 'mysqli';
106     }
108     /**
109      * Returns general database library name
110      * Note: can be used before connect()
111      * @return string db type pdo, native
112      */
113     protected function get_dblibrary() {
114         return 'native';
115     }
117     /**
118      * Returns localised database type name
119      * Note: can be used before connect()
120      * @return string
121      */
122     public function get_name() {
123         return get_string('nativemysqli', 'install');
124     }
126     /**
127      * Returns localised database configuration help.
128      * Note: can be used before connect()
129      * @return string
130      */
131     public function get_configuration_help() {
132         return get_string('nativemysqlihelp', 'install');
133     }
135     /**
136      * Returns localised database description
137      * Note: can be used before connect()
138      * @return string
139      */
140     public function get_configuration_hints() {
141         return get_string('databasesettingssub_mysqli', 'install');
142     }
144     /**
145      * Connect to db
146      * Must be called before other methods.
147      * @param string $dbhost
148      * @param string $dbuser
149      * @param string $dbpass
150      * @param string $dbname
151      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
152      * @param array $dboptions driver specific options
153      * @return bool success
154      */
155     public function connect($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions=null) {
156         $driverstatus = $this->driver_installed();
158         if ($driverstatus !== true) {
159             throw new dml_exception('dbdriverproblem', $driverstatus);
160         }
162         $this->store_settings($dbhost, $dbuser, $dbpass, $dbname, $prefix, $dboptions);
163         unset($this->dboptions['dbsocket']);
165         ob_start();
166         $this->mysqli = new mysqli($dbhost, $dbuser, $dbpass, $dbname);
167         $dberr = ob_get_contents();
168         ob_end_clean();
169         $errorno = @$this->mysqli->connect_errno;
171         if ($errorno !== 0) {
172             throw new dml_connection_exception($dberr);
173         }
175         $this->query_start("--set_charset()", null, SQL_QUERY_AUX);
176         $this->mysqli->set_charset('utf8');
177         $this->query_end(true);
179         // If available, enforce strict mode for the session. That guaranties
180         // standard behaviour under some situations, avoiding some MySQL nasty
181         // habits like truncating data or performing some transparent cast losses.
182         // With strict mode enforced, Moodle DB layer will be consistently throwing
183         // the corresponding exceptions as expected.
184         $si = $this->get_server_info();
185         if (version_compare($si['version'], '5.0.2', '>=')) {
186             $sql = "SET SESSION sql_mode = 'STRICT_ALL_TABLES'";
187             $this->query_start($sql, null, SQL_QUERY_AUX);
188             $result = $this->mysqli->query($sql);
189             $this->query_end($result);
190         }
192         // Connection stabilished and configured, going to instantiate the temptables controller
193         $this->temptables = new mysqli_native_moodle_temptables($this);
195         return true;
196     }
198     /**
199      * Close database connection and release all resources
200      * and memory (especially circular memory references).
201      * Do NOT use connect() again, create a new instance if needed.
202      */
203     public function dispose() {
204         parent::dispose(); // Call parent dispose to write/close session and other common stuff before closing connection
205         if ($this->mysqli) {
206             $this->mysqli->close();
207             $this->mysqli = null;
208         }
209     }
211     /**
212      * Returns database server info array
213      * @return array
214      */
215     public function get_server_info() {
216         return array('description'=>$this->mysqli->server_info, 'version'=>$this->mysqli->server_info);
217     }
219     /**
220      * Returns supported query parameter types
221      * @return bitmask
222      */
223     protected function allowed_param_types() {
224         return SQL_PARAMS_QM;
225     }
227     /**
228      * Returns last error reported by database engine.
229      */
230     public function get_last_error() {
231         return $this->mysqli->error;
232     }
234     /**
235      * Return tables in database WITHOUT current prefix
236      * @return array of table names in lowercase and without prefix
237      */
238     public function get_tables($usecache=true) {
239         if ($usecache and $this->tables !== null) {
240             return $this->tables;
241         }
242         $this->tables = array();
243         $sql = "SHOW TABLES";
244         $this->query_start($sql, null, SQL_QUERY_AUX);
245         $result = $this->mysqli->query($sql);
246         $this->query_end($result);
247         if ($result) {
248             while ($arr = $result->fetch_assoc()) {
249                 $tablename = reset($arr);
250                 if ($this->prefix !== '') {
251                     if (strpos($tablename, $this->prefix) !== 0) {
252                         continue;
253                     }
254                     $tablename = substr($tablename, strlen($this->prefix));
255                 }
256                 $this->tables[$tablename] = $tablename;
257             }
258             $result->close();
259         }
261         // Add the currently available temptables
262         $this->tables = array_merge($this->tables, $this->temptables->get_temptables());
263         return $this->tables;
264     }
266     /**
267      * Return table indexes - everything lowercased
268      * @return array of arrays
269      */
270     public function get_indexes($table) {
271         $indexes = array();
272         $sql = "SHOW INDEXES FROM {$this->prefix}$table";
273         $this->query_start($sql, null, SQL_QUERY_AUX);
274         $result = $this->mysqli->query($sql);
275         $this->query_end($result);
276         if ($result) {
277             while ($res = $result->fetch_object()) {
278                 if ($res->Key_name === 'PRIMARY') {
279                     continue;
280                 }
281                 if (!isset($indexes[$res->Key_name])) {
282                     $indexes[$res->Key_name] = array('unique'=>empty($res->Non_unique), 'columns'=>array());
283                 }
284                 $indexes[$res->Key_name]['columns'][$res->Seq_in_index-1] = $res->Column_name;
285             }
286             $result->close();
287         }
288         return $indexes;
289     }
291     /**
292      * Returns detailed information about columns in table. This information is cached internally.
293      * @param string $table name
294      * @param bool $usecache
295      * @return array array of database_column_info objects indexed with column names
296      */
297     public function get_columns($table, $usecache=true) {
298         if ($usecache and isset($this->columns[$table])) {
299             return $this->columns[$table];
300         }
302         $this->columns[$table] = array();
304         $sql = "SHOW COLUMNS FROM {$this->prefix}$table";
305         $this->query_start($sql, null, SQL_QUERY_AUX);
306         $result = $this->mysqli->query($sql);
307         $this->query_end($result);
309         if ($result === false) {
310             return array();
311         }
313         while ($rawcolumn = $result->fetch_assoc()) {
314             $rawcolumn = (object)array_change_key_case($rawcolumn, CASE_LOWER);
316             $info = new object();
317             $info->name = $rawcolumn->field;
318             $matches = null;
320             if (preg_match('/varchar\((\d+)\)/i', $rawcolumn->type, $matches)) {
321                 $info->type          = 'varchar';
322                 $info->meta_type     = 'C';
323                 $info->max_length    = $matches[1];
324                 $info->scale         = null;
325                 $info->not_null      = ($rawcolumn->null === 'NO');
326                 $info->default_value = $rawcolumn->default;
327                 $info->has_default   = is_null($info->default_value) ? false : true;
328                 $info->primary_key   = ($rawcolumn->key === 'PRI');
329                 $info->binary        = false;
330                 $info->unsigned      = null;
331                 $info->auto_increment= false;
332                 $info->unique        = null;
334             } else if (preg_match('/([a-z]*int[a-z]*)\((\d+)\)/i', $rawcolumn->type, $matches)) {
335                 $info->type = $matches[1];
336                 $info->primary_key       = ($rawcolumn->key === 'PRI');
337                 if ($info->primary_key) {
338                     $info->meta_type     = 'R';
339                     $info->max_length    = $matches[2];
340                     $info->scale         = null;
341                     $info->not_null      = ($rawcolumn->null === 'NO');
342                     $info->default_value = $rawcolumn->default;
343                     $info->has_default   = is_null($info->default_value) ? false : true;
344                     $info->binary        = false;
345                     $info->unsigned      = (stripos($rawcolumn->type, 'unsigned') !== false);
346                     $info->auto_increment= true;
347                     $info->unique        = true;
348                 } else {
349                     $info->meta_type     = 'I';
350                     $info->max_length    = $matches[2];
351                     $info->scale         = null;
352                     $info->not_null      = ($rawcolumn->null === 'NO');
353                     $info->default_value = $rawcolumn->default;
354                     $info->has_default   = is_null($info->default_value) ? false : true;
355                     $info->binary        = false;
356                     $info->unsigned      = (stripos($rawcolumn->type, 'unsigned') !== false);
357                     $info->auto_increment= false;
358                     $info->unique        = null;
359                 }
361             } else if (preg_match('/(decimal|double|float)\((\d+),(\d+)\)/i', $rawcolumn->type, $matches)) {
362                 $info->type          = $matches[1];
363                 $info->meta_type     = 'N';
364                 $info->max_length    = $matches[2];
365                 $info->scale         = $matches[3];
366                 $info->not_null      = ($rawcolumn->null === 'NO');
367                 $info->default_value = $rawcolumn->default;
368                 $info->has_default   = is_null($info->default_value) ? false : true;
369                 $info->primary_key   = ($rawcolumn->key === 'PRI');
370                 $info->binary        = false;
371                 $info->unsigned      = null;
372                 $info->auto_increment= false;
373                 $info->unique        = null;
375             } else if (preg_match('/([a-z]*text)/i', $rawcolumn->type, $matches)) {
376                 $info->type          = $matches[1];
377                 $info->meta_type     = 'X';
378                 $info->max_length    = -1;
379                 $info->scale         = null;
380                 $info->not_null      = ($rawcolumn->null === 'NO');
381                 $info->default_value = $rawcolumn->default;
382                 $info->has_default   = is_null($info->default_value) ? false : true;
383                 $info->primary_key   = ($rawcolumn->key === 'PRI');
384                 $info->binary        = false;
385                 $info->unsigned      = null;
386                 $info->auto_increment= false;
387                 $info->unique        = null;
389             } else if (preg_match('/([a-z]*blob)/i', $rawcolumn->type, $matches)) {
390                 $info->type          = $matches[1];
391                 $info->meta_type     = 'B';
392                 $info->max_length    = -1;
393                 $info->scale         = null;
394                 $info->not_null      = ($rawcolumn->null === 'NO');
395                 $info->default_value = $rawcolumn->default;
396                 $info->has_default   = is_null($info->default_value) ? false : true;
397                 $info->primary_key   = false;
398                 $info->binary        = true;
399                 $info->unsigned      = null;
400                 $info->auto_increment= false;
401                 $info->unique        = null;
403             } else if (preg_match('/enum\((.*)\)/i', $rawcolumn->type, $matches)) {
404                 $info->type          = 'enum';
405                 $info->meta_type     = 'C';
406                 $info->enums         = array();
407                 $info->max_length    = 0;
408                 $values = $matches[1];
409                 $values = explode(',', $values);
410                 $textlib = textlib_get_instance();
411                 foreach ($values as $val) {
412                     $val = trim($val, "'");
413                     $length = $textlib->strlen($val);
414                     $info->enums[] = $val;
415                     $info->max_length = ($info->max_length < $length) ? $length : $info->max_length;
416                 }
417                 $info->scale         = null;
418                 $info->not_null      = ($rawcolumn->null === 'NO');
419                 $info->default_value = $rawcolumn->default;
420                 $info->has_default   = is_null($info->default_value) ? false : true;
421                 $info->primary_key   = ($rawcolumn->key === 'PRI');
422                 $info->binary        = false;
423                 $info->unsigned      = null;
424                 $info->auto_increment= false;
425                 $info->unique        = null;
426             }
428             $this->columns[$table][$info->name] = new database_column_info($info);
429         }
431         $result->close();
433         return $this->columns[$table];
434     }
436     /**
437      * Normalise values based in RDBMS dependencies (booleans, LOBs...)
438      *
439      * @param database_column_info $column column metadata corresponding with the value we are going to normalise
440      * @param mixed $value value we are going to normalise
441      * @return mixed the normalised value
442      */
443     protected function normalise_value($column, $value) {
444         if (is_bool($value)) { // Always, convert boolean to int
445             $value = (int)$value;
447         } else if ($value === '') {
448             if ($column->meta_type == 'I' or $column->meta_type == 'F' or $column->meta_type == 'N') {
449                 $value = 0; // prevent '' problems in numeric fields
450             }
451         }
452         // workaround for problem with wrong enums in mysql - TODO: Out in Moodle 2.1
453         if (!empty($column->enums)) {
454             if (is_null($value) and !$column->not_null) {
455                 // ok - nulls allowed
456             } else {
457                 if (!in_array((string)$value, $column->enums)) {
458                     throw new dml_write_exception('Enum value '.s($value).' not allowed in field '.$field.' table '.$table.'.');
459                 }
460             }
461         }
462         return $value;
463     }
465     /**
466      * Is db in unicode mode?
467      * @return bool
468      */
469     public function setup_is_unicodedb() {
470         $sql = "SHOW LOCAL VARIABLES LIKE 'character_set_database'";
471         $this->query_start($sql, null, SQL_QUERY_AUX);
472         $result = $this->mysqli->query($sql);
473         $this->query_end($result);
475         if ($result) {
476             $result->close();
477             return true;
478         }
479         return false;
480     }
482     /**
483      * Do NOT use in code, to be used by database_manager only!
484      * @param string $sql query
485      * @return bool true
486      * @throws dml_exception if error
487      */
488     public function change_database_structure($sql) {
489         $this->reset_caches();
491         $this->query_start($sql, null, SQL_QUERY_STRUCTURE);
492         $result = $this->mysqli->query($sql);
493         $this->query_end($result);
495         return true;
496     }
498     /**
499      * Very ugly hack which emulates bound parameters in queries
500      * because prepared statements do not use query cache.
501      */
502     protected function emulate_bound_params($sql, array $params=null) {
503         if (empty($params)) {
504             return $sql;
505         }
506         /// ok, we have verified sql statement with ? and correct number of params
507         $return = strtok($sql, '?');
508         foreach ($params as $param) {
509             if (is_bool($param)) {
510                 $return .= (int)$param;
511             } else if (is_null($param)) {
512                 $return .= 'NULL';
513             } else if (is_number($param)) { // we can not use is_numeric() because it eats leading zeros from strings like 0045646
514                 $return .= $param;
515             } else if (is_float($param)) {
516                 $return .= $param;
517             } else {
518                 $param = $this->mysqli->real_escape_string($param);
519                 $return .= "'$param'";
520             }
521             $return .= strtok('?');
522         }
523         return $return;
524     }
526     /**
527      * Execute general sql query. Should be used only when no other method suitable.
528      * Do NOT use this to make changes in db structure, use database_manager::execute_sql() instead!
529      * @param string $sql query
530      * @param array $params query parameters
531      * @return bool true
532      * @throws dml_exception if error
533      */
534     public function execute($sql, array $params=null) {
535         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
537         if (strpos($sql, ';') !== false) {
538             throw new coding_exception('moodle_database::execute() Multiple sql statements found or bound parameters not used properly in query!');
539         }
541         $rawsql = $this->emulate_bound_params($sql, $params);
543         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
544         $result = $this->mysqli->query($rawsql);
545         $this->query_end($result);
547         if ($result === true) {
548             return true;
550         } else {
551             $result->close();
552             return true;
553         }
554     }
556     /**
557      * Get a number of records as a moodle_recordset using a SQL statement.
558      *
559      * Since this method is a little less readable, use of it should be restricted to
560      * code where it's possible there might be large datasets being returned.  For known
561      * small datasets use get_records_sql - it leads to simpler code.
562      *
563      * The return type is as for @see function get_recordset.
564      *
565      * @param string $sql the SQL select query to execute.
566      * @param array $params array of sql parameters
567      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
568      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
569      * @return mixed an moodle_recordset object
570      * @throws dml_exception if error
571      */
572     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
573         $limitfrom = (int)$limitfrom;
574         $limitnum  = (int)$limitnum;
575         $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
576         $limitnum  = ($limitnum < 0)  ? 0 : $limitnum;
578         if ($limitfrom or $limitnum) {
579             if ($limitnum < 1) {
580                 $limitnum = "18446744073709551615";
581             }
582             $sql .= " LIMIT $limitfrom, $limitnum";
583         }
585         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
586         $rawsql = $this->emulate_bound_params($sql, $params);
588         $this->query_start($sql, $params, SQL_QUERY_SELECT);
589         // no MYSQLI_USE_RESULT here, it would block write ops on affected tables
590         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
591         $this->query_end($result);
593         return $this->create_recordset($result);
594     }
596     protected function create_recordset($result) {
597         return new mysqli_native_moodle_recordset($result);
598     }
600     /**
601      * Get a number of records as an array of objects using a SQL statement.
602      *
603      * Return value as for @see function get_records.
604      *
605      * @param string $sql the SQL select query to execute. The first column of this SELECT statement
606      *   must be a unique value (usually the 'id' field), as it will be used as the key of the
607      *   returned array.
608      * @param array $params array of sql parameters
609      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
610      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
611      * @return mixed an array of objects, or empty array if no records were found
612      * @throws dml_exception if error
613      */
614     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
615         $limitfrom = (int)$limitfrom;
616         $limitnum  = (int)$limitnum;
617         $limitfrom = ($limitfrom < 0) ? 0 : $limitfrom;
618         $limitnum  = ($limitnum < 0)  ? 0 : $limitnum;
620         if ($limitfrom or $limitnum) {
621             if ($limitnum < 1) {
622                 $limitnum = "18446744073709551615";
623             }
624             $sql .= " LIMIT $limitfrom, $limitnum";
625         }
627         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
628         $rawsql = $this->emulate_bound_params($sql, $params);
630         $this->query_start($sql, $params, SQL_QUERY_SELECT);
631         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
632         $this->query_end($result);
634         $return = array();
636         while($row = $result->fetch_assoc()) {
637             $row = array_change_key_case($row, CASE_LOWER);
638             $id  = reset($row);
639             if (isset($return[$id])) {
640                 $colname = key($row);
641                 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);
642             }
643             $return[$id] = (object)$row;
644         }
645         $result->close();
647         return $return;
648     }
650     /**
651      * Selects records and return values (first field) as an array using a SQL statement.
652      *
653      * @param string $sql The SQL query
654      * @param array $params array of sql parameters
655      * @return mixed array of values
656      * @throws dml_exception if error
657      */
658     public function get_fieldset_sql($sql, array $params=null) {
659         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
660         $rawsql = $this->emulate_bound_params($sql, $params);
662         $this->query_start($sql, $params, SQL_QUERY_SELECT);
663         $result = $this->mysqli->query($rawsql, MYSQLI_STORE_RESULT);
664         $this->query_end($result);
666         $return = array();
668         while($row = $result->fetch_assoc()) {
669             $return[] = reset($row);
670         }
671         $result->close();
673         return $return;
674     }
676     /**
677      * Insert new record into database, as fast as possible, no safety checks, lobs not supported.
678      * @param string $table name
679      * @param mixed $params data record as object or array
680      * @param bool $returnit return it of inserted record
681      * @param bool $bulk true means repeated inserts expected
682      * @param bool $customsequence true if 'id' included in $params, disables $returnid
683      * @return true or new id
684      * @throws dml_exception if error
685      */
686     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
687         if (!is_array($params)) {
688             $params = (array)$params;
689         }
691         if ($customsequence) {
692             if (!isset($params['id'])) {
693                 throw new coding_exception('moodle_database::insert_record_raw() id field must be specified if custom sequences used.');
694             }
695             $returnid = false;
696         } else {
697             unset($params['id']);
698         }
700         if (empty($params)) {
701             throw new coding_exception('moodle_database::insert_record_raw() no fields found.');
702         }
704         $fields = implode(',', array_keys($params));
705         $qms    = array_fill(0, count($params), '?');
706         $qms    = implode(',', $qms);
708         $sql = "INSERT INTO {$this->prefix}$table ($fields) VALUES($qms)";
710         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
711         $rawsql = $this->emulate_bound_params($sql, $params);
713         $this->query_start($sql, $params, SQL_QUERY_INSERT);
714         $result = $this->mysqli->query($rawsql);
715         $id = @$this->mysqli->insert_id; // must be called before query_end() which may insert log into db
716         $this->query_end($result);
718         if (!$id) {
719             throw new dml_write_exception('unknown error fetching inserted id');
720         }
722         if (!$returnid) {
723             return true;
724         } else {
725             return (int)$id;
726         }
727     }
729     /**
730      * Insert a record into a table and return the "id" field if required.
731      *
732      * Some conversions and safety checks are carried out. Lobs are supported.
733      * If the return ID isn't required, then this just reports success as true/false.
734      * $data is an object containing needed data
735      * @param string $table The database table to be inserted into
736      * @param object $data A data object with values for one or more fields in the record
737      * @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.
738      * @return true or new id
739      * @throws dml_exception if error
740      */
741     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
742         if (!is_object($dataobject)) {
743             $dataobject = (object)$dataobject;
744         }
746         $columns = $this->get_columns($table);
748         unset($dataobject->id);
749         $cleaned = array();
751         foreach ($dataobject as $field=>$value) {
752             if (!isset($columns[$field])) {
753                 continue;
754             }
755             $column = $columns[$field];
756             $cleaned[$field] = $this->normalise_value($column, $value);
757         }
759         return $this->insert_record_raw($table, $cleaned, $returnid, $bulk);
760     }
762     /**
763      * Import a record into a table, id field is required.
764      * Safety checks are NOT carried out. Lobs are supported.
765      *
766      * @param string $table name of database table to be inserted into
767      * @param object $dataobject A data object with values for one or more fields in the record
768      * @return bool true
769      * @throws dml_exception if error
770      */
771     public function import_record($table, $dataobject) {
772         $dataobject = (object)$dataobject;
774         $columns = $this->get_columns($table);
775         $cleaned = array();
777         foreach ($dataobject as $field=>$value) {
778             if (!isset($columns[$field])) {
779                 continue;
780             }
781             $cleaned[$field] = $value;
782         }
784         return $this->insert_record_raw($table, $cleaned, false, true, true);
785     }
787     /**
788      * Update record in database, as fast as possible, no safety checks, lobs not supported.
789      * @param string $table name
790      * @param mixed $params data record as object or array
791      * @param bool true means repeated updates expected
792      * @return bool true
793      * @throws dml_exception if error
794      */
795     public function update_record_raw($table, $params, $bulk=false) {
796         if (!is_array($params)) {
797             $params = (array)$params;
798         }
799         if (!isset($params['id'])) {
800             throw new coding_exception('moodle_database::update_record_raw() id field must be specified.');
801         }
802         $id = $params['id'];
803         unset($params['id']);
805         if (empty($params)) {
806             throw new coding_exception('moodle_database::update_record_raw() no fields found.');
807         }
809         $sets = array();
810         foreach ($params as $field=>$value) {
811             $sets[] = "$field = ?";
812         }
814         $params[] = $id; // last ? in WHERE condition
816         $sets = implode(',', $sets);
817         $sql = "UPDATE {$this->prefix}$table SET $sets WHERE id=?";
819         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
820         $rawsql = $this->emulate_bound_params($sql, $params);
822         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
823         $result = $this->mysqli->query($rawsql);
824         $this->query_end($result);
826         return true;
827     }
829     /**
830      * Update a record in a table
831      *
832      * $dataobject is an object containing needed data
833      * Relies on $dataobject having a variable "id" to
834      * specify the record to update
835      *
836      * @param string $table The database table to be checked against.
837      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
838      * @param bool true means repeated updates expected
839      * @return bool true
840      * @throws dml_exception if error
841      */
842     public function update_record($table, $dataobject, $bulk=false) {
843         if (!is_object($dataobject)) {
844             $dataobject = (object)$dataobject;
845         }
847         $columns = $this->get_columns($table);
848         $cleaned = array();
850         foreach ($dataobject as $field=>$value) {
851             if (!isset($columns[$field])) {
852                 continue;
853             }
854             $column = $columns[$field];
855             $cleaned[$field] = $this->normalise_value($column, $value);
856         }
858         return $this->update_record_raw($table, $cleaned, $bulk);
859     }
861     /**
862      * Set a single field in every table record which match a particular WHERE clause.
863      *
864      * @param string $table The database table to be checked against.
865      * @param string $newfield the field to set.
866      * @param string $newvalue the value to set the field to.
867      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
868      * @param array $params array of sql parameters
869      * @return bool true
870      * @throws dml_exception if error
871      */
872     public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
873         if ($select) {
874             $select = "WHERE $select";
875         }
876         if (is_null($params)) {
877             $params = array();
878         }
879         list($select, $params, $type) = $this->fix_sql_params($select, $params);
881         // Get column metadata
882         $columns = $this->get_columns($table);
883         $column = $columns[$newfield];
885         $normalised_value = $this->normalise_value($column, $newvalue);
887         if (is_null($normalised_value)) {
888             $newfield = "$newfield = NULL";
889         } else {
890             $newfield = "$newfield = ?";
891             array_unshift($params, $normalised_value);
892         }
893         $sql = "UPDATE {$this->prefix}$table SET $newfield $select";
894         $rawsql = $this->emulate_bound_params($sql, $params);
896         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
897         $result = $this->mysqli->query($rawsql);
898         $this->query_end($result);
900         return true;
901     }
903     /**
904      * Delete one or more records from a table which match a particular WHERE clause.
905      *
906      * @param string $table The database table to be checked against.
907      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
908      * @param array $params array of sql parameters
909      * @return bool true
910      * @throws dml_exception if error
911      */
912     public function delete_records_select($table, $select, array $params=null) {
913         if ($select) {
914             $select = "WHERE $select";
915         }
916         $sql = "DELETE FROM {$this->prefix}$table $select";
918         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
919         $rawsql = $this->emulate_bound_params($sql, $params);
921         $this->query_start($sql, $params, SQL_QUERY_UPDATE);
922         $result = $this->mysqli->query($rawsql);
923         $this->query_end($result);
925         return true;
926     }
928     public function sql_cast_char2int($fieldname, $text=false) {
929         return ' CAST(' . $fieldname . ' AS SIGNED) ';
930     }
932     public function sql_concat() {
933         $arr = func_get_args();
934         $s = implode(', ', $arr);
935         if ($s === '') {
936             return "''";
937         }
938         return "CONCAT($s)";
939     }
941     public function sql_concat_join($separator="' '", $elements=array()) {
942         $s = implode(', ', $elements);
944         if ($s === '') {
945             return "''";
946         }
947         return "CONCAT_WS($separator, $s)";
948     }
950     /**
951      * Returns the SQL text to be used to calculate the length in characters of one expression.
952      * @param string fieldname or expression to calculate its length in characters.
953      * @return string the piece of SQL code to be used in the statement.
954      */
955     public function sql_length($fieldname) {
956         return ' CHAR_LENGTH(' . $fieldname . ')';
957     }
959     /**
960      * Does this driver support regex syntax when searching
961      */
962     public function sql_regex_supported() {
963         return true;
964     }
966     /**
967      * Return regex positive or negative match sql
968      * @param bool $positivematch
969      * @return string or empty if not supported
970      */
971     public function sql_regex($positivematch=true) {
972         return $positivematch ? 'REGEXP' : 'NOT REGEXP';
973     }
975     public function sql_cast_2signed($fieldname) {
976         return ' CAST(' . $fieldname . ' AS SIGNED) ';
977     }
979 /// session locking
980     public function session_lock_supported() {
981         return true;
982     }
984     public function get_session_lock($rowid) {
985         parent::get_session_lock($rowid);
986         $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
987         $sql = "SELECT GET_LOCK('$fullname',120)";
988         $this->query_start($sql, null, SQL_QUERY_AUX);
989         $result = $this->mysqli->query($sql);
990         $this->query_end($result);
992         if ($result) {
993             $arr = $result->fetch_assoc();
994             $result->close();
996             if (reset($arr) == 1) {
997                 return;
998             } else {
999                 // try again!
1000                 $this->get_session_lock($rowid);
1001             }
1002         }
1003     }
1005     public function release_session_lock($rowid) {
1006         parent::release_session_lock($rowid);
1007         $fullname = $this->dbname.'-'.$this->prefix.'-session-'.$rowid;
1008         $sql = "SELECT RELEASE_LOCK('$fullname')";
1009         $this->query_start($sql, null, SQL_QUERY_AUX);
1010         $result = $this->mysqli->query($sql);
1011         $this->query_end($result);
1013         if ($result) {
1014             $result->close();
1015         }
1016     }
1018 /// transactions
1019     /**
1020      * Are transactions supported?
1021      * It is not responsible to run productions servers
1022      * on databases without transaction support ;-)
1023      *
1024      * MyISAM does not support support transactions.
1025      *
1026      * @return bool
1027      */
1028     protected function transactions_supported() {
1029         if (!is_null($this->transactions_supported)) {
1030             return $this->transactions_supported;
1031         }
1033         // Only will accept transactions if using InnoDB storage engine (more engines can be added easily BDB, Falcon...)
1034         $this->transactions_supported = false;
1036         $sql = "SELECT @@storage_engine";
1037         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1038         $result = $this->mysqli->query($sql);
1039         $this->query_end($result);
1041         if ($rec = $result->fetch_assoc()) {
1042             if (in_array($rec['@@storage_engine'], array('InnoDB'))) {
1043                 $this->transactions_supported = true;
1044             }
1045         }
1046         $result->close();
1048         return $this->transactions_supported;
1049     }
1051     /**
1052      * Driver specific start of real database transaction,
1053      * this can not be used directly in code.
1054      * @return void
1055      */
1056     protected function begin_transaction() {
1057         if (!$this->transactions_supported()) {
1058             return;
1059         }
1061         $sql = "SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED";
1062         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1063         $result = $this->mysqli->query($sql);
1064         $this->query_end($result);
1066         $sql = "START TRANSACTION";
1067         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1068         $result = $this->mysqli->query($sql);
1069         $this->query_end($result);
1070     }
1072     /**
1073      * Driver specific commit of real database transaction,
1074      * this can not be used directly in code.
1075      * @return void
1076      */
1077     protected function commit_transaction() {
1078         if (!$this->transactions_supported()) {
1079             return;
1080         }
1082         $sql = "COMMIT";
1083         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1084         $result = $this->mysqli->query($sql);
1085         $this->query_end($result);
1086     }
1088     /**
1089      * Driver specific abort of real database transaction,
1090      * this can not be used directly in code.
1091      * @return void
1092      */
1093     protected function rollback_transaction() {
1094         if (!$this->transactions_supported()) {
1095             return;
1096         }
1098         $sql = "ROLLBACK";
1099         $this->query_start($sql, NULL, SQL_QUERY_AUX);
1100         $result = $this->mysqli->query($sql);
1101         $this->query_end($result);
1103         return true;
1104     }