Skip to content
Snippets Groups Projects
Select Git revision
  • 57a156ef960790ab2dc7fd9027d1ab6c8781f669
  • 11.x default protected
  • 11.2.x protected
  • 10.5.x protected
  • 10.6.x protected
  • 11.1.x protected
  • 10.4.x protected
  • 11.0.x protected
  • 10.3.x protected
  • 7.x protected
  • 10.2.x protected
  • 10.1.x protected
  • 9.5.x protected
  • 10.0.x protected
  • 9.4.x protected
  • 9.3.x protected
  • 9.2.x protected
  • 9.1.x protected
  • 8.9.x protected
  • 9.0.x protected
  • 8.8.x protected
  • 10.5.1 protected
  • 11.2.2 protected
  • 11.2.1 protected
  • 11.2.0 protected
  • 10.5.0 protected
  • 11.2.0-rc2 protected
  • 10.5.0-rc1 protected
  • 11.2.0-rc1 protected
  • 10.4.8 protected
  • 11.1.8 protected
  • 10.5.0-beta1 protected
  • 11.2.0-beta1 protected
  • 11.2.0-alpha1 protected
  • 10.4.7 protected
  • 11.1.7 protected
  • 10.4.6 protected
  • 11.1.6 protected
  • 10.3.14 protected
  • 10.4.5 protected
  • 11.0.13 protected
41 results

Connection.php

Blame
  • webchick's avatar
    Issue #692366 by underq, bradweikel, willmoy, kid_icarus | foripepe: Fixed...
    Angie Byron authored
    Issue #692366 by underq, bradweikel, willmoy, kid_icarus | foripepe: Fixed Stop forcing language/mirror for PHP manual links.
    57a156ef
    History
    Code owners
    Assign users and groups as approvers for specific file changes. Learn more.
    Connection.php 35.11 KiB
    <?php
    
    /**
     * @file
     * Definition of Drupal\Core\Database\Connection
     */
    
    namespace Drupal\Core\Database;
    
    use Drupal\Core\Database\TransactionNoActiveException;
    use Drupal\Core\Database\TransactionOutOfOrderException;
    
    use PDO;
    use PDOException;
    
    /**
     * 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 Connection 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 Log
       */
      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 = 'Drupal\Core\Database\Statement';
    
      /**
       * 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 specific PDOStatement class if the driver requires that.
        if (!empty($this->statementClass)) {
          $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));
        }
      }
    
      /**
       * 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 Drupal\Core\Database\StatementInterface
       *   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(Log $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 Drupal\Core\Database\StatementInterface
       *   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 ($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.
       * @return string
       *   The name of the class that should be used for this driver.
       */
      public function getDriverClass($class) {
        if (empty($this->driverClasses[$class])) {
          $driver = $this->driver();
          $driver_class = "Drupal\\Core\\Database\\Driver\\{$driver}\\{$class}";
          $this->driverClasses[$class] = class_exists($driver_class) ? $driver_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 Drupal\Core\Database\Query\SelectInterface
       *   An appropriate SelectQuery object for this database connection. Note that
       *   it may be a driver-specific subclass of SelectQuery, depending on the
       *   driver.
       *
       * @see Drupal\Core\Database\Query\Select
       */
      public function select($table, $alias = NULL, array $options = array()) {
        $class = $this->getDriverClass('Select');
        return new $class($table, $alias, $this, $options);
      }
    
      /**
       * Prepares and returns an INSERT query object.
       *
       * @param $options
       *   An array of options on the query.
       *
       * @return Drupal\Core\Database\Query\Insert
       *   A new Insert query object.
       *
       * @see Drupal\Core\Database\Query\Insert
       */
      public function insert($table, array $options = array()) {
        $class = $this->getDriverClass('Insert');
        return new $class($this, $table, $options);
      }
    
      /**
       * Prepares and returns a MERGE query object.
       *
       * @param $options
       *   An array of options on the query.
       *
       * @return Drupal\Core\Database\Query\Merge
       *   A new Merge query object.
       *
       * @see Drupal\Core\Database\Query\Merge
       */
      public function merge($table, array $options = array()) {
        $class = $this->getDriverClass('Merge');
        return new $class($this, $table, $options);
      }
    
    
      /**
       * Prepares and returns an UPDATE query object.
       *
       * @param $options
       *   An array of options on the query.
       *
       * @return Drupal\Core\Database\Query\Update
       *   A new Update query object.
       *
       * @see Drupal\Core\Database\Query\Update
       */
      public function update($table, array $options = array()) {
        $class = $this->getDriverClass('Update');
        return new $class($this, $table, $options);
      }
    
      /**
       * Prepares and returns a DELETE query object.
       *
       * @param $options
       *   An array of options on the query.
       *
       * @return Drupal\Core\Database\Query\Delete
       *   A new Delete query object.
       *
       * @see Drupal\Core\Database\Query\Delete
       */
      public function delete($table, array $options = array()) {
        $class = $this->getDriverClass('Delete');
        return new $class($this, $table, $options);
      }
    
      /**
       * Prepares and returns a TRUNCATE query object.
       *
       * @param $options
       *   An array of options on the query.
       *
       * @return Drupal\Core\Database\Query\Truncate
       *   A new Truncate query object.
       *
       * @see Drupal\Core\Database\Query\Truncate
       */
      public function truncate($table, array $options = array()) {
        $class = $this->getDriverClass('Truncate');
        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 Drupal\Core\Database\Schema
       *   The database Schema object for this connection.
       */
      public function schema() {
        if (empty($this->schema)) {
          $class = $this->getDriverClass('Schema');
          $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
       * Drupal\Core\Database\Query\Condition::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.
       *
       * @see Drupal\Core\Database\Transaction
       */
      public function startTransaction($name = '') {
        $class = $this->getDriverClass('Transaction');
        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 Drupal\Core\Database\TransactionNoActiveException
       *
       * @see DatabaseTransaction::rollback()
       */
      public function rollback($savepoint_name = 'drupal_transaction') {
        if (!$this->supportsTransactions()) {
          return;
        }
        if (!$this->inTransaction()) {
          throw new TransactionNoActiveException();
        }
        // 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 TransactionNoActiveException();
         }
    
        // 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 TransactionOutOfOrderException();
            }
            return;
          }
          else {
            $rolled_back_other_active_savepoints = TRUE;
          }
        }
        parent::rollBack();
        if ($rolled_back_other_active_savepoints) {
          throw new TransactionOutOfOrderException();
        }
      }
    
      /**
       * Increases the depth of transaction nesting.
       *
       * If no transaction is already active, we begin a new transaction.
       *
       * @throws Drupal\Core\Database\TransactionNameNonUniqueException
       *
       * @see Drupal\Core\Database\Transaction
       */
      public function pushTransaction($name) {
        if (!$this->supportsTransactions()) {
          return;
        }
        if (isset($this->transactionLayers[$name])) {
          throw new TransactionNameNonUniqueException($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 Drupal\Core\Database\TransactionNoActiveException
       * @throws Drupal\Core\Database\TransactionCommitFailedException
       *
       * @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 TransactionCommitFailedException();
            }
          }
          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 Drupal\Core\Database\StatementInterface
       *   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 Drupal\Core\Database\Query\Condition::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 Drupal\Core\Database\TransactionExplicitCommitNotAllowedException
       *
       * @see Drupal\Core\Database\Transaction
       */
      public function commit() {
        throw new TransactionExplicitCommitNotAllowedException();
      }
    
      /**
       * 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);
    }