crell/pdo/database.inc

<?php

error_reporting(E_ALL | E_STRICT);

define('DEBUG', TRUE);

include_once('database_query_builder.inc');

function debug($msg, $label = 'DEBUG', $stealth = FALSE) {
  if (defined('DEBUG') && DEBUG) {
    if (is_bool($msg)) $msg = $msg ? 'TRUE' : 'FALSE';
    $display = $stealth ? ' style="display: none;"' : '';
    $backtrace = debug_backtrace();
    $debug = array();
    $stack = (isset($backtrace[1]['class']) ? "{$backtrace[1]['class']}::" : '')
    	. (isset($backtrace[1]['function']) ? "{$backtrace[1]['function']}" : '');
    if ($stack) $debug[] = $stack;
    $debug[] = "Line {$backtrace[0]['line']} of {$backtrace[0]['file']}";
    $debug = implode('<br />', $debug);
    print "<pre{$display}>{$label}: {$debug}:<br />" . print_r($msg, 1) . "</pre><br />\n";
  }
}

//debug(False, 'Something here', TRUE);

/**
 * Base Database API class.
 *
 * This class provides a Drupal-specific extension of the PDO database abstraction class in PHP.
 * All database access calls should be issued statically against this class.  It acts as a Factory,
 * returning the appropriate child class for a specific database implmentation based on the
 * values of the global $db_url array.
 *
 */
abstract class DatabaseConnection extends PDO {
  
  function __construct($dsn, $username, $password, $driver_options = array()) {
    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION; // Because the other methods don't seem to work right.
    parent::__construct($dsn, $username, $password, $driver_options);
    $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('DatabaseStatement' , array($this)));
  }
  
  /**
   * Return the default query options for any given query.
   *
   * @return
   *  An array of default query options.
   */
  public function defaultOptions() {
    return array(
      'target' => 'default',
      'fetch' => PDO::FETCH_OBJ,
      'return_affected' => FALSE,
    );
  }
  
  public function transactions() {
    return $this->transactionSupport;
  }
  
  /**
   * Append 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 if
   * necessary.
   *
   * @param $sql
   *   A string containing a partial or entire SQL query.
   * @return
   *   The properly-prefixed string.
   */
  protected function prefixTables($sql) {
    global $db_prefix;

    if (is_array($db_prefix)) {
      if (array_key_exists('default', $db_prefix)) {
        $tmp = $db_prefix;
        unset($tmp['default']);
        foreach ($tmp as $key => $val) {
          $sql = strtr($sql, array('{' . $key . '}' => $val . $key));
        }
        return strtr($sql, array('{' => $db_prefix['default'] , '}' => ''));
      } else {
        foreach ($db_prefix as $key => $val) {
          $sql = strtr($sql, array('{' . $key . '}' => $val . $key));
        }
        return strtr($sql, array('{' => '' , '}' => ''));
      }
    } else {
      return strtr($sql, array('{' => $db_prefix , '}' => ''));
    }
  }

  protected function runQuery($query, Array $args, $options) {

    static $statements = array();

    $query = self::prefixTables($query);

    // Cache each prepared statement, keyed by the query itself.  This way,
    // we get the benefit of prepared statement caching without any extra
    // work by the module author.
    if (! isset($statements[$query])) {
      $statements[$query] = $this->prepare($query);
    }

    $options += $this->defaultOptions();
    $statements[$query]->execute($args, $options);

    if ($options['return_affected']) {
      return $statements[$query]->rowCount();
    } else {
      return $statements[$query];
    }
  }

  /**
   * Execute a raw SELECT query on this database object.
   *
   * @param $query
   *   A string containing an SQL query.
   * @param $args
   *  An array of values to substitute into the query at placeholder markers.
   * @param $options
   *  An array of options on the query.  This array is assumed to have all
   *  values populated.
   * @return
   *   A database query result resource, or FALSE if the query was not executed
   *   correctly.
   */
  public function query($query, Array $args, Array $options = array()) {

    // Backward compatibility hack, temporary.
    $query = str_replace(array('%d' , '%f' , '%b' , "'%s'"), '?', $query);

    return $this->runQuery($query, $args, $options);
  }

  public function select($query_id, Array $options = array()) {
    $class_type = 'SelectQuery_'. $this->driver();
    return new $class_type($query_id, $this, $options);
  }

  public function insert($query_id, $table, Array $options = array()) {
    $class_type = 'InsertQuery_'. $this->driver();
    return new $class_type($query_id, $this, $table, $options);
  }

  public function update($query_id, $table, Array $options = array()) {
    $class_type = 'UpdateQuery_'. $this->driver();
    return new $class_type($query_id, $this, $table, $options);
  }

  public function delete($query_id, $table, Array $options = array()) {
    $class_type = 'DeleteQuery_'. $this->driver();
    return new $class_type($query_id, $this, $table, $options);
  }
  
  public function schema() {
    static $schema;
    if (empty($schema)) {
      require_once('schema.inc');
      require_once('schema.'. $this->driver() .'.inc');
      $class_type = 'DatabaseSchema_'. $this->driver();
      $schema = new $class_type($this);
    }
    return $schema;
  }
  
  public function startTransaction() {
    $class_type = 'DatabaseTransaction_'. $this->driver();
    return new $class_type($this);
  }

  public function replace($query_id, $table, Array $fields, Array $where) {
    /*
    // The following trivial method should be replaced with a database-specific
    // mechanism if one exists.
    $num_deleted = $this->delete($table, $where);
    $fields += $where;
    $num_inserted = $this->insert($table, $fields);
    return $num_deleted + $num_inserted;
    */
  }
  
  public function escapeTable($table) {
    return preg_replace('/[^A-Za-z0-9_]+/', '', $string);
  }

  /**
   * 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.  This array is assumed to have all
   *  values populated.
   * @return
   *   A database query result resource, or FALSE if the query was not executed
   *   correctly.
   */
   abstract public function queryRange($query, Array $args, $from, $count, Array $options);

  /**
   * Runs a SELECT query and stores its results in a temporary table.
   *
   * Use this as a substitute for db_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. db_affected_rows() does
   * not give consistent result across different database types in this case.
   *
   * @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 $tablename
   *   The name of the temporary table to select into. This name will not be
   *   prefixed as there is no risk of collision.
   * @return
   *   A database query result resource, or FALSE if the query was not executed
   *   correctly.
   */
   abstract function queryTemporary($query, Array $args, $tablename);

  /**
   * 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();
  
  /**
   * Determine if this driver supports transactions.
   */
  abstract public function supportsTransactions();
  
  /**
   * Returns the type of the database being accessed.
   */
  abstract public function databaseType();
  
}

abstract class Database {

  static protected $connections = array();

  static protected $databaseInfo = NULL;

  static protected $activeKey = 'default';


  final public static function getActiveConnection($target = 'default') {
    return self::getConnection(self::$activeKey, $target);
  }

  final public static function setActiveConnection($key = 'default') {
    $old_key = self::$activeKey;
    self::$activeKey = $key;
    return $old_key;
  }

  /**
   * Parse out the database URLs specified in the config file
   * and specify defaults where necessary.
   */
  final protected static function parseUrls() {
    global $db_url;
    self::$dbUrls = $db_url;
    if (! is_array(self::$dbUrls)) {
      self::$dbUrls = array('default' => self::$dbUrls);
    }
    foreach (self::$dbUrls as $index => $url) {
      if (! is_array(self::$dbUrls[$index])) {
        self::$dbUrls[$index] = array('default' => $url);
      }
      foreach (self::$dbUrls[$index] as $target => $value) {
        // Each target can also be an array.  If it is, we select one entry at random to be
        // target for this request.  That allows us to have multiple slave servers.
        if (is_array($value)) {
          self::$dbUrls[$index][$target] = self::$dbUrls[$index][$target][mt_rand(0, count(self::$dbUrls[$index][$target]) - 1)];
        }
      }
    }
  }
  
  final protected static function parseConnectionInfo() {
    $databaseInfo = $GLOBALS['databases'];
    
    // If no database key is specified, default to default.
    if (! is_array($databaseInfo)) {
      $databaseInfo = array('default' => $databaseInfo);
    }
    
    foreach ($databaseInfo as $index => $info) {
      // If no targets are specified, default to one default.
      if (! is_array($databaseInfo[$index])) {
        $databaseInfo[$index] = array('default' => $info);
      }
      
      foreach ($databaseInfo[$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'])) {
          $databaseInfo[$index][$target] = $databaseInfo[$index][$target][mt_rand(0, count($databaseInfo[$index][$target]) - 1)];
        }
      }
    }
    
    self::$databaseInfo = $databaseInfo;
    
  }

  /**
   * Open a connection to the server specified by the given
   * key and target.
   *
   * @param $key
   * @param $target
   */
  final protected static function openConnection($key, $target) {
    
    if (empty(self::$connectionInfo)) {
      self::parseConnectionInfo();
    }
    
    // If the requested database does not exist then it is an unrecoverable error.
    // If the requested target does not exist, however, 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 (! isset(self::$databaseInfo[$key])) {
      throw new Exception('DB does not exist');
    }
    if (! isset(self::$databaseInfo[$key][$target])) {
      $target = 'default';
    }
    
    $driver = self::$databaseInfo[$key][$target]['driver'];
    $driver_class = 'DatabaseConnection_'. $driver;
    $driver_file ='database.'. $driver .'.inc';

    try {
      require_once($driver_file);
      self::$connections[$key][$target] = new $driver_class(self::$databaseInfo[$key][$target]);
    } catch (PDOException $e) {
    	debug($e->getMessage());
      //watchdog('database', $e->getMessage());
      // print some sort of error here.
    }
  }

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

    if (! isset(self::$connections[$key][$target])) {
      self::openConnection($key, $target);
    }

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

class DatabaseTransaction {
  
  protected $connection;
  protected $supportsTransactions;
  protected $hasRolledBack = FALSE;
  
  public function __construct(DatabaseConnection $connection) {
    $this->connection = $connection;
    $this->supportsTransactions = $connection->supportsTransactions();
    
    if ($this->supportsTransactions) {
      $connection->beginTransaction();
    }
  }
  
  public function commit() {
    if ($this->supportsTransactions) {
      $this->connection->commit();
    }
  }
  
  public function rollBack() {
    if ($this->supportsTransactions) {
      $this->connection->rollBack();
      $this->hasRolledBack = TRUE;
    }
  }
  
  public function hasRolledBack() {
    return $this->hasRolledBack;
  }
  
  public function __destruct() {
    if ($this->supportsTransactions) {
      $this->connection->commit();
    }
  }
  
}


class DatabaseStatement extends PDOStatement {

  public $dbh;

  protected function __construct($dbh) {
    $this->dbh = $dbh;
    $this->setFetchMode(PDO::FETCH_OBJ);
  }

  public function execute($args, $options) {
    if (is_string($options['fetch'])) {
      $this->setFetchMode(PDO::FETCH_CLASS, $options['fetch']);
    }
    else {
      $this->setFetchMode($options['fetch']);
    }
    parent::execute($args);
  }

  public function fetchCol($index = 0) {
    return $this->fetchAll(PDO::FETCH_COLUMN, $index);
  }

  public function fetchAllAssoc($key) {
    $return = array();
    foreach ($this as $record) {
      $return[$record->$key] = $record;
    }
    return $return;
  }
  
  /* This needs a new name.
  public function fetchAssoc() {
    $return = array();
    $this->setFetchMode(PDO::FETCH_NUM);
    foreach ($this as $record) {
      $return[$record[0]] = $record[1];
    }
    return $return;
  }
  */

  public function fetchOne($index = 0) {
    return $this->fetchColumn($index);
  }

  /**
   * Fetches the next row and returns it as an associative array.
   *
   * This method corresponds to PDOStatement::fetchObject(),
   * but for associative arrays.  Why objects get a method of their
   * own and arrays do not, I do not know.
   *
   */
  public function fetchAssoc() {
    return $this->fetch(PDO::FETCH_ASSOC);
  }
}

/**
 * The following utility functions are simply convenience wrappers.
 * They should never, ever have any database-specific code in them.
 */

function db_query($query, Array $args = array(), Array $options = array()) {
  if (empty($options['target'])) {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->query($query, $args, $options);
}

function db_query_range($query, Array $args, $from = 0, $count = 0, Array $options = array()) {
  if (empty($options['target'])) {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->queryRange($query, $args, $from, $count, $options);
}

function db_query_temporary($query, Array $args, $tablename, Array $options = array()) {
  if (empty($options['target'])) {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->queryTemporary($query, $args, $tablename, $options);
}

function db_insert($query_id, $table, Array $options = array()) {
  if (empty($options['target']) || $options['target'] == 'slave') {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->insert($query_id, $table, $options);
}

function db_update($query_id, $table, Array $options = array()) {
  if (empty($options['target']) || $options['target'] == 'slave') {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->update($query_id, $table, $options);
}

function db_delete($query_id, $table, Array $options = array()) {
  if (empty($options['target']) || $options['target'] == 'slave') {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->delete($query_id, $table, $options);
}

function db_select($query_id, Array $options = array()) {
  if (empty($options['target'])) {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->select($query_id, $options);
}

function db_replace($query_id, $table, Array $fields = array(), $where = array()) {
  if (empty($options['target'])) {
    $options['target'] = 'default';
  }
  return Database::getActiveConnection($options['target'])->replace($table, $fields, $where);
}

function db_set_active($key = 'default') {
  Database::setActiveConnection($key);
}


/**
 * Restrict a dynamic table, column or constraint name to safe characters.
 *
 * Only keeps alphanumeric and underscores.
 */
function db_escape_table($string) {
  return Database::getActiveConnection()->escapeTable($table);
}

/**
 * Perform an SQL query and return success or failure.
 *
 * @param $sql
 *   A string containing a complete SQL query.  %-substitution
 *   parameters are not supported.
 * @return
 *   An array containing the keys:
 *      success: a boolean indicating whether the query succeeded
 *      query: the SQL query executed, passed through check_plain()
 */
function update_sql($sql) {
  $result = Database::getActiveConnection()->query($sql, array(true));
  return array('success' => $result !== FALSE, 'query' => check_plain($sql));
}

// Just for testing purposes
function check_plain($string) { return $string; }

/**
 * Returns the last insert id.
 *
 * @todo Remove this function when all queries have been ported to db_insert().
 * @param $table
 *   The name of the table you inserted into.
 * @param $field
 *   The name of the autoincrement field.
 */
function db_last_insert_id($table, $field) {
  Database::getActiveConnection()->lastInsertId();
}

/**
 * Determine the number of rows changed by the preceding query.
 *
 * This may not work, actually, without some tricky temp code.
 *
 * @todo Remove this function when all queries have been ported to db_update().
 */
function db_affected_rows() {
  global $active_db;
  return mysql_affected_rows($active_db);
}

/**
 * Generate placeholders for an array of query arguments of a single type.
 *
 * Given a Schema API field type, return correct %-placeholders to
 * embed in a query
 *
 * @todo This may be possible to remove in favor of db_select().
 * @param $arguments
 *  An array with at least one element.
 * @param $type
 *   The Schema API type of a field (e.g. 'int', 'text', or 'varchar').
 */
function db_placeholders($arguments, $type = 'int') {
  $placeholder = db_type_placeholder($type);
  return implode(',', array_fill(0, count($arguments), $placeholder));
}

/**
 * Helper function for db_rewrite_sql.
 *
 * Collects JOIN and WHERE statements via hook_db_rewrite_sql()
 * Decides whether to select primary_key or DISTINCT(primary_key)
 *
 * @todo Remove this function when all code has been converted to query_alter.
 * @param $query
 *   Query to be rewritten.
 * @param $primary_table
 *   Name or alias of the table which has the primary key field for this query.
 *   Typical table names would be: {blocks}, {comments}, {forum}, {node},
 *   {menu}, {term_data} or {vocabulary}. However, in most cases the usual
 *   table alias (b, c, f, n, m, t or v) is used instead of the table name.
 * @param $primary_field
 *   Name of the primary field.
 * @param $args
 *   Array of additional arguments.
 * @return
 *   An array: join statements, where statements, field or DISTINCT(field).
 */
function _db_rewrite_sql($query = '', $primary_table = 'n', $primary_field = 'nid', $args = array()) {
  $where = array();
  $join = array();
  $distinct = FALSE;
  foreach (module_implements('db_rewrite_sql') as $module) {
    $result = module_invoke($module, 'db_rewrite_sql', $query, $primary_table, $primary_field, $args);
    if (isset($result) && is_array($result)) {
      if (isset($result['where'])) {
        $where[] = $result['where'];
      }
      if (isset($result['join'])) {
        $join[] = $result['join'];
      }
      if (isset($result['distinct']) && $result['distinct']) {
        $distinct = TRUE;
      }
    }
    elseif (isset($result)) {
      $where[] = $result;
    }
  }

  $where = empty($where) ? '' : '('. implode(') AND (', $where) .')';
  $join = empty($join) ? '' : implode(' ', $join);

  return array($join, $where, $distinct);
}

/**
 * Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not
 * use FROM table1, table2 syntax, use JOIN instead.
 *
 * @todo Remove this function when all code has been converted to query_alter.
 * @param $query
 *   Query to be rewritten.
 * @param $primary_table
 *   Name or alias of the table which has the primary key field for this query.
 *   Typical table names would be: {blocks}, {comments}, {forum}, {node},
 *   {menu}, {term_data} or {vocabulary}. However, it is more common to use the
 *   the usual table aliases: b, c, f, n, m, t or v.
 * @param $primary_field
 *   Name of the primary field.
 * @param $args
 *   An array of arguments, passed to the implementations of hook_db_rewrite_sql.
 * @return
 *   The original query with JOIN and WHERE statements inserted from
 *   hook_db_rewrite_sql implementations. nid is rewritten if needed.
 */
function db_rewrite_sql($query, $primary_table = 'n', $primary_field = 'nid',  $args = array()) {
  list($join, $where, $distinct) = _db_rewrite_sql($query, $primary_table, $primary_field, $args);

  if ($distinct) {
    $query = db_distinct_field($primary_table, $primary_field, $query);
  }

  if (!empty($where) || !empty($join)) {
    $pattern = '{
      # Beginning of the string
      ^
      ((?P<anonymous_view>
        # Everything within this set of parentheses is named "anonymous view"
        (?:
          [^()]++                   # anything not parentheses
        |
          \( (?P>anonymous_view) \)          # an open parenthesis, more "anonymous view" and finally a close parenthesis.
        )*
      )[^()]+WHERE)
    }x';
    preg_match($pattern, $query, $matches);
    if ($where) {
      $n = strlen($matches[1]);
      $second_part = substr($query, $n);
      $first_part = substr($matches[1], 0, $n - 5) ." $join WHERE $where AND ( ";
      // PHP 4 does not support strrpos for strings. We emulate it.
      $haystack_reverse = strrev($second_part);
      // No need to use strrev on the needle, we supply GROUP, ORDER, LIMIT
      // reversed.
      foreach (array('PUORG', 'REDRO', 'TIMIL') as $needle_reverse) {
        $pos = strpos($haystack_reverse, $needle_reverse);
        if ($pos !== FALSE) {
          // All needles are five characters long.
          $pos += 5;
          break;
        }
      }
      if ($pos === FALSE) {
        $query = $first_part . $second_part .')';
      }
      else {
        $query = $first_part . substr($second_part, 0, -$pos) .')'. substr($second_part, -$pos);
      }
    }
    else {
      $query = $matches[1] ." $join ". substr($query, strlen($matches[1]));
    }
  }

  return $query;
}


/**
 * @ingroup schemaapi
 * @{
 */


/**
 * Create a new table from a Drupal table definition.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $name
 *   The name of the table to create.
 * @param $table
 *   A Schema API table definition array.
 */
function db_create_table(&$ret, $name, $table) {
  return Database::getActiveConnection()->schema()->createTable($ret, $name, $table);
}

/**
 * Return an array of field names from an array of key/index column specifiers.
 *
 * This is usually an identity function but if a key/index uses a column prefix
 * specification, this function extracts just the name.
 *
 * @param $fields
 *   An array of key/index column specifiers.
 * @return
 *   An array of field names.
 */
function db_field_names($fields) {
  return Database::getActiveConnection()->schema()->fieldNames($fields);
}

/**
 * Check if a table exists.
 */
function db_table_exists($table) {
  return Database::getActiveConnection()->schema()->tableExists($table);
}

/**
 * Check if a column exists in the given table.
 */
function db_column_exists($table, $column) {
  return Database::getActiveConnection()->schema()->columnExists($table, $column);
}


/**
 * Given a Schema API field type, return the correct %-placeholder.
 *
 * Embed the placeholder in a query to be passed to db_query and and pass as an
 * argument to db_query a value of the specified type.
 *
 * @todo Remove this after all queries are converted to type-agnostic form.
 * @param $type
 *   The Schema API type of a field.
 * @return
 *   The placeholder string to embed in a query for that type.
 */
function db_type_placeholder($type) {
  switch ($type) {
    case 'varchar':
    case 'char':
    case 'text':
    case 'datetime':
      return '\'%s\'';

    case 'numeric':
      // For 'numeric' values, we use '%s', not '\'%s\'' as with
      // string types, because numeric values should not be enclosed
      // in quotes in queries (though they can be, at least on mysql
      // and pgsql).  Numerics should only have [0-9.+-] and
      // presumably no db's "escape string" function will mess with
      // those characters.
      return '%s';

    case 'serial':
    case 'int':
      return '%d';

    case 'float':
      return '%f';

    case 'blob':
      return '%b';
  }

  // There is no safe value to return here, so return something that
  // will cause the query to fail.
  return 'unsupported type '. $type .'for db_type_placeholder';
}


function _db_create_keys_sql($spec) {
  return Database::getActiveConnection()->schema()->createKeysSql($spec);
}

/**
 * This maps a generic data type in combination with its data size
 * to the engine-specific data type.
 */
function db_type_map() {
  return Database::getActiveConnection()->schema()->getFieldTypeMap();
}

/**
 * Rename a table.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be renamed.
 * @param $new_name
 *   The new name for the table.
 */
function db_rename_table(&$ret, $table, $new_name) {
  return Database::getActiveConnection()->schema()->renameTable($ret, $table, $new_name);
}

/**
 * Drop a table.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be dropped.
 */
function db_drop_table(&$ret, $table) {
  return Database::getActiveConnection()->schema()->dropTable($ret, $table);
}

/**
 * Add a new field to a table.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   Name of the table to be altered.
 * @param $field
 *   Name of the field to be added.
 * @param $spec
 *   The field specification array, as taken from a schema definition.
 *   The specification may also contain the key 'initial', the newly
 *   created field will be set to the value of the key in all rows.
 *   This is most useful for creating NOT NULL columns with no default
 *   value in existing tables.
 * @param $keys_new
 *   Optional keys and indexes specification to be created on the
 *   table along with adding the field. The format is the same as a
 *   table specification but without the 'fields' element.  If you are
 *   adding a type 'serial' field, you MUST specify at least one key
 *   or index including it in this array. @see db_change_field for more
 *   explanation why.
 */
function db_add_field(&$ret, $table, $field, $spec, $keys_new = array()) {
  return Database::getActiveConnection()->schema()->addField($ret, $table, $field, $spec, $keys_new);
}

/**
 * Drop a field.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $field
 *   The field to be dropped.
 */
function db_drop_field(&$ret, $table, $field) {
  return Database::getActiveConnection()->schema()->dropField($ret, $table, $field);
}

/**
 * Set the default value for a field.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $field
 *   The field to be altered.
 * @param $default
 *   Default value to be set. NULL for 'default NULL'.
 */
function db_field_set_default(&$ret, $table, $field, $default) {
  return Database::getActiveConnection()->schema()->dropField($ret, $table, $field, $default);
}

/**
 * Set a field to have no default value.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $field
 *   The field to be altered.
 */
function db_field_set_no_default(&$ret, $table, $field) {
  return Database::getActiveConnection()->schema()->fieldSetNoDefault($ret, $table, $field);
}

/**
 * Add a primary key.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $fields
 *   Fields for the primary key.
 */
function db_add_primary_key(&$ret, $table, $fields) {
  return Database::getActiveConnection()->schema()->addPrimaryKey($ret, $table, $field);
}

/**
 * Drop the primary key.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 */
function db_drop_primary_key(&$ret, $table) {
  return Database::getActiveConnection()->schema()->dropPrimaryKey($ret, $table);
}

/**
 * Add a unique key.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $name
 *   The name of the key.
 * @param $fields
 *   An array of field names.
 */
function db_add_unique_key(&$ret, $table, $name, $fields) {
  return Database::getActiveConnection()->schema()->addUniqueKey($ret, $table, $name, $fields);
}

/**
 * Drop a unique key.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $name
 *   The name of the key.
 */
function db_drop_unique_key(&$ret, $table, $name) {
  return Database::getActiveConnection()->schema()->dropUniqueKey($ret, $table, $name);
}

/**
 * Add an index.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $name
 *   The name of the index.
 * @param $fields
 *   An array of field names.
 */
function db_add_index(&$ret, $table, $name, $fields) {
  return Database::getActiveConnection()->schema()->addIndex($ret, $table, $name, $fields);
}

/**
 * Drop an index.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   The table to be altered.
 * @param $name
 *   The name of the index.
 */
function db_drop_index(&$ret, $table, $name) {
  return Database::getActiveConnection()->schema()->addIndex($ret, $table, $name);
}

/**
 * Change a field definition.
 *
 * IMPORTANT NOTE: To maintain database portability, you have to explicitly
 * recreate all indices and primary keys that are using the changed field.
 *
 * That means that you have to drop all affected keys and indexes with
 * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
 * To recreate the keys and indices, pass the key definitions as the
 * optional $keys_new argument directly to db_change_field().
 *
 * For example, suppose you have:
 * @code
 * $schema['foo'] = array(
 *   'fields' => array(
 *     'bar' => array('type' => 'int', 'not null' => TRUE)
 *   ),
 *   'primary key' => array('bar')
 * );
 * @endcode
 * and you want to change foo.bar to be type serial, leaving it as the
 * primary key.  The correct sequence is:
 * @code
 * db_drop_primary_key($ret, 'foo');
 * db_change_field($ret, 'foo', 'bar', 'bar',
 *   array('type' => 'serial', 'not null' => TRUE),
 *   array('primary key' => array('bar')));
 * @endcode
 *
 * The reasons for this are due to the different database engines:
 *
 * On PostgreSQL, changing a field definition involves adding a new field
 * and dropping an old one which* causes any indices, primary keys and
 * sequences (from serial-type fields) that use the changed field to be dropped.
 *
 * On MySQL, all type 'serial' fields must be part of at least one key
 * or index as soon as they are created.  You cannot use
 * db_add_{primary_key,unique_key,index}() for this purpose because
 * the ALTER TABLE command will fail to add the column without a key
 * or index specification.  The solution is to use the optional
 * $keys_new argument to create the key or index at the same time as
 * field.
 *
 * You could use db_add_{primary_key,unique_key,index}() in all cases
 * unless you are converting a field to be type serial. You can use
 * the $keys_new argument in all cases.
 *
 * @param $ret
 *   Array to which query results will be added.
 * @param $table
 *   Name of the table.
 * @param $field
 *   Name of the field to change.
 * @param $field_new
 *   New name for the field (set to the same as $field if you don't want to change the name).
 * @param $spec
 *   The field specification for the new field.
 * @param $keys_new
 *   Optional keys and indexes specification to be created on the
 *   table along with changing the field. The format is the same as a
 *   table specification but without the 'fields' element.
 */

function db_change_field(&$ret, $table, $field, $field_new, $spec, $keys_new = array()) {
  return Database::getActiveConnection()->schema()->changeField($ret, $table, $field, $field_new, $spec, $keys_new);
}

/**
 * @} End of "ingroup schemaapi".
 */

// For temporary backward compatibility only.
function db_fetch_object(DatabaseStatement $statement) {
  return $statement->fetch(PDO::FETCH_OBJ);
}

function db_fetch_array(DatabaseStatement $statement) {
  return $statement->fetch(PDO::FETCH_BOTH);
}

