JGviR10p

1<?php
2
3/**
4 * @file
5 * Core systems for the database layer.
6 *
7 * Classes required for basic functioning of the database system should be
8 * placed in this file.  All utility functions should also be placed in this
9 * file only, as they cannot auto-load the way classes can.
10 */
11
12/**
13 * @defgroup database Database abstraction layer
14 * @{
15 * Allow the use of different database servers using the same code base.
16 *
17 * Drupal provides a database abstraction layer to provide developers with
18 * the ability to support multiple database servers easily. The intent of
19 * this layer is to preserve the syntax and power of SQL as much as possible,
20 * but also allow developers a way to leverage more complex functionality in
21 * a unified way. It also provides a structured interface for dynamically
22 * constructing queries when appropriate, and enforcing security checks and
23 * similar good practices.
24 *
25 * The system is built atop PHP's PDO (PHP Data Objects) database API and
26 * inherits much of its syntax and semantics.
27 *
28 * Most Drupal database SELECT queries are performed by a call to db_query() or
29 * db_query_range(). Module authors should also consider using the PagerDefault
30 * Extender for queries that return results that need to be presented on
31 * multiple pages, and the Tablesort Extender for generating appropriate queries
32 * for sortable tables.
33 *
34 * For example, one might wish to return a list of the most recent 10 nodes
35 * authored by a given user. Instead of directly issuing the SQL query
36 * @code
37 * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;
38 * @endcode
39 * one would instead call the Drupal functions:
40 * @code
41 * $result = db_query_range('SELECT n.nid, n.title, n.created
42 *   FROM {node} n WHERE n.uid = :uid', 0, 10, array(':uid' => $uid));
43 * foreach ($result as $record) {
44 *   // Perform operations on $record->title, etc. here.
45 * }
46 * @endcode
47 * Curly braces are used around "node" to provide table prefixing via
48 * DatabaseConnection::prefixTables(). The explicit use of a user ID is pulled
49 * out into an argument passed to db_query() so that SQL injection attacks
50 * from user input can be caught and nullified. The LIMIT syntax varies between
51 * database servers, so that is abstracted into db_query_range() arguments.
52 * Finally, note the PDO-based ability to iterate over the result set using
53 * foreach ().
54 *
55 * All queries are passed as a prepared statement string. A
56 * prepared statement is a "template" of a query that omits literal or variable
57 * values in favor of placeholders. The values to place into those
58 * placeholders are passed separately, and the database driver handles
59 * inserting the values into the query in a secure fashion. That means you
60 * should never quote or string-escape a value to be inserted into the query.
61 *
62 * There are two formats for placeholders: named and unnamed. Named placeholders
63 * are strongly preferred in all cases as they are more flexible and
64 * self-documenting. Named placeholders should start with a colon ":" and can be
65 * followed by one or more letters, numbers or underscores.
66 *
67 * Named placeholders begin with a colon followed by a unique string. Example:
68 * @code
69 * SELECT nid, title FROM {node} WHERE uid=:uid;
70 * @endcode
71 *
72 * ":uid" is a placeholder that will be replaced with a literal value when
73 * the query is executed. A given placeholder label cannot be repeated in a
74 * given query, even if the value should be the same. When using named
75 * placeholders, the array of arguments to the query must be an associative
76 * array where keys are a placeholder label (e.g., :uid) and the value is the
77 * corresponding value to use. The array may be in any order.
78 *
79 * Unnamed placeholders are simply a question mark. Example:
80 * @code
81 * SELECT nid, title FROM {node} WHERE uid=?;
82 * @endcode
83 *
84 * In this case, the array of arguments must be an indexed array of values to
85 * use in the exact same order as the placeholders in the query.
86 *
87 * Note that placeholders should be a "complete" value. For example, when
88 * running a LIKE query the SQL wildcard character, %, should be part of the
89 * value, not the query itself. Thus, the following is incorrect:
90 * @code
91 * SELECT nid, title FROM {node} WHERE title LIKE :title%;
92 * @endcode
93 * It should instead read:
94 * @code
95 * SELECT nid, title FROM {node} WHERE title LIKE :title;
96 * @endcode
97 * and the value for :title should include a % as appropriate. Again, note the
98 * lack of quotation marks around :title. Because the value is not inserted
99 * into the query as one big string but as an explicitly separate value, the
100 * database server knows where the query ends and a value begins. That is
101 * considerably more secure against SQL injection than trying to remember
102 * which values need quotation marks and string escaping and which don't.
103 *
104 * INSERT, UPDATE, and DELETE queries need special care in order to behave
105 * consistently across all different databases. Therefore, they use a special
106 * object-oriented API for defining a query structurally. For example, rather
107 * than:
108 * @code
109 * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');
110 * @endcode
111 * one would instead write:
112 * @code
113 * $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');
114 * db_insert('node')->fields($fields)->execute();
115 * @endcode
116 * This method allows databases that need special data type handling to do so,
117 * while also allowing optimizations such as multi-insert queries. UPDATE and
118 * DELETE queries have a similar pattern.
119 *
120 * Drupal also supports transactions, including a transparent fallback for
121 * databases that do not support transactions. To start a new transaction,
122 * simply call $txn = db_transaction(); in your own code. The transaction will
123 * remain open for as long as the variable $txn remains in scope.  When $txn is
124 * destroyed, the transaction will be committed.  If your transaction is nested
125 * inside of another then Drupal will track each transaction and only commit
126 * the outer-most transaction when the last transaction object goes out out of
127 * scope, that is, all relevant queries completed successfully.
128 *
129 * Example:
130 * @code
131 * function my_transaction_function() {
132 *   // The transaction opens here.
133 *   $txn = db_transaction();
134 *
135 *   try {
136 *     $id = db_insert('example')
137 *       ->fields(array(
138 *         'field1' => 'mystring',
139 *         'field2' => 5,
140 *       ))
141 *       ->execute();
142 *
143 *     my_other_function($id);
144 *
145 *     return $id;
146 *   }
147 *   catch (Exception $e) {
148 *     // Something went wrong somewhere, so roll back now.
149 *     $txn->rollback();
150 *     // Log the exception to watchdog.
151 *     watchdog_exception('type', $e);
152 *   }
153 *
154 *   // $txn goes out of scope here.  Unless the transaction was rolled back, it
155 *   // gets automatically committed here.
156 * }
157 *
158 * function my_other_function($id) {
159 *   // The transaction is still open here.
160 *
161 *   if ($id % 2 == 0) {
162 *     db_update('example')
163 *       ->condition('id', $id)
164 *       ->fields(array('field2' => 10))
165 *       ->execute();
166 *   }
167 * }
168 * @endcode
169 *
170 * @see http://drupal.org/developing/api/database
171 */
172
173
174/**
175 * Base Database API class.
176 *
177 * This class provides a Drupal-specific extension of the PDO database
178 * abstraction class in PHP. Every database driver implementation must provide a
179 * concrete implementation of it to support special handling required by that
180 * database.
181 *
182 * @see http://php.net/manual/en/book.pdo.php
183 */
184abstract class DatabaseConnection extends PDO {
185
186  /**
187   * The database target this connection is for.
188   *
189   * We need this information for later auditing and logging.
190   *
191   * @var string
192   */
193  protected $target = NULL;
194
195  /**
196   * The key representing this connection.
197   *
198   * The key is a unique string which identifies a database connection. A
199   * connection can be a single server or a cluster of master and slaves (use
200   * target to pick between master and slave).
201   *
202   * @var string
203   */
204  protected $key = NULL;
205
206  /**
207   * The current database logging object for this connection.
208   *
209   * @var DatabaseLog
210   */
211  protected $logger = NULL;
212
213  /**
214   * Tracks the number of "layers" of transactions currently active.
215   *
216   * On many databases transactions cannot nest.  Instead, we track
217   * nested calls to transactions and collapse them into a single
218   * transaction.
219   *
220   * @var array
221   */
222  protected $transactionLayers = array();
223
224  /**
225   * Index of what driver-specific class to use for various operations.
226   *
227   * @var array
228   */
229  protected $driverClasses = array();
230
231  /**
232   * The name of the Statement class for this connection.
233   *
234   * @var string
235   */
236  protected $statementClass = 'DatabaseStatementBase';
237
238  /**
239   * Whether this database connection supports transactions.
240   *
241   * @var bool
242   */
243  protected $transactionSupport = TRUE;
244
245  /**
246   * Whether this database connection supports transactional DDL.
247   *
248   * Set to FALSE by default because few databases support this feature.
249   *
250   * @var bool
251   */
252  protected $transactionalDDLSupport = FALSE;
253
254  /**
255   * An index used to generate unique temporary table names.
256   *
257   * @var integer
258   */
259  protected $temporaryNameIndex = 0;
260
261  /**
262   * The connection information for this connection object.
263   *
264   * @var array
265   */
266  protected $connectionOptions = array();
267
268  /**
269   * The schema object for this connection.
270   *
271   * @var object
272   */
273  protected $schema = NULL;
274
275  /**
276   * The prefixes used by this database connection.
277   *
278   * @var array
279   */
280  protected $prefixes = array();
281
282  /**
283   * List of search values for use in prefixTables().
284   *
285   * @var array
286   */
287  protected $prefixSearch = array();
288
289  /**
290   * List of replacement values for use in prefixTables().
291   *
292   * @var array
293   */
294  protected $prefixReplace = array();
295
296  function __construct($dsn, $username, $password, $driver_options = array()) {
297    // Initialize and prepare the connection prefix.
298    $this->setPrefix(isset($this->connectionOptions['prefix']) ? $this->connectionOptions['prefix'] : '');
299
300    // Because the other methods don't seem to work right.
301    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;
302
303    // Call PDO::__construct and PDO::setAttribute.
304    parent::__construct($dsn, $username, $password, $driver_options);
305
306    // Set a Statement class, unless the driver opted out.
307    if (!empty($this->statementClass)) {
308      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));
309    }
310  }
311
312  /**
313   * Destroys this Connection object.
314   *
315   * PHP does not destruct an object if it is still referenced in other
316   * variables. In case of PDO database connection objects, PHP only closes the
317   * connection when the PDO object is destructed, so any references to this
318   * object may cause the number of maximum allowed connections to be exceeded.
319   */
320  public function destroy() {
321    // Destroy all references to this connection by setting them to NULL.
322    // The Statement class attribute only accepts a new value that presents a
323    // proper callable, so we reset it to PDOStatement.
324    $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));
325    $this->schema = NULL;
326  }
327
328  /**
329   * Returns the default query options for any given query.
330   *
331   * A given query can be customized with a number of option flags in an
332   * associative array:
333   * - target: The database "target" against which to execute a query. Valid
334   *   values are "default" or "slave". The system will first try to open a
335   *   connection to a database specified with the user-supplied key. If one
336   *   is not available, it will silently fall back to the "default" target.
337   *   If multiple databases connections are specified with the same target,
338   *   one will be selected at random for the duration of the request.
339   * - fetch: This element controls how rows from a result set will be
340   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,
341   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a
342   *   class. If a string is specified, each record will be fetched into a new
343   *   object of that class. The behavior of all other values is defined by PDO.
344   *   See http://php.net/manual/pdostatement.fetch.php
345   * - return: Depending on the type of query, different return values may be
346   *   meaningful. This directive instructs the system which type of return
347   *   value is desired. The system will generally set the correct value
348   *   automatically, so it is extremely rare that a module developer will ever
349   *   need to specify this value. Setting it incorrectly will likely lead to
350   *   unpredictable results or fatal errors. Legal values include:
351   *   - Database::RETURN_STATEMENT: Return the prepared statement object for
352   *     the query. This is usually only meaningful for SELECT queries, where
353   *     the statement object is how one accesses the result set returned by the
354   *     query.
355   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an
356   *     UPDATE or DELETE query. Be aware that means the number of rows actually
357   *     changed, not the number of rows matched by the WHERE clause.
358   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)
359   *     created by an INSERT statement on a table that contains a serial
360   *     column.
361   *   - Database::RETURN_NULL: Do not return anything, as there is no
362   *     meaningful value to return. That is the case for INSERT queries on
363   *     tables that do not contain a serial column.
364   * - throw_exception: By default, the database system will catch any errors
365   *   on a query as an Exception, log it, and then rethrow it so that code
366   *   further up the call chain can take an appropriate action. To suppress
367   *   that behavior and simply return NULL on failure, set this option to
368   *   FALSE.
369   *
370   * @return
371   *   An array of default query options.
372   */
373  protected function defaultOptions() {
374    return array(
375      'target' => 'default',
376      'fetch' => PDO::FETCH_OBJ,
377      'return' => Database::RETURN_STATEMENT,
378      'throw_exception' => TRUE,
379    );
380  }
381
382  /**
383   * Returns the connection information for this connection object.
384   *
385   * Note that Database::getConnectionInfo() is for requesting information
386   * about an arbitrary database connection that is defined. This method
387   * is for requesting the connection information of this specific
388   * open connection object.
389   *
390   * @return
391   *   An array of the connection information. The exact list of
392   *   properties is driver-dependent.
393   */
394  public function getConnectionOptions() {
395    return $this->connectionOptions;
396  }
397
398  /**
399   * Set the list of prefixes used by this database connection.
400   *
401   * @param $prefix
402   *   The prefixes, in any of the multiple forms documented in
403   *   default.settings.php.
404   */
405  protected function setPrefix($prefix) {
406    if (is_array($prefix)) {
407      $this->prefixes = $prefix + array('default' => '');
408    }
409    else {
410      $this->prefixes = array('default' => $prefix);
411    }
412
413    // Set up variables for use in prefixTables(). Replace table-specific
414    // prefixes first.
415    $this->prefixSearch = array();
416    $this->prefixReplace = array();
417    foreach ($this->prefixes as $key => $val) {
418      if ($key != 'default') {
419        $this->prefixSearch[] = '{' . $key . '}';
420        $this->prefixReplace[] = $val . $key;
421      }
422    }
423    // Then replace remaining tables with the default prefix.
424    $this->prefixSearch[] = '{';
425    $this->prefixReplace[] = $this->prefixes['default'];
426    $this->prefixSearch[] = '}';
427    $this->prefixReplace[] = '';
428  }
429
430  /**
431   * Appends a database prefix to all tables in a query.
432   *
433   * Queries sent to Drupal should wrap all table names in curly brackets. This
434   * function searches for this syntax and adds Drupal's table prefix to all
435   * tables, allowing Drupal to coexist with other systems in the same database
436   * and/or schema if necessary.
437   *
438   * @param $sql
439   *   A string containing a partial or entire SQL query.
440   *
441   * @return
442   *   The properly-prefixed string.
443   */
444  public function prefixTables($sql) {
445    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);
446  }
447
448  /**
449   * Find the prefix for a table.
450   *
451   * This function is for when you want to know the prefix of a table. This
452   * is not used in prefixTables due to performance reasons.
453   */
454  public function tablePrefix($table = 'default') {
455    if (isset($this->prefixes[$table])) {
456      return $this->prefixes[$table];
457    }
458    else {
459      return $this->prefixes['default'];
460    }
461  }
462
463  /**
464   * Prepares a query string and returns the prepared statement.
465   *
466   * This method caches prepared statements, reusing them when
467   * possible. It also prefixes tables names enclosed in curly-braces.
468   *
469   * @param $query
470   *   The query string as SQL, with curly-braces surrounding the
471   *   table names.
472   *
473   * @return DatabaseStatementInterface
474   *   A PDO prepared statement ready for its execute() method.
475   */
476  public function prepareQuery($query) {
477    $query = $this->prefixTables($query);
478
479    // Call PDO::prepare.
480    return parent::prepare($query);
481  }
482
483  /**
484   * Tells this connection object what its target value is.
485   *
486   * This is needed for logging and auditing. It's sloppy to do in the
487   * constructor because the constructor for child classes has a different
488   * signature. We therefore also ensure that this function is only ever
489   * called once.
490   *
491   * @param $target
492   *   The target this connection is for. Set to NULL (default) to disable
493   *   logging entirely.
494   */
495  public function setTarget($target = NULL) {
496    if (!isset($this->target)) {
497      $this->target = $target;
498    }
499  }
500
501  /**
502   * Returns the target this connection is associated with.
503   *
504   * @return
505   *   The target string of this connection.
506   */
507  public function getTarget() {
508    return $this->target;
509  }
510
511  /**
512   * Tells this connection object what its key is.
513   *
514   * @param $target
515   *   The key this connection is for.
516   */
517  public function setKey($key) {
518    if (!isset($this->key)) {
519      $this->key = $key;
520    }
521  }
522
523  /**
524   * Returns the key this connection is associated with.
525   *
526   * @return
527   *   The key of this connection.
528   */
529  public function getKey() {
530    return $this->key;
531  }
532
533  /**
534   * Associates a logging object with this connection.
535   *
536   * @param $logger
537   *   The logging object we want to use.
538   */
539  public function setLogger(DatabaseLog $logger) {
540    $this->logger = $logger;
541  }
542
543  /**
544   * Gets the current logging object for this connection.
545   *
546   * @return DatabaseLog
547   *   The current logging object for this connection. If there isn't one,
548   *   NULL is returned.
549   */
550  public function getLogger() {
551    return $this->logger;
552  }
553
554  /**
555   * Creates the appropriate sequence name for a given table and serial field.
556   *
557   * This information is exposed to all database drivers, although it is only
558   * useful on some of them. This method is table prefix-aware.
559   *
560   * @param $table
561   *   The table name to use for the sequence.
562   * @param $field
563   *   The field name to use for the sequence.
564   *
565   * @return
566   *   A table prefix-parsed string for the sequence name.
567   */
568  public function makeSequenceName($table, $field) {
569    return $this->prefixTables('{' . $table . '}_' . $field . '_seq');
570  }
571
572  /**
573   * Flatten an array of query comments into a single comment string.
574   *
575   * The comment string will be sanitized to avoid SQL injection attacks.
576   *
577   * @param $comments
578   *   An array of query comment strings.
579   *
580   * @return
581   *   A sanitized comment string.
582   */
583  public function makeComment($comments) {
584    if (empty($comments))
585      return '';
586
587    // Flatten the array of comments.
588    $comment = implode('; ', $comments);
589
590    // Sanitize the comment string so as to avoid SQL injection attacks.
591    return '/* ' . $this->filterComment($comment) . ' */ ';
592  }
593
594  /**
595   * Sanitize a query comment string.
596   *
597   * Ensure a query comment does not include strings such as "* /" that might
598   * terminate the comment early. This avoids SQL injection attacks via the
599   * query comment. The comment strings in this example are separated by a
600   * space to avoid PHP parse errors.
601   *
602   * For example, the comment:
603   * @code
604   * db_update('example')
605   *  ->condition('id', $id)
606   *  ->fields(array('field2' => 10))
607   *  ->comment('Exploit * / DROP TABLE node; --')
608   *  ->execute()
609   * @endcode
610   *
611   * Would result in the following SQL statement being generated:
612   * @code
613   * "/ * Exploit * / DROP TABLE node; -- * / UPDATE example SET field2=..."
614   * @endcode
615   *
616   * Unless the comment is sanitised first, the SQL server would drop the
617   * node table and ignore the rest of the SQL statement.
618   *
619   * @param $comment
620   *   A query comment string.
621   *
622   * @return
623   *   A sanitized version of the query comment string.
624   */
625  protected function filterComment($comment = '') {
626    return preg_replace('/(\/\*\s*)|(\s*\*\/)/', '', $comment);
627  }
628
629  /**
630   * Executes a query string against the database.
631   *
632   * This method provides a central handler for the actual execution of every
633   * query. All queries executed by Drupal are executed as PDO prepared
634   * statements.
635   *
636   * @param $query
637   *   The query to execute. In most cases this will be a string containing
638   *   an SQL query with placeholders. An already-prepared instance of
639   *   DatabaseStatementInterface may also be passed in order to allow calling
640   *   code to manually bind variables to a query. If a
641   *   DatabaseStatementInterface is passed, the $args array will be ignored.
642   *   It is extremely rare that module code will need to pass a statement
643   *   object to this method. It is used primarily for database drivers for
644   *   databases that require special LOB field handling.
645   * @param $args
646   *   An array of arguments for the prepared statement. If the prepared
647   *   statement uses ? placeholders, this array must be an indexed array.
648   *   If it contains named placeholders, it must be an associative array.
649   * @param $options
650   *   An associative array of options to control how the query is run. See
651   *   the documentation for DatabaseConnection::defaultOptions() for details.
652   *
653   * @return DatabaseStatementInterface
654   *   This method will return one of: the executed statement, the number of
655   *   rows affected by the query (not the number matched), or the generated
656   *   insert IT of the last query, depending on the value of
657   *   $options['return']. Typically that value will be set by default or a
658   *   query builder and should not be set by a user. If there is an error,
659   *   this method will return NULL and may throw an exception if
660   *   $options['throw_exception'] is TRUE.
661   *
662   * @throws PDOException
663   */
664  public function query($query, array $args = array(), $options = array()) {
665
666    // Use default values if not already set.
667    $options += $this->defaultOptions();
668
669    try {
670      // We allow either a pre-bound statement object or a literal string.
671      // In either case, we want to end up with an executed statement object,
672      // which we pass to PDOStatement::execute.
673      if ($query instanceof DatabaseStatementInterface) {
674        $stmt = $query;
675        $stmt->execute(NULL, $options);
676      }
677      else {
678        $this->expandArguments($query, $args);
679        $stmt = $this->prepareQuery($query);
680        $stmt->execute($args, $options);
681      }
682
683      // Depending on the type of query we may need to return a different value.
684      // See DatabaseConnection::defaultOptions() for a description of each
685      // value.
686      switch ($options['return']) {
687        case Database::RETURN_STATEMENT:
688          return $stmt;
689        case Database::RETURN_AFFECTED:
690          return $stmt->rowCount();
691        case Database::RETURN_INSERT_ID:
692          return $this->lastInsertId();
693        case Database::RETURN_NULL:
694          return;
695        default:
696          throw new PDOException('Invalid return directive: ' . $options['return']);
697      }
698    }
699    catch (PDOException $e) {
700      if ($options['throw_exception']) {
701        // Add additional debug information.
702        if ($query instanceof DatabaseStatementInterface) {
703          $e->query_string = $stmt->getQueryString();
704        }
705        else {
706          $e->query_string = $query;
707        }
708        $e->args = $args;
709        throw $e;
710      }
711      return NULL;
712    }
713  }
714
715  /**
716   * Expands out shorthand placeholders.
717   *
718   * Drupal supports an alternate syntax for doing arrays of values. We
719   * therefore need to expand them out into a full, executable query string.
720   *
721   * @param $query
722   *   The query string to modify.
723   * @param $args
724   *   The arguments for the query.
725   *
726   * @return
727   *   TRUE if the query was modified, FALSE otherwise.
728   */
729  protected function expandArguments(&$query, &$args) {
730    $modified = FALSE;
731
732    // If the placeholder value to insert is an array, assume that we need
733    // to expand it out into a comma-delimited set of placeholders.
734    foreach (array_filter($args, 'is_array') as $key => $data) {
735      $new_keys = array();
736      foreach (array_values($data) as $i => $value) {
737        // This assumes that there are no other placeholders that use the same
738        // name.  For example, if the array placeholder is defined as :example
739        // and there is already an :example_2 placeholder, this will generate
740        // a duplicate key.  We do not account for that as the calling code
741        // is already broken if that happens.
742        $new_keys[$key . '_' . $i] = $value;
743      }
744
745      // Update the query with the new placeholders.
746      // preg_replace is necessary to ensure the replacement does not affect
747      // placeholders that start with the same exact text. For example, if the
748      // query contains the placeholders :foo and :foobar, and :foo has an
749      // array of values, using str_replace would affect both placeholders,
750      // but using the following preg_replace would only affect :foo because
751      // it is followed by a non-word character.
752      $query = preg_replace('#' . $key . '\b#', implode(', ', array_keys($new_keys)), $query);
753
754      // Update the args array with the new placeholders.
755      unset($args[$key]);
756      $args += $new_keys;
757
758      $modified = TRUE;
759    }
760
761    return $modified;
762  }
763
764  /**
765   * Gets the driver-specific override class if any for the specified class.
766   *
767   * @param string $class
768   *   The class for which we want the potentially driver-specific class.
769   * @param array $files
770   *   The name of the files in which the driver-specific class can be.
771   * @param $use_autoload
772   *   If TRUE, attempt to load classes using PHP's autoload capability
773   *   as well as the manual approach here.
774   * @return string
775   *   The name of the class that should be used for this driver.
776   */
777  public function getDriverClass($class, array $files = array(), $use_autoload = FALSE) {
778    if (empty($this->driverClasses[$class])) {
779      $driver = $this->driver();
780      $this->driverClasses[$class] = $class . '_' . $driver;
781      Database::loadDriverFile($driver, $files);
782      if (!class_exists($this->driverClasses[$class], $use_autoload)) {
783        $this->driverClasses[$class] = $class;
784      }
785    }
786    return $this->driverClasses[$class];
787  }
788
789  /**
790   * Prepares and returns a SELECT query object.
791   *
792   * @param $table
793   *   The base table for this query, that is, the first table in the FROM
794   *   clause. This table will also be used as the "base" table for query_alter
795   *   hook implementations.
796   * @param $alias
797   *   The alias of the base table of this query.
798   * @param $options
799   *   An array of options on the query.
800   *
801   * @return SelectQueryInterface
802   *   An appropriate SelectQuery object for this database connection. Note that
803   *   it may be a driver-specific subclass of SelectQuery, depending on the
804   *   driver.
805   *
806   * @see SelectQuery
807   */
808  public function select($table, $alias = NULL, array $options = array()) {
809    $class = $this->getDriverClass('SelectQuery', array('query.inc', 'select.inc'));
810    return new $class($table, $alias, $this, $options);
811  }
812
813  /**
814   * Prepares and returns an INSERT query object.
815   *
816   * @param $options
817   *   An array of options on the query.
818   *
819   * @return InsertQuery
820   *   A new InsertQuery object.
821   *
822   * @see InsertQuery
823   */
824  public function insert($table, array $options = array()) {
825    $class = $this->getDriverClass('InsertQuery', array('query.inc'));
826    return new $class($this, $table, $options);
827  }
828
829  /**
830   * Prepares and returns a MERGE query object.
831   *
832   * @param $options
833   *   An array of options on the query.
834   *
835   * @return MergeQuery
836   *   A new MergeQuery object.
837   *
838   * @see MergeQuery
839   */
840  public function merge($table, array $options = array()) {
841    $class = $this->getDriverClass('MergeQuery', array('query.inc'));
842    return new $class($this, $table, $options);
843  }
844
845
846  /**
847   * Prepares and returns an UPDATE query object.
848   *
849   * @param $options
850   *   An array of options on the query.
851   *
852   * @return UpdateQuery
853   *   A new UpdateQuery object.
854   *
855   * @see UpdateQuery
856   */
857  public function update($table, array $options = array()) {
858    $class = $this->getDriverClass('UpdateQuery', array('query.inc'));
859    return new $class($this, $table, $options);
860  }
861
862  /**
863   * Prepares and returns a DELETE query object.
864   *
865   * @param $options
866   *   An array of options on the query.
867   *
868   * @return DeleteQuery
869   *   A new DeleteQuery object.
870   *
871   * @see DeleteQuery
872   */
873  public function delete($table, array $options = array()) {
874    $class = $this->getDriverClass('DeleteQuery', array('query.inc'));
875    return new $class($this, $table, $options);
876  }
877
878  /**
879   * Prepares and returns a TRUNCATE query object.
880   *
881   * @param $options
882   *   An array of options on the query.
883   *
884   * @return TruncateQuery
885   *   A new TruncateQuery object.
886   *
887   * @see TruncateQuery
888   */
889  public function truncate($table, array $options = array()) {
890    $class = $this->getDriverClass('TruncateQuery', array('query.inc'));
891    return new $class($this, $table, $options);
892  }
893
894  /**
895   * Returns a DatabaseSchema object for manipulating the schema.
896   *
897   * This method will lazy-load the appropriate schema library file.
898   *
899   * @return DatabaseSchema
900   *   The DatabaseSchema object for this connection.
901   */
902  public function schema() {
903    if (empty($this->schema)) {
904      $class = $this->getDriverClass('DatabaseSchema', array('schema.inc'));
905      if (class_exists($class)) {
906        $this->schema = new $class($this);
907      }
908    }
909    return $this->schema;
910  }
911
912  /**
913   * Escapes a table name string.
914   *
915   * Force all table names to be strictly alphanumeric-plus-underscore.
916   * For some database drivers, it may also wrap the table name in
917   * database-specific escape characters.
918   *
919   * @return
920   *   The sanitized table name string.
921   */
922  public function escapeTable($table) {
923    return preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
924  }
925
926  /**
927   * Escapes a field name string.
928   *
929   * Force all field names to be strictly alphanumeric-plus-underscore.
930   * For some database drivers, it may also wrap the field name in
931   * database-specific escape characters.
932   *
933   * @return
934   *   The sanitized field name string.
935   */
936  public function escapeField($field) {
937    return preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
938  }
939
940  /**
941   * Escapes an alias name string.
942   *
943   * Force all alias names to be strictly alphanumeric-plus-underscore. In
944   * contrast to DatabaseConnection::escapeField() /
945   * DatabaseConnection::escapeTable(), this doesn't allow the period (".")
946   * because that is not allowed in aliases.
947   *
948   * @return
949   *   The sanitized field name string.
950   */
951  public function escapeAlias($field) {
952    return preg_replace('/[^A-Za-z0-9_]+/', '', $field);
953  }
954
955  /**
956   * Escapes characters that work as wildcard characters in a LIKE pattern.
957   *
958   * The wildcard characters "%" and "_" as well as backslash are prefixed with
959   * a backslash. Use this to do a search for a verbatim string without any
960   * wildcard behavior.
961   *
962   * For example, the following does a case-insensitive query for all rows whose
963   * name starts with $prefix:
964   * @code
965   * $result = db_query(
966   *   'SELECT * FROM person WHERE name LIKE :pattern',
967   *   array(':pattern' => db_like($prefix) . '%')
968   * );
969   * @endcode
970   *
971   * Backslash is defined as escape character for LIKE patterns in
972   * DatabaseCondition::mapConditionOperator().
973   *
974   * @param $string
975   *   The string to escape.
976   *
977   * @return
978   *   The escaped string.
979   */
980  public function escapeLike($string) {
981    return addcslashes($string, '\%_');
982  }
983
984  /**
985   * Determines if there is an active transaction open.
986   *
987   * @return
988   *   TRUE if we're currently in a transaction, FALSE otherwise.
989   */
990  public function inTransaction() {
991    return ($this->transactionDepth() > 0);
992  }
993
994  /**
995   * Determines current transaction depth.
996   */
997  public function transactionDepth() {
998    return count($this->transactionLayers);
999  }
1000
1001  /**
1002   * Returns a new DatabaseTransaction object on this connection.
1003   *
1004   * @param $name
1005   *   Optional name of the savepoint.
1006   *
1007   * @return DatabaseTransaction
1008   *   A DatabaseTransaction object.
1009   *
1010   * @see DatabaseTransaction
1011   */
1012  public function startTransaction($name = '') {
1013    $class = $this->getDriverClass('DatabaseTransaction');
1014    return new $class($this, $name);
1015  }
1016
1017  /**
1018   * Rolls back the transaction entirely or to a named savepoint.
1019   *
1020   * This method throws an exception if no transaction is active.
1021   *
1022   * @param $savepoint_name
1023   *   The name of the savepoint. The default, 'drupal_transaction', will roll
1024   *   the entire transaction back.
1025   *
1026   * @throws DatabaseTransactionNoActiveException
1027   *
1028   * @see DatabaseTransaction::rollback()
1029   */
1030  public function rollback($savepoint_name = 'drupal_transaction') {
1031    if (!$this->supportsTransactions()) {
1032      return;
1033    }
1034    if (!$this->inTransaction()) {
1035      throw new DatabaseTransactionNoActiveException();
1036    }
1037    // A previous rollback to an earlier savepoint may mean that the savepoint
1038    // in question has already been accidentally committed.
1039    if (!isset($this->transactionLayers[$savepoint_name])) {
1040      throw new DatabaseTransactionNoActiveException();
1041    }
1042
1043    // We need to find the point we're rolling back to, all other savepoints
1044    // before are no longer needed. If we rolled back other active savepoints,
1045    // we need to throw an exception.
1046    $rolled_back_other_active_savepoints = FALSE;
1047    while ($savepoint = array_pop($this->transactionLayers)) {
1048      if ($savepoint == $savepoint_name) {
1049        // If it is the last the transaction in the stack, then it is not a
1050        // savepoint, it is the transaction itself so we will need to roll back
1051        // the transaction rather than a savepoint.
1052        if (empty($this->transactionLayers)) {
1053          break;
1054        }
1055        $this->query('ROLLBACK TO SAVEPOINT ' . $savepoint);
1056        $this->popCommittableTransactions();
1057        if ($rolled_back_other_active_savepoints) {
1058          throw new DatabaseTransactionOutOfOrderException();
1059        }
1060        return;
1061      }
1062      else {
1063        $rolled_back_other_active_savepoints = TRUE;
1064      }
1065    }
1066    parent::rollBack();
1067    if ($rolled_back_other_active_savepoints) {
1068      throw new DatabaseTransactionOutOfOrderException();
1069    }
1070  }
1071
1072  /**
1073   * Increases the depth of transaction nesting.
1074   *
1075   * If no transaction is already active, we begin a new transaction.
1076   *
1077   * @throws DatabaseTransactionNameNonUniqueException
1078   *
1079   * @see DatabaseTransaction
1080   */
1081  public function pushTransaction($name) {
1082    if (!$this->supportsTransactions()) {
1083      return;
1084    }
1085    if (isset($this->transactionLayers[$name])) {
1086      throw new DatabaseTransactionNameNonUniqueException($name . " is already in use.");
1087    }
1088    // If we're already in a transaction then we want to create a savepoint
1089    // rather than try to create another transaction.
1090    if ($this->inTransaction()) {
1091      $this->query('SAVEPOINT ' . $name);
1092    }
1093    else {
1094      parent::beginTransaction();
1095    }
1096    $this->transactionLayers[$name] = $name;
1097  }
1098
1099  /**
1100   * Decreases the depth of transaction nesting.
1101   *
1102   * If we pop off the last transaction layer, then we either commit or roll
1103   * back the transaction as necessary. If no transaction is active, we return
1104   * because the transaction may have manually been rolled back.
1105   *
1106   * @param $name
1107   *   The name of the savepoint
1108   *
1109   * @throws DatabaseTransactionNoActiveException
1110   * @throws DatabaseTransactionCommitFailedException
1111   *
1112   * @see DatabaseTransaction
1113   */
1114  public function popTransaction($name) {
1115    if (!$this->supportsTransactions()) {
1116      return;
1117    }
1118    // The transaction has already been committed earlier. There is nothing we
1119    // need to do. If this transaction was part of an earlier out-of-order
1120    // rollback, an exception would already have been thrown by
1121    // Database::rollback().
1122    if (!isset($this->transactionLayers[$name])) {
1123      return;
1124    }
1125
1126    // Mark this layer as committable.
1127    $this->transactionLayers[$name] = FALSE;
1128    $this->popCommittableTransactions();
1129  }
1130
1131  /**
1132   * Internal function: commit all the transaction layers that can commit.
1133   */
1134  protected function popCommittableTransactions() {
1135    // Commit all the committable layers.
1136    foreach (array_reverse($this->transactionLayers) as $name => $active) {
1137      // Stop once we found an active transaction.
1138      if ($active) {
1139        break;
1140      }
1141
1142      // If there are no more layers left then we should commit.
1143      unset($this->transactionLayers[$name]);
1144      if (empty($this->transactionLayers)) {
1145        if (!parent::commit()) {
1146          throw new DatabaseTransactionCommitFailedException();
1147        }
1148      }
1149      else {
1150        $this->query('RELEASE SAVEPOINT ' . $name);
1151      }
1152    }
1153  }
1154
1155  /**
1156   * Runs a limited-range query on this database object.
1157   *
1158   * Use this as a substitute for ->query() when a subset of the query is to be
1159   * returned. User-supplied arguments to the query should be passed in as
1160   * separate parameters so that they can be properly escaped to avoid SQL
1161   * injection attacks.
1162   *
1163   * @param $query
1164   *   A string containing an SQL query.
1165   * @param $args
1166   *   An array of values to substitute into the query at placeholder markers.
1167   * @param $from
1168   *   The first result row to return.
1169   * @param $count
1170   *   The maximum number of result rows to return.
1171   * @param $options
1172   *   An array of options on the query.
1173   *
1174   * @return DatabaseStatementInterface
1175   *   A database query result resource, or NULL if the query was not executed
1176   *   correctly.
1177   */
1178  abstract public function queryRange($query, $from, $count, array $args = array(), array $options = array());
1179
1180  /**
1181   * Generates a temporary table name.
1182   *
1183   * @return
1184   *   A table name.
1185   */
1186  protected function generateTemporaryTableName() {
1187    return "db_temporary_" . $this->temporaryNameIndex++;
1188  }
1189
1190  /**
1191   * Runs a SELECT query and stores its results in a temporary table.
1192   *
1193   * Use this as a substitute for ->query() when the results need to stored
1194   * in a temporary table. Temporary tables exist for the duration of the page
1195   * request. User-supplied arguments to the query should be passed in as
1196   * separate parameters so that they can be properly escaped to avoid SQL
1197   * injection attacks.
1198   *
1199   * Note that if you need to know how many results were returned, you should do
1200   * a SELECT COUNT(*) on the temporary table afterwards.
1201   *
1202   * @param $query
1203   *   A string containing a normal SELECT SQL query.
1204   * @param $args
1205   *   An array of values to substitute into the query at placeholder markers.
1206   * @param $options
1207   *   An associative array of options to control how the query is run. See
1208   *   the documentation for DatabaseConnection::defaultOptions() for details.
1209   *
1210   * @return
1211   *   The name of the temporary table.
1212   */
1213  abstract function queryTemporary($query, array $args = array(), array $options = array());
1214
1215  /**
1216   * Returns the type of database driver.
1217   *
1218   * This is not necessarily the same as the type of the database itself. For
1219   * instance, there could be two MySQL drivers, mysql and mysql_mock. This
1220   * function would return different values for each, but both would return
1221   * "mysql" for databaseType().
1222   */
1223  abstract public function driver();
1224
1225  /**
1226   * Returns the version of the database server.
1227   */
1228  public function version() {
1229    return $this->getAttribute(PDO::ATTR_SERVER_VERSION);
1230  }
1231
1232  /**
1233   * Determines if this driver supports transactions.
1234   *
1235   * @return
1236   *   TRUE if this connection supports transactions, FALSE otherwise.
1237   */
1238  public function supportsTransactions() {
1239    return $this->transactionSupport;
1240  }
1241
1242  /**
1243   * Determines if this driver supports transactional DDL.
1244   *
1245   * DDL queries are those that change the schema, such as ALTER queries.
1246   *
1247   * @return
1248   *   TRUE if this connection supports transactions for DDL queries, FALSE
1249   *   otherwise.
1250   */
1251  public function supportsTransactionalDDL() {
1252    return $this->transactionalDDLSupport;
1253  }
1254
1255  /**
1256   * Returns the name of the PDO driver for this connection.
1257   */
1258  abstract public function databaseType();
1259
1260
1261  /**
1262   * Gets any special processing requirements for the condition operator.
1263   *
1264   * Some condition types require special processing, such as IN, because
1265   * the value data they pass in is not a simple value. This is a simple
1266   * overridable lookup function. Database connections should define only
1267   * those operators they wish to be handled differently than the default.
1268   *
1269   * @param $operator
1270   *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
1271   *
1272   * @return
1273   *   The extra handling directives for the specified operator, or NULL.
1274   *
1275   * @see DatabaseCondition::compile()
1276   */
1277  abstract public function mapConditionOperator($operator);
1278
1279  /**
1280   * Throws an exception to deny direct access to transaction commits.
1281   *
1282   * We do not want to allow users to commit transactions at any time, only
1283   * by destroying the transaction object or allowing it to go out of scope.
1284   * A direct commit bypasses all of the safety checks we've built on top of
1285   * PDO's transaction routines.
1286   *
1287   * @throws DatabaseTransactionExplicitCommitNotAllowedException
1288   *
1289   * @see DatabaseTransaction
1290   */
1291  public function commit() {
1292    throw new DatabaseTransactionExplicitCommitNotAllowedException();
1293  }
1294
1295  /**
1296   * Retrieves an unique id from a given sequence.
1297   *
1298   * Use this function if for some reason you can't use a serial field. For
1299   * example, MySQL has no ways of reading of the current value of a sequence
1300   * and PostgreSQL can not advance the sequence to be larger than a given
1301   * value. Or sometimes you just need a unique integer.
1302   *
1303   * @param $existing_id
1304   *   After a database import, it might be that the sequences table is behind,
1305   *   so by passing in the maximum existing id, it can be assured that we
1306   *   never issue the same id.
1307   *
1308   * @return
1309   *   An integer number larger than any number returned by earlier calls and
1310   *   also larger than the $existing_id if one was passed in.
1311   */
1312  abstract public function nextId($existing_id = 0);
1313}
1314
1315/**
1316 * Primary front-controller for the database system.
1317 *
1318 * This class is uninstantiatable and un-extendable. It acts to encapsulate
1319 * all control and shepherding of database connections into a single location
1320 * without the use of globals.
1321 */
1322abstract class Database {
1323
1324  /**
1325   * Flag to indicate a query call should simply return NULL.
1326   *
1327   * This is used for queries that have no reasonable return value anyway, such
1328   * as INSERT statements to a table without a serial primary key.
1329   */
1330  const RETURN_NULL = 0;
1331
1332  /**
1333   * Flag to indicate a query call should return the prepared statement.
1334   */
1335  const RETURN_STATEMENT = 1;
1336
1337  /**
1338   * Flag to indicate a query call should return the number of affected rows.
1339   */
1340  const RETURN_AFFECTED = 2;
1341
1342  /**
1343   * Flag to indicate a query call should return the "last insert id".
1344   */
1345  const RETURN_INSERT_ID = 3;
1346
1347  /**
1348   * An nested array of all active connections. It is keyed by database name
1349   * and target.
1350   *
1351   * @var array
1352   */
1353  static protected $connections = array();
1354
1355  /**
1356   * A processed copy of the database connection information from settings.php.
1357   *
1358   * @var array
1359   */
1360  static protected $databaseInfo = NULL;
1361
1362  /**
1363   * A list of key/target credentials to simply ignore.
1364   *
1365   * @var array
1366   */
1367  static protected $ignoreTargets = array();
1368
1369  /**
1370   * The key of the currently active database connection.
1371   *
1372   * @var string
1373   */
1374  static protected $activeKey = 'default';
1375
1376  /**
1377   * An array of active query log objects.
1378   *
1379   * Every connection has one and only one logger object for all targets and
1380   * logging keys.
1381   *
1382   * array(
1383   *   '$db_key' => DatabaseLog object.
1384   * );
1385   *
1386   * @var array
1387   */
1388  static protected $logs = array();
1389
1390  /**
1391   * Starts logging a given logging key on the specified connection.
1392   *
1393   * @param $logging_key
1394   *   The logging key to log.
1395   * @param $key
1396   *   The database connection key for which we want to log.
1397   *
1398   * @return DatabaseLog
1399   *   The query log object. Note that the log object does support richer
1400   *   methods than the few exposed through the Database class, so in some
1401   *   cases it may be desirable to access it directly.
1402   *
1403   * @see DatabaseLog
1404   */
1405  final public static function startLog($logging_key, $key = 'default') {
1406    if (empty(self::$logs[$key])) {
1407      self::$logs[$key] = new DatabaseLog($key);
1408
1409      // Every target already active for this connection key needs to have the
1410      // logging object associated with it.
1411      if (!empty(self::$connections[$key])) {
1412        foreach (self::$connections[$key] as $connection) {
1413          $connection->setLogger(self::$logs[$key]);
1414        }
1415      }
1416    }
1417
1418    self::$logs[$key]->start($logging_key);
1419    return self::$logs[$key];
1420  }
1421
1422  /**
1423   * Retrieves the queries logged on for given logging key.
1424   *
1425   * This method also ends logging for the specified key. To get the query log
1426   * to date without ending the logger request the logging object by starting
1427   * it again (which does nothing to an open log key) and call methods on it as
1428   * desired.
1429   *
1430   * @param $logging_key
1431   *   The logging key to log.
1432   * @param $key
1433   *   The database connection key for which we want to log.
1434   *
1435   * @return array
1436   *   The query log for the specified logging key and connection.
1437   *
1438   * @see DatabaseLog
1439   */
1440  final public static function getLog($logging_key, $key = 'default') {
1441    if (empty(self::$logs[$key])) {
1442      return NULL;
1443    }
1444    $queries = self::$logs[$key]->get($logging_key);
1445    self::$logs[$key]->end($logging_key);
1446    return $queries;
1447  }
1448
1449  /**
1450   * Gets the connection object for the specified database key and target.
1451   *
1452   * @param $target
1453   *   The database target name.
1454   * @param $key
1455   *   The database connection key. Defaults to NULL which means the active key.
1456   *
1457   * @return DatabaseConnection
1458   *   The corresponding connection object.
1459   */
1460  final public static function getConnection($target = 'default', $key = NULL) {
1461    if (!isset($key)) {
1462      // By default, we want the active connection, set in setActiveConnection.
1463      $key = self::$activeKey;
1464    }
1465    // If the requested target does not exist, or if it is ignored, we fall back
1466    // to the default target. The target is typically either "default" or
1467    // "slave", indicating to use a slave SQL server if one is available. If
1468    // it's not available, then the default/master server is the correct server
1469    // to use.
1470    if (!empty(self::$ignoreTargets[$key][$target]) || !isset(self::$databaseInfo[$key][$target])) {
1471      $target = 'default';
1472    }
1473
1474    if (!isset(self::$connections[$key][$target])) {
1475      // If necessary, a new connection is opened.
1476      self::$connections[$key][$target] = self::openConnection($key, $target);
1477    }
1478    return self::$connections[$key][$target];
1479  }
1480
1481  /**
1482   * Determines if there is an active connection.
1483   *
1484   * Note that this method will return FALSE if no connection has been
1485   * established yet, even if one could be.
1486   *
1487   * @return
1488   *   TRUE if there is at least one database connection established, FALSE
1489   *   otherwise.
1490   */
1491  final public static function isActiveConnection() {
1492    return !empty(self::$activeKey) && !empty(self::$connections) && !empty(self::$connections[self::$activeKey]);
1493  }
1494
1495  /**
1496   * Sets the active connection to the specified key.
1497   *
1498   * @return
1499   *   The previous database connection key.
1500   */
1501  final public static function setActiveConnection($key = 'default') {
1502    if (empty(self::$databaseInfo)) {
1503      self::parseConnectionInfo();
1504    }
1505
1506    if (!empty(self::$databaseInfo[$key])) {
1507      $old_key = self::$activeKey;
1508      self::$activeKey = $key;
1509      return $old_key;
1510    }
1511  }
1512
1513  /**
1514   * Process the configuration file for database information.
1515   */
1516  final public static function parseConnectionInfo() {
1517    global $databases;
1518
1519    $database_info = is_array($databases) ? $databases : array();
1520    foreach ($database_info as $index => $info) {
1521      foreach ($database_info[$index] as $target => $value) {
1522        // If there is no "driver" property, then we assume it's an array of
1523        // possible connections for this target. Pick one at random. That allows
1524        //  us to have, for example, multiple slave servers.
1525        if (empty($value['driver'])) {
1526          $database_info[$index][$target] = $database_info[$index][$target][mt_rand(0, count($database_info[$index][$target]) - 1)];
1527        }
1528
1529        // Parse the prefix information.
1530        if (!isset($database_info[$index][$target]['prefix'])) {
1531          // Default to an empty prefix.
1532          $database_info[$index][$target]['prefix'] = array(
1533            'default' => '',
1534          );
1535        }
1536        elseif (!is_array($database_info[$index][$target]['prefix'])) {
1537          // Transform the flat form into an array form.
1538          $database_info[$index][$target]['prefix'] = array(
1539            'default' => $database_info[$index][$target]['prefix'],
1540          );
1541        }
1542      }
1543    }
1544
1545    if (!is_array(self::$databaseInfo)) {
1546      self::$databaseInfo = $database_info;
1547    }
1548
1549    // Merge the new $database_info into the existing.
1550    // array_merge_recursive() cannot be used, as it would make multiple
1551    // database, user, and password keys in the same database array.
1552    else {
1553      foreach ($database_info as $database_key => $database_values) {
1554        foreach ($database_values as $target => $target_values) {
1555          self::$databaseInfo[$database_key][$target] = $target_values;
1556        }
1557      }
1558    }
1559  }
1560
1561  /**
1562   * Adds database connection information for a given key/target.
1563   *
1564   * This method allows the addition of new connection credentials at runtime.
1565   * Under normal circumstances the preferred way to specify database
1566   * credentials is via settings.php. However, this method allows them to be
1567   * added at arbitrary times, such as during unit tests, when connecting to
1568   * admin-defined third party databases, etc.
1569   *
1570   * If the given key/target pair already exists, this method will be ignored.
1571   *
1572   * @param $key
1573   *   The database key.
1574   * @param $target
1575   *   The database target name.
1576   * @param $info
1577   *   The database connection information, as it would be defined in
1578   *   settings.php. Note that the structure of this array will depend on the
1579   *   database driver it is connecting to.
1580   */
1581  public static function addConnectionInfo($key, $target, $info) {
1582    if (empty(self::$databaseInfo[$key][$target])) {
1583      self::$databaseInfo[$key][$target] = $info;
1584    }
1585  }
1586
1587  /**
1588   * Gets information on the specified database connection.
1589   *
1590   * @param $connection
1591   *   The connection key for which we want information.
1592   */
1593  final public static function getConnectionInfo($key = 'default') {
1594    if (empty(self::$databaseInfo)) {
1595      self::parseConnectionInfo();
1596    }
1597
1598    if (!empty(self::$databaseInfo[$key])) {
1599      return self::$databaseInfo[$key];
1600    }
1601  }
1602
1603  /**
1604   * Rename a connection and its corresponding connection information.
1605   *
1606   * @param $old_key
1607   *   The old connection key.
1608   * @param $new_key
1609   *   The new connection key.
1610   * @return
1611   *   TRUE in case of success, FALSE otherwise.
1612   */
1613  final public static function renameConnection($old_key, $new_key) {
1614    if (empty(self::$databaseInfo)) {
1615      self::parseConnectionInfo();
1616    }
1617
1618    if (!empty(self::$databaseInfo[$old_key]) && empty(self::$databaseInfo[$new_key])) {
1619      // Migrate the database connection information.
1620      self::$databaseInfo[$new_key] = self::$databaseInfo[$old_key];
1621      unset(self::$databaseInfo[$old_key]);
1622
1623      // Migrate over the DatabaseConnection object if it exists.
1624      if (isset(self::$connections[$old_key])) {
1625        self::$connections[$new_key] = self::$connections[$old_key];
1626        unset(self::$connections[$old_key]);
1627      }
1628
1629      return TRUE;
1630    }
1631    else {
1632      return FALSE;
1633    }
1634  }
1635
1636  /**
1637   * Remove a connection and its corresponding connection information.
1638   *
1639   * @param $key
1640   *   The connection key.
1641   * @return
1642   *   TRUE in case of success, FALSE otherwise.
1643   */
1644  final public static function removeConnection($key) {
1645    if (isset(self::$databaseInfo[$key])) {
1646      self::closeConnection(NULL, $key);
1647      unset(self::$databaseInfo[$key]);
1648      return TRUE;
1649    }
1650    else {
1651      return FALSE;
1652    }
1653  }
1654
1655  /**
1656   * Opens a connection to the server specified by the given key and target.
1657   *
1658   * @param $key
1659   *   The database connection key, as specified in settings.php. The default is
1660   *   "default".
1661   * @param $target
1662   *   The database target to open.
1663   *
1664   * @throws DatabaseConnectionNotDefinedException
1665   * @throws DatabaseDriverNotSpecifiedException
1666   */
1667  final protected static function openConnection($key, $target) {
1668    if (empty(self::$databaseInfo)) {
1669      self::parseConnectionInfo();
1670    }
1671
1672    // If the requested database does not exist then it is an unrecoverable
1673    // error.
1674    if (!isset(self::$databaseInfo[$key])) {
1675      throw new DatabaseConnectionNotDefinedException('The specified database connection is not defined: ' . $key);
1676    }
1677
1678    if (!$driver = self::$databaseInfo[$key][$target]['driver']) {
1679      throw new DatabaseDriverNotSpecifiedException('Driver not specified for this database connection: ' . $key);
1680    }
1681
1682    // We cannot rely on the registry yet, because the registry requires an
1683    // open database connection.
1684    $driver_class = 'DatabaseConnection_' . $driver;
1685    require_once DRUPAL_ROOT . '/includes/database/' . $driver . '/database.inc';
1686    $new_connection = new $driver_class(self::$databaseInfo[$key][$target]);
1687    $new_connection->setTarget($target);
1688    $new_connection->setKey($key);
1689
1690    // If we have any active logging objects for this connection key, we need
1691    // to associate them with the connection we just opened.
1692    if (!empty(self::$logs[$key])) {
1693      $new_connection->setLogger(self::$logs[$key]);
1694    }
1695
1696    return $new_connection;
1697  }
1698
1699  /**
1700   * Closes a connection to the server specified by the given key and target.
1701   *
1702   * @param $target
1703   *   The database target name.  Defaults to NULL meaning that all target
1704   *   connections will be closed.
1705   * @param $key
1706   *   The database connection key. Defaults to NULL which means the active key.
1707   */
1708  public static function closeConnection($target = NULL, $key = NULL) {
1709    // Gets the active connection by default.
1710    if (!isset($key)) {
1711      $key = self::$activeKey;
1712    }
1713    // To close a connection, it needs to be set to NULL and removed from the
1714    // static variable. In all cases, closeConnection() might be called for a
1715    // connection that was not opened yet, in which case the key is not defined
1716    // yet and we just ensure that the connection key is undefined.
1717    if (isset($target)) {
1718      if (isset(self::$connections[$key][$target])) {
1719        self::$connections[$key][$target]->destroy();
1720        self::$connections[$key][$target] = NULL;
1721      }
1722      unset(self::$connections[$key][$target]);
1723    }
1724    else {
1725      if (isset(self::$connections[$key])) {
1726        foreach (self::$connections[$key] as $target => $connection) {
1727          self::$connections[$key][$target]->destroy();
1728          self::$connections[$key][$target] = NULL;
1729        }
1730      }
1731      unset(self::$connections[$key]);
1732    }
1733  }
1734
1735  /**
1736   * Instructs the system to temporarily ignore a given key/target.
1737   *
1738   * At times we need to temporarily disable slave queries. To do so, call this
1739   * method with the database key and the target to disable. That database key
1740   * will then always fall back to 'default' for that key, even if it's defined.
1741   *
1742   * @param $key
1743   *   The database connection key.
1744   * @param $target
1745   *   The target of the specified key to ignore.
1746   */
1747  public static function ignoreTarget($key, $target) {
1748    self::$ignoreTargets[$key][$target] = TRUE;
1749  }
1750
1751  /**
1752   * Load a file for the database that might hold a class.
1753   *
1754   * @param $driver
1755   *   The name of the driver.
1756   * @param array $files
1757   *   The name of the files the driver specific class can be.
1758   */
1759  public static function loadDriverFile($driver, array $files = array()) {
1760    static $base_path;
1761
1762    if (empty($base_path)) {
1763      $base_path = dirname(realpath(__FILE__));
1764    }
1765
1766    $driver_base_path = "$base_path/$driver";
1767    foreach ($files as $file) {
1768      // Load the base file first so that classes extending base classes will
1769      // have the base class loaded.
1770      foreach (array("$base_path/$file", "$driver_base_path/$file") as $filename) {
1771        // The OS caches file_exists() and PHP caches require_once(), so
1772        // we'll let both of those take care of performance here.
1773        if (file_exists($filename)) {
1774          require_once $filename;
1775        }
1776      }
1777    }
1778  }
1779}
1780
1781/**
1782 * Exception for when popTransaction() is called with no active transaction.
1783 */
1784class DatabaseTransactionNoActiveException extends Exception { }
1785
1786/**
1787 * Exception thrown when a savepoint or transaction name occurs twice.
1788 */
1789class DatabaseTransactionNameNonUniqueException extends Exception { }
1790
1791/**
1792 * Exception thrown when a commit() function fails.
1793 */
1794class DatabaseTransactionCommitFailedException extends Exception { }
1795
1796/**
1797 * Exception to deny attempts to explicitly manage transactions.
1798 *
1799 * This exception will be thrown when the PDO connection commit() is called.
1800 * Code should never call this method directly.
1801 */
1802class DatabaseTransactionExplicitCommitNotAllowedException extends Exception { }
1803
1804/**
1805 * Exception thrown when a rollback() resulted in other active transactions being rolled-back.
1806 */
1807class DatabaseTransactionOutOfOrderException extends Exception { }
1808
1809/**
1810 * Exception thrown for merge queries that do not make semantic sense.
1811 *
1812 * There are many ways that a merge query could be malformed.  They should all
1813 * throw this exception and set an appropriately descriptive message.
1814 */
1815class InvalidMergeQueryException extends Exception {}
1816
1817/**
1818 * Exception thrown if an insert query specifies a field twice.
1819 *
1820 * It is not allowed to specify a field as default and insert field, this
1821 * exception is thrown if that is the case.
1822 */
1823class FieldsOverlapException extends Exception {}
1824
1825/**
1826 * Exception thrown if an insert query doesn't specify insert or default fields.
1827 */
1828class NoFieldsException extends Exception {}
1829
1830/**
1831 * Exception thrown if an undefined database connection is requested.
1832 */
1833class DatabaseConnectionNotDefinedException extends Exception {}
1834
1835/**
1836 * Exception thrown if no driver is specified for a database connection.
1837 */
1838class DatabaseDriverNotSpecifiedException extends Exception {}
1839
1840
1841/**
1842 * A wrapper class for creating and managing database transactions.
1843 *
1844 * Not all databases or database configurations support transactions. For
1845 * example, MySQL MyISAM tables do not. It is also easy to begin a transaction
1846 * and then forget to commit it, which can lead to connection errors when
1847 * another transaction is started.
1848 *
1849 * This class acts as a wrapper for transactions. To begin a transaction,
1850 * simply instantiate it. When the object goes out of scope and is destroyed
1851 * it will automatically commit. It also will check to see if the specified
1852 * connection supports transactions. If not, it will simply skip any transaction
1853 * commands, allowing user-space code to proceed normally. The only difference
1854 * is that rollbacks won't actually do anything.
1855 *
1856 * In the vast majority of cases, you should not instantiate this class
1857 * directly. Instead, call ->startTransaction(), from the appropriate connection
1858 * object.
1859 */
1860class DatabaseTransaction {
1861
1862  /**
1863   * The connection object for this transaction.
1864   *
1865   * @var DatabaseConnection
1866   */
1867  protected $connection;
1868
1869  /**
1870   * A boolean value to indicate whether this transaction has been rolled back.
1871   *
1872   * @var Boolean
1873   */
1874  protected $rolledBack = FALSE;
1875
1876  /**
1877   * The name of the transaction.
1878   *
1879   * This is used to label the transaction savepoint. It will be overridden to
1880   * 'drupal_transaction' if there is no transaction depth.
1881   */
1882  protected $name;
1883
1884  public function __construct(DatabaseConnection $connection, $name = NULL) {
1885    $this->connection = $connection;
1886    // If there is no transaction depth, then no transaction has started. Name
1887    // the transaction 'drupal_transaction'.
1888    if (!$depth = $connection->transactionDepth()) {
1889      $this->name = 'drupal_transaction';
1890    }
1891    // Within transactions, savepoints are used. Each savepoint requires a
1892    // name. So if no name is present we need to create one.
1893    elseif (!$name) {
1894      $this->name = 'savepoint_' . $depth;
1895    }
1896    else {
1897      $this->name = $name;
1898    }
1899    $this->connection->pushTransaction($this->name);
1900  }
1901
1902  public function __destruct() {
1903    // If we rolled back then the transaction would have already been popped.
1904    if (!$this->rolledBack) {
1905      $this->connection->popTransaction($this->name);
1906    }
1907  }
1908
1909  /**
1910   * Retrieves the name of the transaction or savepoint.
1911   */
1912  public function name() {
1913    return $this->name;
1914  }
1915
1916  /**
1917   * Rolls back the current transaction.
1918   *
1919   * This is just a wrapper method to rollback whatever transaction stack we are
1920   * currently in, which is managed by the connection object itself. Note that
1921   * logging (preferable with watchdog_exception()) needs to happen after a
1922   * transaction has been rolled back or the log messages will be rolled back
1923   * too.
1924   *
1925   * @see DatabaseConnection::rollback()
1926   * @see watchdog_exception()
1927   */
1928  public function rollback() {
1929    $this->rolledBack = TRUE;
1930    $this->connection->rollback($this->name);
1931  }
1932}
1933
1934/**
1935 * Represents a prepared statement.
1936 *
1937 * Some methods in that class are purposefully commented out. Due to a change in
1938 * how PHP defines PDOStatement, we can't define a signature for those methods
1939 * that will work the same way between versions older than 5.2.6 and later
1940 * versions.  See http://bugs.php.net/bug.php?id=42452 for more details.
1941 *
1942 * Child implementations should either extend PDOStatement:
1943 * @code
1944 * class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
1945 * @endcode
1946 * or define their own class. If defining their own class, they will also have
1947 * to implement either the Iterator or IteratorAggregate interface before
1948 * DatabaseStatementInterface:
1949 * @code
1950 * class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
1951 * @endcode
1952 */
1953interface DatabaseStatementInterface extends Traversable {
1954
1955  /**
1956   * Executes a prepared statement
1957   *
1958   * @param $args
1959   *   An array of values with as many elements as there are bound parameters in
1960   *   the SQL statement being executed.
1961   * @param $options
1962   *   An array of options for this query.
1963   *
1964   * @return
1965   *   TRUE on success, or FALSE on failure.
1966   */
1967  public function execute($args = array(), $options = array());
1968
1969  /**
1970   * Gets the query string of this statement.
1971   *
1972   * @return
1973   *   The query string, in its form with placeholders.
1974   */
1975  public function getQueryString();
1976
1977  /**
1978   * Returns the number of rows affected by the last SQL statement.
1979   *
1980   * @return
1981   *   The number of rows affected by the last DELETE, INSERT, or UPDATE
1982   *   statement executed.
1983   */
1984  public function rowCount();
1985
1986  /**
1987   * Sets the default fetch mode for this statement.
1988   *
1989   * See http://php.net/manual/en/pdo.constants.php for the definition of the
1990   * constants used.
1991   *
1992   * @param $mode
1993   *   One of the PDO::FETCH_* constants.
1994   * @param $a1
1995   *   An option depending of the fetch mode specified by $mode:
1996   *   - for PDO::FETCH_COLUMN, the index of the column to fetch
1997   *   - for PDO::FETCH_CLASS, the name of the class to create
1998   *   - for PDO::FETCH_INTO, the object to add the data to
1999   * @param $a2
2000   *   If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the
2001   *   constructor.
2002   */
2003  // public function setFetchMode($mode, $a1 = NULL, $a2 = array());
2004
2005  /**
2006   * Fetches the next row from a result set.
2007   *
2008   * See http://php.net/manual/en/pdo.constants.php for the definition of the
2009   * constants used.
2010   *
2011   * @param $mode
2012   *   One of the PDO::FETCH_* constants.
2013   *   Default to what was specified by setFetchMode().
2014   * @param $cursor_orientation
2015   *   Not implemented in all database drivers, don't use.
2016   * @param $cursor_offset
2017   *   Not implemented in all database drivers, don't use.
2018   *
2019   * @return
2020   *   A result, formatted according to $mode.
2021   */
2022  // public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
2023
2024  /**
2025   * Returns a single field from the next record of a result set.
2026   *
2027   * @param $index
2028   *   The numeric index of the field to return. Defaults to the first field.
2029   *
2030   * @return
2031   *   A single field from the next record, or FALSE if there is no next record.
2032   */
2033  public function fetchField($index = 0);
2034
2035  /**
2036   * Fetches the next row and returns it as an object.
2037   *
2038   * The object will be of the class specified by DatabaseStatementInterface::setFetchMode()
2039   * or stdClass if not specified.
2040   */
2041  // public function fetchObject();
2042
2043  /**
2044   * Fetches the next row and returns it as an associative array.
2045   *
2046   * This method corresponds to PDOStatement::fetchObject(), but for associative
2047   * arrays. For some reason PDOStatement does not have a corresponding array
2048   * helper method, so one is added.
2049   *
2050   * @return
2051   *   An associative array, or FALSE if there is no next row.
2052   */
2053  public function fetchAssoc();
2054
2055  /**
2056   * Returns an array containing all of the result set rows.
2057   *
2058   * @param $mode
2059   *   One of the PDO::FETCH_* constants.
2060   * @param $column_index
2061   *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
2062   * @param $constructor_arguments
2063   *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
2064   *
2065   * @return
2066   *   An array of results.
2067   */
2068  // function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments);
2069
2070  /**
2071   * Returns an entire single column of a result set as an indexed array.
2072   *
2073   * Note that this method will run the result set to the end.
2074   *
2075   * @param $index
2076   *   The index of the column number to fetch.
2077   *
2078   * @return
2079   *   An indexed array, or an empty array if there is no result set.
2080   */
2081  public function fetchCol($index = 0);
2082
2083  /**
2084   * Returns the entire result set as a single associative array.
2085   *
2086   * This method is only useful for two-column result sets. It will return an
2087   * associative array where the key is one column from the result set and the
2088   * value is another field. In most cases, the default of the first two columns
2089   * is appropriate.
2090   *
2091   * Note that this method will run the result set to the end.
2092   *
2093   * @param $key_index
2094   *   The numeric index of the field to use as the array key.
2095   * @param $value_index
2096   *   The numeric index of the field to use as the array value.
2097   *
2098   * @return
2099   *   An associative array, or an empty array if there is no result set.
2100   */
2101  public function fetchAllKeyed($key_index = 0, $value_index = 1);
2102
2103  /**
2104   * Returns the result set as an associative array keyed by the given field.
2105   *
2106   * If the given key appears multiple times, later records will overwrite
2107   * earlier ones.
2108   *
2109   * @param $key
2110   *   The name of the field on which to index the array.
2111   * @param $fetch
2112   *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
2113   *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
2114   *   other value it will be an array of objects. By default, the fetch mode
2115   *   set for the query will be used.
2116   *
2117   * @return
2118   *   An associative array, or an empty array if there is no result set.
2119   */
2120  public function fetchAllAssoc($key, $fetch = NULL);
2121}
2122
2123/**
2124 * Default implementation of DatabaseStatementInterface.
2125 *
2126 * PDO allows us to extend the PDOStatement class to provide additional
2127 * functionality beyond that offered by default. We do need extra
2128 * functionality. By default, this class is not driver-specific. If a given
2129 * driver needs to set a custom statement class, it may do so in its
2130 * constructor.
2131 *
2132 * @see http://us.php.net/pdostatement
2133 */
2134class DatabaseStatementBase extends PDOStatement implements DatabaseStatementInterface {
2135
2136  /**
2137   * Reference to the database connection object for this statement.
2138   *
2139   * The name $dbh is inherited from PDOStatement.
2140   *
2141   * @var DatabaseConnection
2142   */
2143  public $dbh;
2144
2145  protected function __construct($dbh) {
2146    $this->dbh = $dbh;
2147    $this->setFetchMode(PDO::FETCH_OBJ);
2148  }
2149
2150  public function execute($args = array(), $options = array()) {
2151    if (isset($options['fetch'])) {
2152      if (is_string($options['fetch'])) {
2153        // Default to an object. Note: db fields will be added to the object
2154        // before the constructor is run. If you need to assign fields after
2155        // the constructor is run, see http://drupal.org/node/315092.
2156        $this->setFetchMode(PDO::FETCH_CLASS, $options['fetch']);
2157      }
2158      else {
2159        $this->setFetchMode($options['fetch']);
2160      }
2161    }
2162
2163    $logger = $this->dbh->getLogger();
2164    if (!empty($logger)) {
2165      $query_start = microtime(TRUE);
2166    }
2167
2168    $return = parent::execute($args);
2169
2170    if (!empty($logger)) {
2171      $query_end = microtime(TRUE);
2172      $logger->log($this, $args, $query_end - $query_start);
2173    }
2174
2175    return $return;
2176  }
2177
2178  public function getQueryString() {
2179    return $this->queryString;
2180  }
2181
2182  public function fetchCol($index = 0) {
2183    return $this->fetchAll(PDO::FETCH_COLUMN, $index);
2184  }
2185
2186  public function fetchAllAssoc($key, $fetch = NULL) {
2187    $return = array();
2188    if (isset($fetch)) {
2189      if (is_string($fetch)) {
2190        $this->setFetchMode(PDO::FETCH_CLASS, $fetch);
2191      }
2192      else {
2193        $this->setFetchMode($fetch);
2194      }
2195    }
2196
2197    foreach ($this as $record) {
2198      $record_key = is_object($record) ? $record->$key : $record[$key];
2199      $return[$record_key] = $record;
2200    }
2201
2202    return $return;
2203  }
2204
2205  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2206    $return = array();
2207    $this->setFetchMode(PDO::FETCH_NUM);
2208    foreach ($this as $record) {
2209      $return[$record[$key_index]] = $record[$value_index];
2210    }
2211    return $return;
2212  }
2213
2214  public function fetchField($index = 0) {
2215    // Call PDOStatement::fetchColumn to fetch the field.
2216    return $this->fetchColumn($index);
2217  }
2218
2219  public function fetchAssoc() {
2220    // Call PDOStatement::fetch to fetch the row.
2221    return $this->fetch(PDO::FETCH_ASSOC);
2222  }
2223}
2224
2225/**
2226 * Empty implementation of a database statement.
2227 *
2228 * This class satisfies the requirements of being a database statement/result
2229 * object, but does not actually contain data.  It is useful when developers
2230 * need to safely return an "empty" result set without connecting to an actual
2231 * database.  Calling code can then treat it the same as if it were an actual
2232 * result set that happens to contain no records.
2233 *
2234 * @see SearchQuery
2235 */
2236class DatabaseStatementEmpty implements Iterator, DatabaseStatementInterface {
2237
2238  public function execute($args = array(), $options = array()) {
2239    return FALSE;
2240  }
2241
2242  public function getQueryString() {
2243    return '';
2244  }
2245
2246  public function rowCount() {
2247    return 0;
2248  }
2249
2250  public function setFetchMode($mode, $a1 = NULL, $a2 = array()) {
2251    return;
2252  }
2253
2254  public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL) {
2255    return NULL;
2256  }
2257
2258  public function fetchField($index = 0) {
2259    return NULL;
2260  }
2261
2262  public function fetchObject() {
2263    return NULL;
2264  }
2265
2266  public function fetchAssoc() {
2267    return NULL;
2268  }
2269
2270  function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments = array()) {
2271    return array();
2272  }
2273
2274  public function fetchCol($index = 0) {
2275    return array();
2276  }
2277
2278  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2279    return array();
2280  }
2281
2282  public function fetchAllAssoc($key, $fetch = NULL) {
2283    return array();
2284  }
2285
2286  /* Implementations of Iterator. */
2287
2288  public function current() {
2289    return NULL;
2290  }
2291
2292  public function key() {
2293    return NULL;
2294  }
2295
2296  public function rewind() {
2297    // Nothing to do: our DatabaseStatement can't be rewound.
2298  }
2299
2300  public function next() {
2301    // Do nothing, since this is an always-empty implementation.
2302  }
2303
2304  public function valid() {
2305    return FALSE;
2306  }
2307}
2308
2309/**
2310 * The following utility functions are simply convenience wrappers.
2311 *
2312 * They should never, ever have any database-specific code in them.
2313 */
2314
2315/**
2316 * Executes an arbitrary query string against the active database.
2317 *
2318 * Use this function for SELECT queries if it is just a simple query string.
2319 * If the caller or other modules need to change the query, use db_select()
2320 * instead.
2321 *
2322 * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
2323 * be handled via db_insert(), db_update() and db_delete() respectively.
2324 *
2325 * @param $query
2326 *   The prepared statement query to run. Although it will accept both named and
2327 *   unnamed placeholders, named placeholders are strongly preferred as they are
2328 *   more self-documenting.
2329 * @param $args
2330 *   An array of values to substitute into the query. If the query uses named
2331 *   placeholders, this is an associative array in any order. If the query uses
2332 *   unnamed placeholders (?), this is an indexed array and the order must match
2333 *   the order of placeholders in the query string.
2334 * @param $options
2335 *   An array of options to control how the query operates.
2336 *
2337 * @return DatabaseStatementInterface
2338 *   A prepared statement object, already executed.
2339 *
2340 * @see DatabaseConnection::defaultOptions()
2341 */
2342function db_query($query, array $args = array(), array $options = array()) {
2343  if (empty($options['target'])) {
2344    $options['target'] = 'default';
2345  }
2346
2347  return Database::getConnection($options['target'])->query($query, $args, $options);
2348}
2349
2350/**
2351 * Executes a query against the active database, restricted to a range.
2352 *
2353 * @param $query
2354 *   The prepared statement query to run. Although it will accept both named and
2355 *   unnamed placeholders, named placeholders are strongly preferred as they are
2356 *   more self-documenting.
2357 * @param $from
2358 *   The first record from the result set to return.
2359 * @param $count
2360 *   The number of records to return from the result set.
2361 * @param $args
2362 *   An array of values to substitute into the query. If the query uses named
2363 *   placeholders, this is an associative array in any order. If the query uses
2364 *   unnamed placeholders (?), this is an indexed array and the order must match
2365 *   the order of placeholders in the query string.
2366 * @param $options
2367 *   An array of options to control how the query operates.
2368 *
2369 * @return DatabaseStatementInterface
2370 *   A prepared statement object, already executed.
2371 *
2372 * @see DatabaseConnection::defaultOptions()
2373 */
2374function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
2375  if (empty($options['target'])) {
2376    $options['target'] = 'default';
2377  }
2378
2379  return Database::getConnection($options['target'])->queryRange($query, $from, $count, $args, $options);
2380}
2381
2382/**
2383 * Executes a query string and saves the result set to a temporary table.
2384 *
2385 * The execution of the query string happens against the active database.
2386 *
2387 * @param $query
2388 *   The prepared statement query to run. Although it will accept both named and
2389 *   unnamed placeholders, named placeholders are strongly preferred as they are
2390 *   more self-documenting.
2391 * @param $args
2392 *   An array of values to substitute into the query. If the query uses named
2393 *   placeholders, this is an associative array in any order. If the query uses
2394 *   unnamed placeholders (?), this is an indexed array and the order must match
2395 *   the order of placeholders in the query string.
2396 * @param $options
2397 *   An array of options to control how the query operates.
2398 *
2399 * @return
2400 *   The name of the temporary table.
2401 *
2402 * @see DatabaseConnection::defaultOptions()
2403 */
2404function db_query_temporary($query, array $args = array(), array $options = array()) {
2405  if (empty($options['target'])) {
2406    $options['target'] = 'default';
2407  }
2408
2409  return Database::getConnection($options['target'])->queryTemporary($query, $args, $options);
2410}
2411
2412/**
2413 * Returns a new InsertQuery object for the active database.
2414 *
2415 * @param $table
2416 *   The table into which to insert.
2417 * @param $options
2418 *   An array of options to control how the query operates.
2419 *
2420 * @return InsertQuery
2421 *   A new InsertQuery object for this connection.
2422 */
2423function db_insert($table, array $options = array()) {
2424  if (empty($options['target']) || $options['target'] == 'slave') {
2425    $options['target'] = 'default';
2426  }
2427  return Database::getConnection($options['target'])->insert($table, $options);
2428}
2429
2430/**
2431 * Returns a new MergeQuery object for the active database.
2432 *
2433 * @param $table
2434 *   The table into which to merge.
2435 * @param $options
2436 *   An array of options to control how the query operates.
2437 *
2438 * @return MergeQuery
2439 *   A new MergeQuery object for this connection.
2440 */
2441function db_merge($table, array $options = array()) {
2442  if (empty($options['target']) || $options['target'] == 'slave') {
2443    $options['target'] = 'default';
2444  }
2445  return Database::getConnection($options['target'])->merge($table, $options);
2446}
2447
2448/**
2449 * Returns a new UpdateQuery object for the active database.
2450 *
2451 * @param $table
2452 *   The table to update.
2453 * @param $options
2454 *   An array of options to control how the query operates.
2455 *
2456 * @return UpdateQuery
2457 *   A new UpdateQuery object for this connection.
2458 */
2459function db_update($table, array $options = array()) {
2460  if (empty($options['target']) || $options['target'] == 'slave') {
2461    $options['target'] = 'default';
2462  }
2463  return Database::getConnection($options['target'])->update($table, $options);
2464}
2465
2466/**
2467 * Returns a new DeleteQuery object for the active database.
2468 *
2469 * @param $table
2470 *   The table from which to delete.
2471 * @param $options
2472 *   An array of options to control how the query operates.
2473 *
2474 * @return DeleteQuery
2475 *   A new DeleteQuery object for this connection.
2476 */
2477function db_delete($table, array $options = array()) {
2478  if (empty($options['target']) || $options['target'] == 'slave') {
2479    $options['target'] = 'default';
2480  }
2481  return Database::getConnection($options['target'])->delete($table, $options);
2482}
2483
2484/**
2485 * Returns a new TruncateQuery object for the active database.
2486 *
2487 * @param $table
2488 *   The table from which to delete.
2489 * @param $options
2490 *   An array of options to control how the query operates.
2491 *
2492 * @return TruncateQuery
2493 *   A new TruncateQuery object for this connection.
2494 */
2495function db_truncate($table, array $options = array()) {
2496  if (empty($options['target']) || $options['target'] == 'slave') {
2497    $options['target'] = 'default';
2498  }
2499  return Database::getConnection($options['target'])->truncate($table, $options);
2500}
2501
2502/**
2503 * Returns a new SelectQuery object for the active database.
2504 *
2505 * @param $table
2506 *   The base table for this query. May be a string or another SelectQuery
2507 *   object. If a query object is passed, it will be used as a subselect.
2508 * @param $alias
2509 *   The alias for the base table of this query.
2510 * @param $options
2511 *   An array of options to control how the query operates.
2512 *
2513 * @return SelectQuery
2514 *   A new SelectQuery object for this connection.
2515 */
2516function db_select($table, $alias = NULL, array $options = array()) {
2517  if (empty($options['target'])) {
2518    $options['target'] = 'default';
2519  }
2520  return Database::getConnection($options['target'])->select($table, $alias, $options);
2521}
2522
2523/**
2524 * Returns a new transaction object for the active database.
2525 *
2526 * @param string $name
2527 *   Optional name of the transaction.
2528 * @param array $options
2529 *   An array of options to control how the transaction operates:
2530 *   - target: The database target name.
2531 *
2532 * @return DatabaseTransaction
2533 *   A new DatabaseTransaction object for this connection.
2534 */
2535function db_transaction($name = NULL, array $options = array()) {
2536  if (empty($options['target'])) {
2537    $options['target'] = 'default';
2538  }
2539  return Database::getConnection($options['target'])->startTransaction($name);
2540}
2541
2542/**
2543 * Sets a new active database.
2544 *
2545 * @param $key
2546 *   The key in the $databases array to set as the default database.
2547 *
2548 * @return
2549 *   The key of the formerly active database.
2550 */
2551function db_set_active($key = 'default') {
2552  return Database::setActiveConnection($key);
2553}
2554
2555/**
2556 * Restricts a dynamic table name to safe characters.
2557 *
2558 * Only keeps alphanumeric and underscores.
2559 *
2560 * @param $table
2561 *   The table name to escape.
2562 *
2563 * @return
2564 *   The escaped table name as a string.
2565 */
2566function db_escape_table($table) {
2567  return Database::getConnection()->escapeTable($table);
2568}
2569
2570/**
2571 * Restricts a dynamic column or constraint name to safe characters.
2572 *
2573 * Only keeps alphanumeric and underscores.
2574 *
2575 * @param $field
2576 *   The field name to escape.
2577 *
2578 * @return
2579 *   The escaped field name as a string.
2580 */
2581function db_escape_field($field) {
2582  return Database::getConnection()->escapeField($field);
2583}
2584
2585/**
2586 * Escapes characters that work as wildcard characters in a LIKE pattern.
2587 *
2588 * The wildcard characters "%" and "_" as well as backslash are prefixed with
2589 * a backslash. Use this to do a search for a verbatim string without any
2590 * wildcard behavior.
2591 *
2592 * For example, the following does a case-insensitive query for all rows whose
2593 * name starts with $prefix:
2594 * @code
2595 * $result = db_query(
2596 *   'SELECT * FROM person WHERE name LIKE :pattern',
2597 *   array(':pattern' => db_like($prefix) . '%')
2598 * );
2599 * @endcode
2600 *
2601 * Backslash is defined as escape character for LIKE patterns in
2602 * DatabaseCondition::mapConditionOperator().
2603 *
2604 * @param $string
2605 *   The string to escape.
2606 *
2607 * @return
2608 *   The escaped string.
2609 */
2610function db_like($string) {
2611  return Database::getConnection()->escapeLike($string);
2612}
2613
2614/**
2615 * Retrieves the name of the currently active database driver.
2616 *
2617 * @return
2618 *   The name of the currently active database driver.
2619 */
2620function db_driver() {
2621  return Database::getConnection()->driver();
2622}
2623
2624/**
2625 * Closes the active database connection.
2626 *
2627 * @param $options
2628 *   An array of options to control which connection is closed. Only the target
2629 *   key has any meaning in this case.
2630 */
2631function db_close(array $options = array()) {
2632  if (empty($options['target'])) {
2633    $options['target'] = NULL;
2634  }
2635  Database::closeConnection($options['target']);
2636}
2637
2638/**
2639 * Retrieves a unique id.
2640 *
2641 * Use this function if for some reason you can't use a serial field. Using a
2642 * serial field is preferred, and InsertQuery::execute() returns the value of
2643 * the last ID inserted.
2644 *
2645 * @param $existing_id
2646 *   After a database import, it might be that the sequences table is behind, so
2647 *   by passing in a minimum ID, it can be assured that we never issue the same
2648 *   ID.
2649 *
2650 * @return
2651 *   An integer number larger than any number returned before for this sequence.
2652 */
2653function db_next_id($existing_id = 0) {
2654  return Database::getConnection()->nextId($existing_id);
2655}
2656
2657/**
2658 * Returns a new DatabaseCondition, set to "OR" all conditions together.
2659 *
2660 * @return DatabaseCondition
2661 */
2662function db_or() {
2663  return new DatabaseCondition('OR');
2664}
2665
2666/**
2667 * Returns a new DatabaseCondition, set to "AND" all conditions together.
2668 *
2669 * @return DatabaseCondition
2670 */
2671function db_and() {
2672  return new DatabaseCondition('AND');
2673}
2674
2675/**
2676 * Returns a new DatabaseCondition, set to "XOR" all conditions together.
2677 *
2678 * @return DatabaseCondition
2679 */
2680function db_xor() {
2681  return new DatabaseCondition('XOR');
2682}
2683
2684/**
2685 * Returns a new DatabaseCondition, set to the specified conjunction.
2686 *
2687 * Internal API function call.  The db_and(), db_or(), and db_xor()
2688 * functions are preferred.
2689 *
2690 * @param $conjunction
2691 *   The conjunction to use for query conditions (AND, OR or XOR).
2692 * @return DatabaseCondition
2693 */
2694function db_condition($conjunction) {
2695  return new DatabaseCondition($conjunction);
2696}
2697
2698/**
2699 * @} End of "defgroup database".
2700 */
2701
2702
2703/**
2704 * @addtogroup schemaapi
2705 * @{
2706 */
2707
2708/**
2709 * Creates a new table from a Drupal table definition.
2710 *
2711 * @param $name
2712 *   The name of the table to create.
2713 * @param $table
2714 *   A Schema API table definition array.
2715 */
2716function db_create_table($name, $table) {
2717  return Database::getConnection()->schema()->createTable($name, $table);
2718}
2719
2720/**
2721 * Returns an array of field names from an array of key/index column specifiers.
2722 *
2723 * This is usually an identity function but if a key/index uses a column prefix
2724 * specification, this function extracts just the name.
2725 *
2726 * @param $fields
2727 *   An array of key/index column specifiers.
2728 *
2729 * @return
2730 *   An array of field names.
2731 */
2732function db_field_names($fields) {
2733  return Database::getConnection()->schema()->fieldNames($fields);
2734}
2735
2736/**
2737 * Checks if an index exists in the given table.
2738 *
2739 * @param $table
2740 *   The name of the table in drupal (no prefixing).
2741 * @param $name
2742 *   The name of the index in drupal (no prefixing).
2743 *
2744 * @return
2745 *   TRUE if the given index exists, otherwise FALSE.
2746 */
2747function db_index_exists($table, $name) {
2748  return Database::getConnection()->schema()->indexExists($table, $name);
2749}
2750
2751/**
2752 * Checks if a table exists.
2753 *
2754 * @param $table
2755 *   The name of the table in drupal (no prefixing).
2756 *
2757 * @return
2758 *   TRUE if the given table exists, otherwise FALSE.
2759 */
2760function db_table_exists($table) {
2761  return Database::getConnection()->schema()->tableExists($table);
2762}
2763
2764/**
2765 * Checks if a column exists in the given table.
2766 *
2767 * @param $table
2768 *   The name of the table in drupal (no prefixing).
2769 * @param $field
2770 *   The name of the field.
2771 *
2772 * @return
2773 *   TRUE if the given column exists, otherwise FALSE.
2774 */
2775function db_field_exists($table, $field) {
2776  return Database::getConnection()->schema()->fieldExists($table, $field);
2777}
2778
2779/**
2780 * Finds all tables that are like the specified base table name.
2781 *
2782 * @param $table_expression
2783 *   An SQL expression, for example "simpletest%" (without the quotes).
2784 *   BEWARE: this is not prefixed, the caller should take care of that.
2785 *
2786 * @return
2787 *   Array, both the keys and the values are the matching tables.
2788 */
2789function db_find_tables($table_expression) {
2790  return Database::getConnection()->schema()->findTables($table_expression);
2791}
2792
2793function _db_create_keys_sql($spec) {
2794  return Database::getConnection()->schema()->createKeysSql($spec);
2795}
2796
2797/**
2798 * Renames a table.
2799 *
2800 * @param $table
2801 *   The current name of the table to be renamed.
2802 * @param $new_name
2803 *   The new name for the table.
2804 */
2805function db_rename_table($table, $new_name) {
2806  return Database::getConnection()->schema()->renameTable($table, $new_name);
2807}
2808
2809/**
2810 * Drops a table.
2811 *
2812 * @param $table
2813 *   The table to be dropped.
2814 */
2815function db_drop_table($table) {
2816  return Database::getConnection()->schema()->dropTable($table);
2817}
2818
2819/**
2820 * Adds a new field to a table.
2821 *
2822 * @param $table
2823 *   Name of the table to be altered.
2824 * @param $field
2825 *   Name of the field to be added.
2826 * @param $spec
2827 *   The field specification array, as taken from a schema definition. The
2828 *   specification may also contain the key 'initial'; the newly-created field
2829 *   will be set to the value of the key in all rows. This is most useful for
2830 *   creating NOT NULL columns with no default value in existing tables.
2831 * @param $keys_new
2832 *   Optional keys and indexes specification to be created on the table along
2833 *   with adding the field. The format is the same as a table specification, but
2834 *   without the 'fields' element. If you are adding a type 'serial' field, you
2835 *   MUST specify at least one key or index including it in this array. See
2836 *   db_change_field() for more explanation why.
2837 *
2838 * @see db_change_field()
2839 */
2840function db_add_field($table, $field, $spec, $keys_new = array()) {
2841  return Database::getConnection()->schema()->addField($table, $field, $spec, $keys_new);
2842}
2843
2844/**
2845 * Drops a field.
2846 *
2847 * @param $table
2848 *   The table to be altered.
2849 * @param $field
2850 *   The field to be dropped.
2851 */
2852function db_drop_field($table, $field) {
2853  return Database::getConnection()->schema()->dropField($table, $field);
2854}
2855
2856/**
2857 * Sets the default value for a field.
2858 *
2859 * @param $table
2860 *   The table to be altered.
2861 * @param $field
2862 *   The field to be altered.
2863 * @param $default
2864 *   Default value to be set. NULL for 'default NULL'.
2865 */
2866function db_field_set_default($table, $field, $default) {
2867  return Database::getConnection()->schema()->fieldSetDefault($table, $field, $default);
2868}
2869
2870/**
2871 * Sets a field to have no default value.
2872 *
2873 * @param $table
2874 *   The table to be altered.
2875 * @param $field
2876 *   The field to be altered.
2877 */
2878function db_field_set_no_default($table, $field) {
2879  return Database::getConnection()->schema()->fieldSetNoDefault($table, $field);
2880}
2881
2882/**
2883 * Adds a primary key to a database table.
2884 *
2885 * @param $table
2886 *   Name of the table to be altered.
2887 * @param $fields
2888 *   Array of fields for the primary key.
2889 */
2890function db_add_primary_key($table, $fields) {
2891  return Database::getConnection()->schema()->addPrimaryKey($table, $fields);
2892}
2893
2894/**
2895 * Drops the primary key of a database table.
2896 *
2897 * @param $table
2898 *   Name of the table to be altered.
2899 */
2900function db_drop_primary_key($table) {
2901  return Database::getConnection()->schema()->dropPrimaryKey($table);
2902}
2903
2904/**
2905 * Adds a unique key.
2906 *
2907 * @param $table
2908 *   The table to be altered.
2909 * @param $name
2910 *   The name of the key.
2911 * @param $fields
2912 *   An array of field names.
2913 */
2914function db_add_unique_key($table, $name, $fields) {
2915  return Database::getConnection()->schema()->addUniqueKey($table, $name, $fields);
2916}
2917
2918/**
2919 * Drops a unique key.
2920 *
2921 * @param $table
2922 *   The table to be altered.
2923 * @param $name
2924 *   The name of the key.
2925 */
2926function db_drop_unique_key($table, $name) {
2927  return Database::getConnection()->schema()->dropUniqueKey($table, $name);
2928}
2929
2930/**
2931 * Adds an index.
2932 *
2933 * @param $table
2934 *   The table to be altered.
2935 * @param $name
2936 *   The name of the index.
2937 * @param $fields
2938 *   An array of field names.
2939 */
2940function db_add_index($table, $name, $fields) {
2941  return Database::getConnection()->schema()->addIndex($table, $name, $fields);
2942}
2943
2944/**
2945 * Drops an index.
2946 *
2947 * @param $table
2948 *   The table to be altered.
2949 * @param $name
2950 *   The name of the index.
2951 */
2952function db_drop_index($table, $name) {
2953  return Database::getConnection()->schema()->dropIndex($table, $name);
2954}
2955
2956/**
2957 * Changes a field definition.
2958 *
2959 * IMPORTANT NOTE: To maintain database portability, you have to explicitly
2960 * recreate all indices and primary keys that are using the changed field.
2961 *
2962 * That means that you have to drop all affected keys and indexes with
2963 * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
2964 * To recreate the keys and indices, pass the key definitions as the optional
2965 * $keys_new argument directly to db_change_field().
2966 *
2967 * For example, suppose you have:
2968 * @code
2969 * $schema['foo'] = array(
2970 *   'fields' => array(
2971 *     'bar' => array('type' => 'int', 'not null' => TRUE)
2972 *   ),
2973 *   'primary key' => array('bar')
2974 * );
2975 * @endcode
2976 * and you want to change foo.bar to be type serial, leaving it as the primary
2977 * key. The correct sequence is:
2978 * @code
2979 * db_drop_primary_key('foo');
2980 * db_change_field('foo', 'bar', 'bar',
2981 *   array('type' => 'serial', 'not null' => TRUE),
2982 *   array('primary key' => array('bar')));
2983 * @endcode
2984 *
2985 * The reasons for this are due to the different database engines:
2986 *
2987 * On PostgreSQL, changing a field definition involves adding a new field and
2988 * dropping an old one which causes any indices, primary keys and sequences
2989 * (from serial-type fields) that use the changed field to be dropped.
2990 *
2991 * On MySQL, all type 'serial' fields must be part of at least one key or index
2992 * as soon as they are created. You cannot use
2993 * db_add_{primary_key,unique_key,index}() for this purpose because the ALTER
2994 * TABLE command will fail to add the column without a key or index
2995 * specification. The solution is to use the optional $keys_new argument to
2996 * create the key or index at the same time as field.
2997 *
2998 * You could use db_add_{primary_key,unique_key,index}() in all cases unless you
2999 * are converting a field to be type serial. You can use the $keys_new argument
3000 * in all cases.
3001 *
3002 * @param $table
3003 *   Name of the table.
3004 * @param $field
3005 *   Name of the field to change.
3006 * @param $field_new
3007 *   New name for the field (set to the same as $field if you don't want to
3008 *   change the name).
3009 * @param $spec
3010 *   The field specification for the new field.
3011 * @param $keys_new
3012 *   Optional keys and indexes specification to be created on the table along
3013 *   with changing the field. The format is the same as a table specification
3014 *   but without the 'fields' element.
3015 */
3016function db_change_field($table, $field, $field_new, $spec, $keys_new = array()) {
3017  return Database::getConnection()->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
3018}
3019
3020/**
3021 * @} End of "addtogroup schemaapi".
3022 */
3023
3024/**
3025 * Sets a session variable specifying the lag time for ignoring a slave server.
3026 */
3027function db_ignore_slave() {
3028  $connection_info = Database::getConnectionInfo();
3029  // Only set ignore_slave_server if there are slave servers being used, which
3030  // is assumed if there are more than one.
3031  if (count($connection_info) > 1) {
3032    // Five minutes is long enough to allow the slave to break and resume
3033    // interrupted replication without causing problems on the Drupal site from
3034    // the old data.
3035    $duration = variable_get('maximum_replication_lag', 300);
3036    // Set session variable with amount of time to delay before using slave.
3037    $_SESSION['ignore_slave_server'] = REQUEST_TIME + $duration;
3038  }
3039}