2BH5GHzK

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