Club Drupal

<?php

/**

 * @file

 * Core systems for the database layer.

 *

 * Classes required for basic functioning of the database system should be

 * placed in this file.  All utility functions should also be placed in this

 * file only, as they cannot auto-load the way classes can.

 */

/**

 * @defgroup database Database abstraction layer

 * @{

 * Allow the use of different database servers using the same code base.

 *

 * Drupal provides a database abstraction layer to provide developers with

 * the ability to support multiple database servers easily. The intent of

 * this layer is to preserve the syntax and power of SQL as much as possible,

 * but also allow developers a way to leverage more complex functionality in

 * a unified way. It also provides a structured interface for dynamically

 * constructing queries when appropriate, and enforcing security checks and

 * similar good practices.

 *

 * The system is built atop PHP's PDO (PHP Data Objects) database API and

 * inherits much of its syntax and semantics.

 *

 * Most Drupal database SELECT queries are performed by a call to db_query() or

 * db_query_range(). Module authors should also consider using the PagerDefault

 * Extender for queries that return results that need to be presented on

 * multiple pages (see https://drupal.org/node/508796), and the TableSort

 * Extender for generating appropriate queries for sortable tables

 * (see https://drupal.org/node/1848372).

 *

 * For example, one might wish to return a list of the most recent 10 nodes

 * authored by a given user. Instead of directly issuing the SQL query

 * @code

 * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid

 *   ORDER BY n.created DESC LIMIT 0, 10;

 * @endcode

 * one would instead call the Drupal functions:

 * @code

 * $result = db_query_range('SELECT n.nid, n.title, n.created

 *   FROM {node} n WHERE n.uid = :uid

 *   ORDER BY n.created DESC', 0, 10, array(':uid' => $uid));

 * foreach ($result as $record) {

 *   // Perform operations on $record->title, etc. here.

 * }

 * @endcode

 * Curly braces are used around "node" to provide table prefixing via

 * DatabaseConnection::prefixTables(). The explicit use of a user ID is pulled

 * out into an argument passed to db_query() so that SQL injection attacks

 * from user input can be caught and nullified. The LIMIT syntax varies between

 * database servers, so that is abstracted into db_query_range() arguments.

 * Finally, note the PDO-based ability to iterate over the result set using

 * foreach ().

 *

 * All queries are passed as a prepared statement string. A

 * prepared statement is a "template" of a query that omits literal or variable

 * values in favor of placeholders. The values to place into those

 * placeholders are passed separately, and the database driver handles

 * inserting the values into the query in a secure fashion. That means you

 * should never quote or string-escape a value to be inserted into the query.

 *

 * There are two formats for placeholders: named and unnamed. Named placeholders

 * are strongly preferred in all cases as they are more flexible and

 * self-documenting. Named placeholders should start with a colon ":" and can be

 * followed by one or more letters, numbers or underscores.

 *

 * Named placeholders begin with a colon followed by a unique string. Example:

 * @code

 * SELECT nid, title FROM {node} WHERE uid=:uid;

 * @endcode

 *

 * ":uid" is a placeholder that will be replaced with a literal value when

 * the query is executed. A given placeholder label cannot be repeated in a

 * given query, even if the value should be the same. When using named

 * placeholders, the array of arguments to the query must be an associative

 * array where keys are a placeholder label (e.g., :uid) and the value is the

 * corresponding value to use. The array may be in any order.

 *

 * Unnamed placeholders are simply a question mark. Example:

 * @code

 * SELECT nid, title FROM {node} WHERE uid=?;

 * @endcode

 *

 * In this case, the array of arguments must be an indexed array of values to

 * use in the exact same order as the placeholders in the query.

 *

 * Note that placeholders should be a "complete" value. For example, when

 * running a LIKE query the SQL wildcard character, %, should be part of the

 * value, not the query itself. Thus, the following is incorrect:

 * @code

 * SELECT nid, title FROM {node} WHERE title LIKE :title%;

 * @endcode

 * It should instead read:

 * @code

 * SELECT nid, title FROM {node} WHERE title LIKE :title;

 * @endcode

 * and the value for :title should include a % as appropriate. Again, note the

 * lack of quotation marks around :title. Because the value is not inserted

 * into the query as one big string but as an explicitly separate value, the

 * database server knows where the query ends and a value begins. That is

 * considerably more secure against SQL injection than trying to remember

 * which values need quotation marks and string escaping and which don't.

 *

 * INSERT, UPDATE, and DELETE queries need special care in order to behave

 * consistently across all different databases. Therefore, they use a special

 * object-oriented API for defining a query structurally. For example, rather

 * than:

 * @code

 * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');

 * @endcode

 * one would instead write:

 * @code

 * $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');

 * db_insert('node')->fields($fields)->execute();

 * @endcode

 * This method allows databases that need special data type handling to do so,

 * while also allowing optimizations such as multi-insert queries. UPDATE and

 * DELETE queries have a similar pattern.

 *

 * Drupal also supports transactions, including a transparent fallback for

 * databases that do not support transactions. To start a new transaction,

 * simply call $txn = db_transaction(); in your own code. The transaction will

 * remain open for as long as the variable $txn remains in scope.  When $txn is

 * destroyed, the transaction will be committed.  If your transaction is nested

 * inside of another then Drupal will track each transaction and only commit

 * the outer-most transaction when the last transaction object goes out out of

 * scope, that is, all relevant queries completed successfully.

 *

 * Example:

 * @code

 * function my_transaction_function() {

 *   // The transaction opens here.

 *   $txn = db_transaction();

 *

 *   try {

 *     $id = db_insert('example')

 *       ->fields(array(

 *         'field1' => 'mystring',

 *         'field2' => 5,

 *       ))

 *       ->execute();

 *

 *     my_other_function($id);

 *

 *     return $id;

 *   }

 *   catch (Exception $e) {

 *     // Something went wrong somewhere, so roll back now.

 *     $txn->rollback();

 *     // Log the exception to watchdog.

 *     watchdog_exception('type', $e);

 *   }

 *

 *   // $txn goes out of scope here.  Unless the transaction was rolled back, it

 *   // gets automatically committed here.

 * }

 *

 * function my_other_function($id) {

 *   // The transaction is still open here.

 *

 *   if ($id % 2 == 0) {

 *     db_update('example')

 *       ->condition('id', $id)

 *       ->fields(array('field2' => 10))

 *       ->execute();

 *   }

 * }

 * @endcode

 *

 * @see http://drupal.org/developing/api/database

 */

/**

 * Base Database API class.

 *

 * This class provides a Drupal-specific extension of the PDO database

 * abstraction class in PHP. Every database driver implementation must provide a

 * concrete implementation of it to support special handling required by that

 * database.

 *

 * @see http://php.net/manual/book.pdo.php

 */

abstract class DatabaseConnection extends PDO {

  /**

   * The database target this connection is for.

   *

   * We need this information for later auditing and logging.

   *

   * @var string

   */

  protected $target = NULL;

  /**

   * The key representing this connection.

   *

   * The key is a unique string which identifies a database connection. A

   * connection can be a single server or a cluster of master and slaves (use

   * target to pick between master and slave).

   *

   * @var string

   */

  protected $key = NULL;

  /**

   * The current database logging object for this connection.

   *

   * @var DatabaseLog

   */

  protected $logger = NULL;

  /**

   * Tracks the number of "layers" of transactions currently active.

   *

   * On many databases transactions cannot nest.  Instead, we track

   * nested calls to transactions and collapse them into a single

   * transaction.

   *

   * @var array

   */

  protected $transactionLayers = array();

  /**

   * Index of what driver-specific class to use for various operations.

   *

   * @var array

   */

  protected $driverClasses = array();

  /**

   * The name of the Statement class for this connection.

   *

   * @var string

   */

  protected $statementClass = 'DatabaseStatementBase';

  /**

   * Whether this database connection supports transactions.

   *

   * @var bool

   */

  protected $transactionSupport = TRUE;

  /**

   * Whether this database connection supports transactional DDL.

   *

   * Set to FALSE by default because few databases support this feature.

   *

   * @var bool

   */

  protected $transactionalDDLSupport = FALSE;

  /**

   * An index used to generate unique temporary table names.

   *

   * @var integer

   */

  protected $temporaryNameIndex = 0;

  /**

   * The connection information for this connection object.

   *

   * @var array

   */

  protected $connectionOptions = array();

  /**

   * The schema object for this connection.

   *

   * @var object

   */

  protected $schema = NULL;

  /**

   * The prefixes used by this database connection.

   *

   * @var array

   */

  protected $prefixes = array();

  /**

   * List of search values for use in prefixTables().

   *

   * @var array

   */

  protected $prefixSearch = array();

  /**

   * List of replacement values for use in prefixTables().

   *

   * @var array

   */

  protected $prefixReplace = array();

  function __construct($dsn, $username, $password, $driver_options = array()) {

    // Initialize and prepare the connection prefix.

    $this->setPrefix(isset($this->connectionOptions['prefix']) ? $this->connectionOptions['prefix'] : '');

    // Because the other methods don't seem to work right.

    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;

    // Call PDO::__construct and PDO::setAttribute.

    parent::__construct($dsn, $username, $password, $driver_options);

    // Set a Statement class, unless the driver opted out.

    if (!empty($this->statementClass)) {

      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));

    }

  }

  /**

   * Destroys this Connection object.

   *

   * PHP does not destruct an object if it is still referenced in other

   * variables. In case of PDO database connection objects, PHP only closes the

   * connection when the PDO object is destructed, so any references to this

   * object may cause the number of maximum allowed connections to be exceeded.

   */

  public function destroy() {

    // Destroy all references to this connection by setting them to NULL.

    // The Statement class attribute only accepts a new value that presents a

    // proper callable, so we reset it to PDOStatement.

    $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));

    $this->schema = NULL;

  }

  /**

   * Returns the default query options for any given query.

   *

   * A given query can be customized with a number of option flags in an

   * associative array:

   * - target: The database "target" against which to execute a query. Valid

   *   values are "default" or "slave". The system will first try to open a

   *   connection to a database specified with the user-supplied key. If one

   *   is not available, it will silently fall back to the "default" target.

   *   If multiple databases connections are specified with the same target,

   *   one will be selected at random for the duration of the request.

   * - fetch: This element controls how rows from a result set will be

   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,

   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a

   *   class. If a string is specified, each record will be fetched into a new

   *   object of that class. The behavior of all other values is defined by PDO.

   *   See http://php.net/manual/pdostatement.fetch.php

   * - return: Depending on the type of query, different return values may be

   *   meaningful. This directive instructs the system which type of return

   *   value is desired. The system will generally set the correct value

   *   automatically, so it is extremely rare that a module developer will ever

   *   need to specify this value. Setting it incorrectly will likely lead to

   *   unpredictable results or fatal errors. Legal values include:

   *   - Database::RETURN_STATEMENT: Return the prepared statement object for

   *     the query. This is usually only meaningful for SELECT queries, where

   *     the statement object is how one accesses the result set returned by the

   *     query.

   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an

   *     UPDATE or DELETE query. Be aware that means the number of rows actually

   *     changed, not the number of rows matched by the WHERE clause.

   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)

   *     created by an INSERT statement on a table that contains a serial

   *     column.

   *   - Database::RETURN_NULL: Do not return anything, as there is no

   *     meaningful value to return. That is the case for INSERT queries on

   *     tables that do not contain a serial column.

   * - throw_exception: By default, the database system will catch any errors

   *   on a query as an Exception, log it, and then rethrow it so that code

   *   further up the call chain can take an appropriate action. To suppress

   *   that behavior and simply return NULL on failure, set this option to

   *   FALSE.

   *

   * @return

   *   An array of default query options.

   */

  protected function defaultOptions() {

    return array(

      'target' => 'default',

      'fetch' => PDO::FETCH_OBJ,

      'return' => Database::RETURN_STATEMENT,

      'throw_exception' => TRUE,

    );

  }

  /**

   * Returns the connection information for this connection object.

   *

   * Note that Database::getConnectionInfo() is for requesting information

   * about an arbitrary database connection that is defined. This method

   * is for requesting the connection information of this specific

   * open connection object.

   *

   * @return

   *   An array of the connection information. The exact list of

   *   properties is driver-dependent.

   */

  public function getConnectionOptions() {

    return $this->connectionOptions;

  }

  /**

   * Set the list of prefixes used by this database connection.

   *

   * @param $prefix

   *   The prefixes, in any of the multiple forms documented in

   *   default.settings.php.

   */

  protected function setPrefix($prefix) {

    if (is_array($prefix)) {

      $this->prefixes = $prefix + array('default' => '');

    }

    else {

      $this->prefixes = array('default' => $prefix);

    }

    // Set up variables for use in prefixTables(). Replace table-specific

    // prefixes first.

    $this->prefixSearch = array();

    $this->prefixReplace = array();

    foreach ($this->prefixes as $key => $val) {

      if ($key != 'default') {

        $this->prefixSearch[] = '{' . $key . '}';

        $this->prefixReplace[] = $val . $key;

      }

    }

    // Then replace remaining tables with the default prefix.

    $this->prefixSearch[] = '{';

    $this->prefixReplace[] = $this->prefixes['default'];

    $this->prefixSearch[] = '}';

    $this->prefixReplace[] = '';

  }

  /**

   * Appends a database prefix to all tables in a query.

   *

   * Queries sent to Drupal should wrap all table names in curly brackets. This

   * function searches for this syntax and adds Drupal's table prefix to all

   * tables, allowing Drupal to coexist with other systems in the same database

   * and/or schema if necessary.

   *

   * @param $sql

   *   A string containing a partial or entire SQL query.

   *

   * @return

   *   The properly-prefixed string.

   */

  public function prefixTables($sql) {

    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);

  }

  /**

   * Find the prefix for a table.

   *

   * This function is for when you want to know the prefix of a table. This

   * is not used in prefixTables due to performance reasons.

   */

  public function tablePrefix($table = 'default') {

    if (isset($this->prefixes[$table])) {

      return $this->prefixes[$table];

    }

    else {

      return $this->prefixes['default'];

    }

  }

  /**

   * Prepares a query string and returns the prepared statement.

   *

   * This method caches prepared statements, reusing them when

   * possible. It also prefixes tables names enclosed in curly-braces.

   *

   * @param $query

   *   The query string as SQL, with curly-braces surrounding the

   *   table names.

   *

   * @return DatabaseStatementInterface

   *   A PDO prepared statement ready for its execute() method.

   */

  public function prepareQuery($query) {

    $query = $this->prefixTables($query);

    // Call PDO::prepare.

    return parent::prepare($query);

  }

  /**

   * Tells this connection object what its target value is.

   *

   * This is needed for logging and auditing. It's sloppy to do in the

   * constructor because the constructor for child classes has a different

   * signature. We therefore also ensure that this function is only ever

   * called once.

   *

   * @param $target

   *   The target this connection is for. Set to NULL (default) to disable

   *   logging entirely.

   */

  public function setTarget($target = NULL) {

    if (!isset($this->target)) {

      $this->target = $target;

    }

  }

  /**

   * Returns the target this connection is associated with.

   *

   * @return

   *   The target string of this connection.

   */

  public function getTarget() {

    return $this->target;

  }

  /**

   * Tells this connection object what its key is.

   *

   * @param $target

   *   The key this connection is for.

   */

  public function setKey($key) {

    if (!isset($this->key)) {

      $this->key = $key;

    }

  }

  /**

   * Returns the key this connection is associated with.

   *

   * @return

   *   The key of this connection.

   */

  public function getKey() {

    return $this->key;

  }

  /**

   * Associates a logging object with this connection.

   *

   * @param $logger

   *   The logging object we want to use.

   */

  public function setLogger(DatabaseLog $logger) {

    $this->logger = $logger;

  }

  /**

   * Gets the current logging object for this connection.

   *

   * @return DatabaseLog

   *   The current logging object for this connection. If there isn't one,

   *   NULL is returned.

   */

  public function getLogger() {

    return $this->logger;

  }

  /**

   * Creates the appropriate sequence name for a given table and serial field.

   *

   * This information is exposed to all database drivers, although it is only

   * useful on some of them. This method is table prefix-aware.

   *

   * @param $table

   *   The table name to use for the sequence.

   * @param $field

   *   The field name to use for the sequence.

   *

   * @return

   *   A table prefix-parsed string for the sequence name.

   */

  public function makeSequenceName($table, $field) {

    return $this->prefixTables('{' . $table . '}_' . $field . '_seq');

  }

  /**

   * Flatten an array of query comments into a single comment string.

   *

   * The comment string will be sanitized to avoid SQL injection attacks.

   *

   * @param $comments

   *   An array of query comment strings.

   *

   * @return

   *   A sanitized comment string.

   */

  public function makeComment($comments) {

    if (empty($comments))

      return '';

    // Flatten the array of comments.

    $comment = implode('; ', $comments);

    // Sanitize the comment string so as to avoid SQL injection attacks.

    return '/* ' . $this->filterComment($comment) . ' */ ';

  }

  /**

   * Sanitize a query comment string.

   *

   * Ensure a query comment does not include strings such as "* /" that might

   * terminate the comment early. This avoids SQL injection attacks via the

   * query comment. The comment strings in this example are separated by a

   * space to avoid PHP parse errors.

   *

   * For example, the comment:

   * @code

   * db_update('example')

   *  ->condition('id', $id)

   *  ->fields(array('field2' => 10))

   *  ->comment('Exploit * / DROP TABLE node; --')

   *  ->execute()

   * @endcode

   *

   * Would result in the following SQL statement being generated:

   * @code

   * "/ * Exploit * / DROP TABLE node; -- * / UPDATE example SET field2=..."

   * @endcode

   *

   * Unless the comment is sanitised first, the SQL server would drop the

   * node table and ignore the rest of the SQL statement.

   *

   * @param $comment

   *   A query comment string.

   *

   * @return

   *   A sanitized version of the query comment string.

   */

  protected function filterComment($comment = '') {

    return preg_replace('/(\/\*\s*)|(\s*\*\/)/', '', $comment);

  }

  /**

   * Executes a query string against the database.

   *

   * This method provides a central handler for the actual execution of every

   * query. All queries executed by Drupal are executed as PDO prepared

   * statements.

   *

   * @param $query

   *   The query to execute. In most cases this will be a string containing

   *   an SQL query with placeholders. An already-prepared instance of

   *   DatabaseStatementInterface may also be passed in order to allow calling

   *   code to manually bind variables to a query. If a

   *   DatabaseStatementInterface is passed, the $args array will be ignored.

   *   It is extremely rare that module code will need to pass a statement

   *   object to this method. It is used primarily for database drivers for

   *   databases that require special LOB field handling.

   * @param $args

   *   An array of arguments for the prepared statement. If the prepared

   *   statement uses ? placeholders, this array must be an indexed array.

   *   If it contains named placeholders, it must be an associative array.

   * @param $options

   *   An associative array of options to control how the query is run. See

   *   the documentation for DatabaseConnection::defaultOptions() for details.

   *

   * @return DatabaseStatementInterface

   *   This method will return one of: the executed statement, the number of

   *   rows affected by the query (not the number matched), or the generated

   *   insert IT of the last query, depending on the value of

   *   $options['return']. Typically that value will be set by default or a

   *   query builder and should not be set by a user. If there is an error,

   *   this method will return NULL and may throw an exception if

   *   $options['throw_exception'] is TRUE.

   *

   * @throws PDOException

   */

  public function query($query, array $args = array(), $options = array()) {

    // Use default values if not already set.

    $options += $this->defaultOptions();

    try {

      // We allow either a pre-bound statement object or a literal string.

      // In either case, we want to end up with an executed statement object,

      // which we pass to PDOStatement::execute.

      if ($query instanceof DatabaseStatementInterface) {

        $stmt = $query;

        $stmt->execute(NULL, $options);

      }

      else {

        $this->expandArguments($query, $args);

        $stmt = $this->prepareQuery($query);

        $stmt->execute($args, $options);

      }

      // Depending on the type of query we may need to return a different value.

      // See DatabaseConnection::defaultOptions() for a description of each

      // value.

      switch ($options['return']) {

        case Database::RETURN_STATEMENT:

          return $stmt;

        case Database::RETURN_AFFECTED:

          return $stmt->rowCount();

        case Database::RETURN_INSERT_ID:

          return $this->lastInsertId();

        case Database::RETURN_NULL:

          return;

        default:

          throw new PDOException('Invalid return directive: ' . $options['return']);

      }

    }

    catch (PDOException $e) {

      if ($options['throw_exception']) {

        // Add additional debug information.

        if ($query instanceof DatabaseStatementInterface) {

          $e->query_string = $stmt->getQueryString();

        }

        else {

          $e->query_string = $query;

        }

        $e->args = $args;

        throw $e;

      }

      return NULL;

    }

  }

  /**

   * Expands out shorthand placeholders.

   *

   * Drupal supports an alternate syntax for doing arrays of values. We

   * therefore need to expand them out into a full, executable query string.

   *

   * @param $query

   *   The query string to modify.

   * @param $args

   *   The arguments for the query.

   *

   * @return

   *   TRUE if the query was modified, FALSE otherwise.

   */

  protected function expandArguments(&$query, &$args) {

    $modified = FALSE;

    // If the placeholder value to insert is an array, assume that we need

    // to expand it out into a comma-delimited set of placeholders.

    foreach (array_filter($args, 'is_array') as $key => $data) {

      $new_keys = array();

      foreach (array_values($data) as $i => $value) {

        // This assumes that there are no other placeholders that use the same

        // name.  For example, if the array placeholder is defined as :example

        // and there is already an :example_2 placeholder, this will generate

        // a duplicate key.  We do not account for that as the calling code

        // is already broken if that happens.

        $new_keys[$key . '_' . $i] = $value;

      }

      // Update the query with the new placeholders.

      // preg_replace is necessary to ensure the replacement does not affect

      // placeholders that start with the same exact text. For example, if the

      // query contains the placeholders :foo and :foobar, and :foo has an

      // array of values, using str_replace would affect both placeholders,

      // but using the following preg_replace would only affect :foo because

      // it is followed by a non-word character.

      $query = preg_replace('#' . $key . '\b#', implode(', ', array_keys($new_keys)), $query);

      // Update the args array with the new placeholders.

      unset($args[$key]);

      $args += $new_keys;

      $modified = TRUE;

    }

    return $modified;

  }

  /**

   * Gets the driver-specific override class if any for the specified class.

   *

   * @param string $class

   *   The class for which we want the potentially driver-specific class.

   * @param array $files

   *   The name of the files in which the driver-specific class can be.

   * @param $use_autoload

   *   If TRUE, attempt to load classes using PHP's autoload capability

   *   as well as the manual approach here.

   * @return string

   *   The name of the class that should be used for this driver.

   */

  public function getDriverClass($class, array $files = array(), $use_autoload = FALSE) {

    if (empty($this->driverClasses[$class])) {

      $driver = $this->driver();

      $this->driverClasses[$class] = $class . '_' . $driver;

      Database::loadDriverFile($driver, $files);

      if (!class_exists($this->driverClasses[$class], $use_autoload)) {

        $this->driverClasses[$class] = $class;

      }

    }

    return $this->driverClasses[$class];

  }

  /**

   * Prepares and returns a SELECT query object.

   *

   * @param $table

   *   The base table for this query, that is, the first table in the FROM

   *   clause. This table will also be used as the "base" table for query_alter

   *   hook implementations.

   * @param $alias

   *   The alias of the base table of this query.

   * @param $options

   *   An array of options on the query.

   *

   * @return SelectQueryInterface

   *   An appropriate SelectQuery object for this database connection. Note that

   *   it may be a driver-specific subclass of SelectQuery, depending on the

   *   driver.

   *

   * @see SelectQuery

   */

  public function select($table, $alias = NULL, array $options = array()) {

    $class = $this->getDriverClass('SelectQuery', array('query.inc', 'select.inc'));

    return new $class($table, $alias, $this, $options);

  }

  /**

   * Prepares and returns an INSERT query object.

   *

   * @param $options

   *   An array of options on the query.

   *

   * @return InsertQuery

   *   A new InsertQuery object.

   *

   * @see InsertQuery

   */

  public function insert($table, array $options = array()) {

    $class = $this->getDriverClass('InsertQuery', array('query.inc'));

    return new $class($this, $table, $options);

  }

  /**

   * Prepares and returns a MERGE query object.

   *

   * @param $options

   *   An array of options on the query.

   *

   * @return MergeQuery

   *   A new MergeQuery object.

   *

   * @see MergeQuery

   */

  public function merge($table, array $options = array()) {

    $class = $this->getDriverClass('MergeQuery', array('query.inc'));

    return new $class($this, $table, $options);

  }

  /**

   * Prepares and returns an UPDATE query object.

   *

   * @param $options

   *   An array of options on the query.

   *

   * @return UpdateQuery

   *   A new UpdateQuery object.

   *

   * @see UpdateQuery

   */

  public function update($table, array $options = array()) {

    $class = $this->getDriverClass('UpdateQuery', array('query.inc'));

    return new $class($this, $table, $options);

  }

  /**

   * Prepares and returns a DELETE query object.

   *

   * @param $options

   *   An array of options on the query.

   *

   * @return DeleteQuery

   *   A new DeleteQuery object.

   *

   * @see DeleteQuery

   */

  public function delete($table, array $options = array()) {

    $class = $this->getDriverClass('DeleteQuery', array('query.inc'));

    return new $class($this, $table, $options);

  }

  /**

   * Prepares and returns a TRUNCATE query object.

   *

   * @param $options

   *   An array of options on the query.

   *

   * @return TruncateQuery

   *   A new TruncateQuery object.

   *

   * @see TruncateQuery

   */

  public function truncate($table, array $options = array()) {

    $class = $this->getDriverClass('TruncateQuery', array('query.inc'));

    return new $class($this, $table, $options);

  }

  /**

   * Returns a DatabaseSchema object for manipulating the schema.

   *

   * This method will lazy-load the appropriate schema library file.

   *

   * @return DatabaseSchema

   *   The DatabaseSchema object for this connection.

   */

  public function schema() {

    if (empty($this->schema)) {

      $class = $this->getDriverClass('DatabaseSchema', array('schema.inc'));

      if (class_exists($class)) {

        $this->schema = new $class($this);

      }

    }

    return $this->schema;

  }

  /**

   * Escapes a table name string.

   *

   * Force all table names to be strictly alphanumeric-plus-underscore.

   * For some database drivers, it may also wrap the table name in

   * database-specific escape characters.

   *

   * @return

   *   The sanitized table name string.

   */

  public function escapeTable($table) {

    return preg_replace('/[^A-Za-z0-9_.]+/', '', $table);

  }

  /**

   * Escapes a field name string.

   *

   * Force all field names to be strictly alphanumeric-plus-underscore.

   * For some database drivers, it may also wrap the field name in

   * database-specific escape characters.

   *

   * @return

   *   The sanitized field name string.

   */

  public function escapeField($field) {

    return preg_replace('/[^A-Za-z0-9_.]+/', '', $field);

  }

  /**

   * Escapes an alias name string.

   *

   * Force all alias names to be strictly alphanumeric-plus-underscore. In

   * contrast to DatabaseConnection::escapeField() /

   * DatabaseConnection::escapeTable(), this doesn't allow the period (".")

   * because that is not allowed in aliases.

   *

   * @return

   *   The sanitized field name string.

   */

  public function escapeAlias($field) {

    return preg_replace('/[^A-Za-z0-9_]+/', '', $field);

  }

  /**

   * Escapes characters that work as wildcard characters in a LIKE pattern.

   *

   * The wildcard characters "%" and "_" as well as backslash are prefixed with

   * a backslash. Use this to do a search for a verbatim string without any

   * wildcard behavior.

   *

   * For example, the following does a case-insensitive query for all rows whose

   * name starts with $prefix:

   * @code

   * $result = db_query(

   *   'SELECT * FROM person WHERE name LIKE :pattern',

   *   array(':pattern' => db_like($prefix) . '%')

   * );

   * @endcode

   *

   * Backslash is defined as escape character for LIKE patterns in

   * DatabaseCondition::mapConditionOperator().

   *

   * @param $string

   *   The string to escape.

   *

   * @return

   *   The escaped string.

   */

  public function escapeLike($string) {

    return addcslashes($string, '\%_');

  }

  /**

   * Determines if there is an active transaction open.

   *

   * @return

   *   TRUE if we're currently in a transaction, FALSE otherwise.

   */

  public function inTransaction() {

    return ($this->transactionDepth() > 0);

  }

  /**

   * Determines current transaction depth.

   */

  public function transactionDepth() {

    return count($this->transactionLayers);

  }

  /**

   * Returns a new DatabaseTransaction object on this connection.

   *

   * @param $name

   *   Optional name of the savepoint.

   *

   * @return DatabaseTransaction

   *   A DatabaseTransaction object.

   *

   * @see DatabaseTransaction

   */

  public function startTransaction($name = '') {

    $class = $this->getDriverClass('DatabaseTransaction');

    return new $class($this, $name);

  }

  /**

   * Rolls back the transaction entirely or to a named savepoint.

   *

   * This method throws an exception if no transaction is active.

   *

   * @param $savepoint_name

   *   The name of the savepoint. The default, 'drupal_transaction', will roll

   *   the entire transaction back.

   *

   * @throws DatabaseTransactionNoActiveException

   *

   * @see DatabaseTransaction::rollback()

   */

  public function rollback($savepoint_name = 'drupal_transaction') {

    if (!$this->supportsTransactions()) {

      return;

    }

    if (!$this->inTransaction()) {

      throw new DatabaseTransactionNoActiveException();

    }

    // A previous rollback to an earlier savepoint may mean that the savepoint

    // in question has already been accidentally committed.

    if (!isset($this->transactionLayers[$savepoint_name])) {

      throw new DatabaseTransactionNoActiveException();

    }

    // We need to find the point we're rolling back to, all other savepoints

    // before are no longer needed. If we rolled back other active savepoints,

    // we need to throw an exception.

    $rolled_back_other_active_savepoints = FALSE;

    while ($savepoint = array_pop($this->transactionLayers)) {

      if ($savepoint == $savepoint_name) {

        // If it is the last the transaction in the stack, then it is not a

        // savepoint, it is the transaction itself so we will need to roll back

        // the transaction rather than a savepoint.

        if (empty($this->transactionLayers)) {

          break;

        }

        $this->query('ROLLBACK TO SAVEPOINT ' . $savepoint);

        $this->popCommittableTransactions();

        if ($rolled_back_other_active_savepoints) {

          throw new DatabaseTransactionOutOfOrderException();

        }

        return;

      }

      else {

        $rolled_back_other_active_savepoints = TRUE;

      }

    }

    parent::rollBack();

    if ($rolled_back_other_active_savepoints) {

      throw new DatabaseTransactionOutOfOrderException();

    }

  }

  /**

   * Increases the depth of transaction nesting.

   *

   * If no transaction is already active, we begin a new transaction.

   *

   * @throws DatabaseTransactionNameNonUniqueException

   *

   * @see DatabaseTransaction

   */

  public function pushTransaction($name) {

    if (!$this->supportsTransactions()) {

      return;

    }

    if (isset($this->transactionLayers[$name])) {

      throw new DatabaseTransactionNameNonUniqueException($name . " is already in use.");

    }

    // If we're already in a transaction then we want to create a savepoint

    // rather than try to create another transaction.

    if ($this->inTransaction()) {

      $this->query('SAVEPOINT ' . $name);

    }

    else {

      parent::beginTransaction();

    }

    $this->transactionLayers[$name] = $name;

  }

  /**

   * Decreases the depth of transaction nesting.

   *

   * If we pop off the last transaction layer, then we either commit or roll

   * back the transaction as necessary. If no transaction is active, we return

   * because the transaction may have manually been rolled back.

   *

   * @param $name

   *   The name of the savepoint

   *

   * @throws DatabaseTransactionNoActiveException

   * @throws DatabaseTransactionCommitFailedException

   *

   * @see DatabaseTransaction

   */

  public function popTransaction($name) {

    if (!$this->supportsTransactions()) {

      return;

    }

    // The transaction has already been committed earlier. There is nothing we

    // need to do. If this transaction was part of an earlier out-of-order

    // rollback, an exception would already have been thrown by

    // Database::rollback().

    if (!isset($this->transactionLayers[$name])) {

      return;

    }

    // Mark this layer as committable.

    $this->transactionLayers[$name] = FALSE;

    $this->popCommittableTransactions();

  }

  /**

   * Internal function: commit all the transaction layers that can commit.

   */

  protected function popCommittableTransactions() {

    // Commit all the committable layers.

    foreach (array_reverse($this->transactionLayers) as $name => $active) {

      // Stop once we found an active transaction.

      if ($active) {

        break;

      }

      // If there are no more layers left then we should commit.

      unset($this->transactionLayers[$name]);

      if (empty($this->transactionLayers)) {

        if (!parent::commit()) {

          throw new DatabaseTransactionCommitFailedException();

        }

      }

      else {

        $this->query('RELEASE SAVEPOINT ' . $name);

      }

    }

  }

  /**

   * Runs a limited-range query on this database object.

   *

   * Use this as a substitute for ->query() when a subset of the query is to be

   * returned. User-supplied arguments to the query should be passed in as

   * separate parameters so that they can be properly escaped to avoid SQL

   * injection attacks.

   *

   * @param $query

   *   A string containing an SQL query.

   * @param $args

   *   An array of values to substitute into the query at placeholder markers.

   * @param $from

   *   The first result row to return.

   * @param $count

   *   The maximum number of result rows to return.

   * @param $options

   *   An array of options on the query.

   *

   * @return DatabaseStatementInterface

   *   A database query result resource, or NULL if the query was not executed

   *   correctly.

   */

  abstract public function queryRange($query, $from, $count, array $args = array(), array $options = array());

  /**

   * Generates a temporary table name.

   *

   * @return

   *   A table name.

   */

  protected function generateTemporaryTableName() {

    return "db_temporary_" . $this->temporaryNameIndex++;

  }

  /**

   * Runs a SELECT query and stores its results in a temporary table.

   *

   * Use this as a substitute for ->query() when the results need to stored

   * in a temporary table. Temporary tables exist for the duration of the page

   * request. User-supplied arguments to the query should be passed in as

   * separate parameters so that they can be properly escaped to avoid SQL

   * injection attacks.

   *

   * Note that if you need to know how many results were returned, you should do

   * a SELECT COUNT(*) on the temporary table afterwards.

   *

   * @param $query

   *   A string containing a normal SELECT SQL query.

   * @param $args

   *   An array of values to substitute into the query at placeholder markers.

   * @param $options

   *   An associative array of options to control how the query is run. See

   *   the documentation for DatabaseConnection::defaultOptions() for details.

   *

   * @return

   *   The name of the temporary table.

   */

  abstract function queryTemporary($query, array $args = array(), array $options = array());

  /**

   * Returns the type of database driver.

   *

   * This is not necessarily the same as the type of the database itself. For

   * instance, there could be two MySQL drivers, mysql and mysql_mock. This

   * function would return different values for each, but both would return

   * "mysql" for databaseType().

   */

  abstract public function driver();

  /**

   * Returns the version of the database server.

   */

  public function version() {

    return $this->getAttribute(PDO::ATTR_SERVER_VERSION);

  }

  /**

   * Determines if this driver supports transactions.

   *

   * @return

   *   TRUE if this connection supports transactions, FALSE otherwise.

   */

  public function supportsTransactions() {

    return $this->transactionSupport;

  }

  /**

   * Determines if this driver supports transactional DDL.

   *

   * DDL queries are those that change the schema, such as ALTER queries.

   *

   * @return

   *   TRUE if this connection supports transactions for DDL queries, FALSE

   *   otherwise.

   */

  public function supportsTransactionalDDL() {

    return $this->transactionalDDLSupport;

  }

  /**

   * Returns the name of the PDO driver for this connection.

   */

  abstract public function databaseType();

  /**

   * Gets any special processing requirements for the condition operator.

   *

   * Some condition types require special processing, such as IN, because

   * the value data they pass in is not a simple value. This is a simple

   * overridable lookup function. Database connections should define only

   * those operators they wish to be handled differently than the default.

   *

   * @param $operator

   *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.

   *

   * @return

   *   The extra handling directives for the specified operator, or NULL.

   *

   * @see DatabaseCondition::compile()

   */

  abstract public function mapConditionOperator($operator);

  /**

   * Throws an exception to deny direct access to transaction commits.

   *

   * We do not want to allow users to commit transactions at any time, only

   * by destroying the transaction object or allowing it to go out of scope.

   * A direct commit bypasses all of the safety checks we've built on top of

   * PDO's transaction routines.

   *

   * @throws DatabaseTransactionExplicitCommitNotAllowedException

   *

   * @see DatabaseTransaction

   */

  public function commit() {

    throw new DatabaseTransactionExplicitCommitNotAllowedException();

  }

  /**

   * Retrieves an unique id from a given sequence.

   *

   * Use this function if for some reason you can't use a serial field. For

   * example, MySQL has no ways of reading of the current value of a sequence

   * and PostgreSQL can not advance the sequence to be larger than a given

   * value. Or sometimes you just need a unique integer.

   *

   * @param $existing_id

   *   After a database import, it might be that the sequences table is behind,

   *   so by passing in the maximum existing id, it can be assured that we

   *   never issue the same id.

   *

   * @return

   *   An integer number larger than any number returned by earlier calls and

   *   also larger than the $existing_id if one was passed in.

   */

  abstract public function nextId($existing_id = 0);

}

/**

 * Primary front-controller for the database system.

 *

 * This class is uninstantiatable and un-extendable. It acts to encapsulate

 * all control and shepherding of database connections into a single location

 * without the use of globals.

 */

abstract class Database {

  /**

   * Flag to indicate a query call should simply return NULL.

   *

   * This is used for queries that have no reasonable return value anyway, such

   * as INSERT statements to a table without a serial primary key.

   */

  const RETURN_NULL = 0;

  /**

   * Flag to indicate a query call should return the prepared statement.

   */

  const RETURN_STATEMENT = 1;

  /**

   * Flag to indicate a query call should return the number of affected rows.

   */

  const RETURN_AFFECTED = 2;

  /**

   * Flag to indicate a query call should return the "last insert id".

   */

  const RETURN_INSERT_ID = 3;

  /**

   * An nested array of all active connections. It is keyed by database name

   * and target.

   *

   * @var array

   */

  static protected $connections = array();

  /**

   * A processed copy of the database connection information from settings.php.

   *

   * @var array

   */

  static protected $databaseInfo = NULL;

  /**

   * A list of key/target credentials to simply ignore.

   *

   * @var array

   */

  static protected $ignoreTargets = array();

  /**

   * The key of the currently active database connection.

   *

   * @var string

   */

  static protected $activeKey = 'default';

  /**

   * An array of active query log objects.

   *

   * Every connection has one and only one logger object for all targets and

   * logging keys.

   *

   * array(

   *   '$db_key' => DatabaseLog object.

   * );

   *

   * @var array

   */

  static protected $logs = array();

  /**

   * Starts logging a given logging key on the specified connection.

   *

   * @param $logging_key

   *   The logging key to log.

   * @param $key

   *   The database connection key for which we want to log.

   *

   * @return DatabaseLog

   *   The query log object. Note that the log object does support richer

   *   methods than the few exposed through the Database class, so in some

   *   cases it may be desirable to access it directly.

   *

   * @see DatabaseLog

   */

  final public static function startLog($logging_key, $key = 'default') {

    if (empty(self::$logs[$key])) {

      self::$logs[$key] = new DatabaseLog($key);

      // Every target already active for this connection key needs to have the

      // logging object associated with it.

      if (!empty(self::$connections[$key])) {

        foreach (self::$connections[$key] as $connection) {

          $connection->setLogger(self::$logs[$key]);

        }

      }

    }

    self::$logs[$key]->start($logging_key);

    return self::$logs[$key];

  }

  /**

   * Retrieves the queries logged on for given logging key.

   *

   * This method also ends logging for the specified key. To get the query log

   * to date without ending the logger request the logging object by starting

   * it again (which does nothing to an open log key) and call methods on it as

   * desired.

   *

   * @param $logging_key

   *   The logging key to log.

   * @param $key

   *   The database connection key for which we want to log.

   *

   * @return array

   *   The query log for the specified logging key and connection.

   *

   * @see DatabaseLog

   */

  final public static function getLog($logging_key, $key = 'default') {

    if (empty(self::$logs[$key])) {

      return NULL;

    }

    $queries = self::$logs[$key]->get($logging_key);

    self::$logs[$key]->end($logging_key);

    return $queries;

  }

  /**

   * Gets the connection object for the specified database key and target.

   *

   * @param $target

   *   The database target name.

   * @param $key

   *   The database connection key. Defaults to NULL which means the active key.

   *

   * @return DatabaseConnection

   *   The corresponding connection object.

   */

  final public static function getConnection($target = 'default', $key = NULL) {

    if (!isset($key)) {

      // By default, we want the active connection, set in setActiveConnection.

      $key = self::$activeKey;

    }

    // If the requested target does not exist, or if it is ignored, we fall back

    // to the default target. The target is typically either "default" or

    // "slave", indicating to use a slave SQL server if one is available. If

    // it's not available, then the default/master server is the correct server

    // to use.

    if (!empty(self::$ignoreTargets[$key][$target]) || !isset(self::$databaseInfo[$key][$target])) {

      $target = 'default';

    }

    if (!isset(self::$connections[$key][$target])) {

      // If necessary, a new connection is opened.

      self::$connections[$key][$target] = self::openConnection($key, $target);

    }

    return self::$connections[$key][$target];

  }

  /**

   * Determines if there is an active connection.

   *

   * Note that this method will return FALSE if no connection has been

   * established yet, even if one could be.

   *

   * @return

   *   TRUE if there is at least one database connection established, FALSE

   *   otherwise.

   */

  final public static function isActiveConnection() {

    return !empty(self::$activeKey) && !empty(self::$connections) && !empty(self::$connections[self::$activeKey]);

  }

  /**

   * Sets the active connection to the specified key.

   *

   * @return

   *   The previous database connection key.

   */

  final public static function setActiveConnection($key = 'default') {

    if (empty(self::$databaseInfo)) {

      self::parseConnectionInfo();

    }

    if (!empty(self::$databaseInfo[$key])) {

      $old_key = self::$activeKey;

      self::$activeKey = $key;

      return $old_key;

    }

  }

  /**

   * Process the configuration file for database information.

   */

  final public static function parseConnectionInfo() {

    global $databases;

    $database_info = is_array($databases) ? $databases : array();

    foreach ($database_info as $index => $info) {

      foreach ($database_info[$index] as $target => $value) {

        // If there is no "driver" property, then we assume it's an array of

        // possible connections for this target. Pick one at random. That allows

        //  us to have, for example, multiple slave servers.

        if (empty($value['driver'])) {

          $database_info[$index][$target] = $database_info[$index][$target][mt_rand(0, count($database_info[$index][$target]) - 1)];

        }

        // Parse the prefix information.

        if (!isset($database_info[$index][$target]['prefix'])) {

          // Default to an empty prefix.

          $database_info[$index][$target]['prefix'] = array(

            'default' => '',

          );

        }

        elseif (!is_array($database_info[$index][$target]['prefix'])) {

          // Transform the flat form into an array form.

          $database_info[$index][$target]['prefix'] = array(

            'default' => $database_info[$index][$target]['prefix'],

          );

        }

      }

    }

    if (!is_array(self::$databaseInfo)) {

      self::$databaseInfo = $database_info;

    }

    // Merge the new $database_info into the existing.

    // array_merge_recursive() cannot be used, as it would make multiple

    // database, user, and password keys in the same database array.

    else {

      foreach ($database_info as $database_key => $database_values) {

        foreach ($database_values as $target => $target_values) {

          self::$databaseInfo[$database_key][$target] = $target_values;

        }

      }

    }

  }

  /**

   * Adds database connection information for a given key/target.

   *

   * This method allows the addition of new connection credentials at runtime.

   * Under normal circumstances the preferred way to specify database

   * credentials is via settings.php. However, this method allows them to be

   * added at arbitrary times, such as during unit tests, when connecting to

   * admin-defined third party databases, etc.

   *

   * If the given key/target pair already exists, this method will be ignored.

   *

   * @param $key