database.inc
Same filename in this branch
Same filename in other branches
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.
File
-
includes/
database/ database.inc
View source
<?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 {
/**
* 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 actual PDO connection.
*
* @var \PDO
*/
protected $connection;
/**
* 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();
/**
* List of escaped database, table, and field names, keyed by unescaped names.
*
* @var array
*/
protected $escapedNames = array();
/**
* List of escaped aliases names, keyed by unescaped aliases.
*
* @var array
*/
protected $escapedAliases = array();
/**
* List of un-prefixed table names, keyed by prefixed table names.
*
* @var array
*/
protected $unprefixedTablesMap = 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.
$this->connection = new PDO($dsn, $username, $password, $driver_options);
// Set a Statement class, unless the driver opted out.
if (!empty($this->statementClass)) {
$this->connection
->setAttribute(PDO::ATTR_STATEMENT_CLASS, array(
$this->statementClass,
array(
$this,
),
));
}
}
/**
* Proxy possible direct calls to the \PDO methods.
*
* Since PHP8.0 the signature of the the \PDO::query() method has changed,
* and this class can't extending \PDO any more.
*
* However, for the BC, proxy any calls to the \PDO methods to the actual
* PDO connection object.
*/
public function __call($name, $arguments) {
return call_user_func_array(array(
$this->connection,
$name,
), $arguments);
}
/**
* 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.
if (!empty($this->statementClass)) {
$this->connection
->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[] = '';
// Set up a map of prefixed => un-prefixed tables.
foreach ($this->prefixes as $table_name => $prefix) {
if ($table_name !== 'default') {
$this->unprefixedTablesMap[$prefix . $table_name] = $table_name;
}
}
}
/**
* 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'];
}
}
/**
* Gets a list of individually prefixed table names.
*
* @return array
* An array of un-prefixed table names, keyed by their fully qualified table
* names (i.e. prefix + table_name).
*/
public function getUnprefixedTablesMap() {
return $this->unprefixedTablesMap;
}
/**
* 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 $this->connection
->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 strtr($comment, array(
'*' => ' * ',
));
}
/**
* 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 ID 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->connection
->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->errorInfo['query_string'] = $stmt->getQueryString();
}
else {
$e->errorInfo['query_string'] = $query;
}
$e->errorInfo['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 string
* The sanitized table name string.
*/
public function escapeTable($table) {
if (!isset($this->escapedNames[$table])) {
$this->escapedNames[$table] = preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
}
return $this->escapedNames[$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 string
* The sanitized field name string.
*/
public function escapeField($field) {
if (!isset($this->escapedNames[$field])) {
$this->escapedNames[$field] = preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
}
return $this->escapedNames[$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 string
* The sanitized field name string.
*/
public function escapeAlias($field) {
if (!isset($this->escapedAliases[$field])) {
$this->escapedAliases[$field] = preg_replace('/[^A-Za-z0-9_]+/', '', $field);
}
return $this->escapedAliases[$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;
}
}
$this->connection
->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 {
$this->connection
->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 (!$this->connection
->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.
*/
public abstract 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().
*/
public abstract function driver();
/**
* Returns the version of the database server.
*/
public function version() {
return $this->connection
->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.
*/
public abstract 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()
*/
public abstract 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.
*/
public abstract function nextId($existing_id = 0);
/**
* Checks whether utf8mb4 support is configurable in settings.php.
*
* @return bool
*/
public function utf8mb4IsConfigurable() {
// Since 4 byte UTF-8 is not supported by default, there is nothing to
// configure.
return FALSE;
}
/**
* Checks whether utf8mb4 support is currently active.
*
* @return bool
*/
public function utf8mb4IsActive() {
// Since 4 byte UTF-8 is not supported by default, there is nothing to
// activate.
return FALSE;
}
/**
* Checks whether utf8mb4 support is available on the current database system.
*
* @return bool
*/
public function utf8mb4IsSupported() {
// By default we assume that the database backend may not support 4 byte
// UTF-8.
return FALSE;
}
}
/**
* 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
*/
protected static $connections = array();
/**
* A processed copy of the database connection information from settings.php.
*
* @var array
*/
protected static $databaseInfo = NULL;
/**
* A list of key/target credentials to simply ignore.
*
* @var array
*/
protected static $ignoreTargets = array();
/**
* The key of the currently active database connection.
*
* @var string
*/
protected static $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
*/
protected static $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
*/
public static final 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
*/
public static final 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.
*/
public static final 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.
*/
public static final 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.
*/
public static final 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.
*/
public static final 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;
}
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
* The database key.
* @param $target
* The database target name.
* @param $info
* The database connection information, as it would be defined in
* settings.php. Note that the structure of this array will depend on the
* database driver it is connecting to.
*/
public static function addConnectionInfo($key, $target, $info) {
if (empty(self::$databaseInfo[$key][$target])) {
self::$databaseInfo[$key][$target] = $info;
}
}
/**
* Gets information on the specified database connection.
*
* @param $connection
* The connection key for which we want information.
*/
public static final function getConnectionInfo($key = 'default') {
if (empty(self::$databaseInfo)) {
self::parseConnectionInfo();
}
if (!empty(self::$databaseInfo[$key])) {
return self::$databaseInfo[$key];
}
}
/**
* Rename a connection and its corresponding connection information.
*
* @param $old_key
* The old connection key.
* @param $new_key
* The new connection key.
* @return
* TRUE in case of success, FALSE otherwise.
*/
public static final function renameConnection($old_key, $new_key) {
if (empty(self::$databaseInfo)) {
self::parseConnectionInfo();
}
if (!empty(self::$databaseInfo[$old_key]) && empty(self::$databaseInfo[$new_key])) {
// Migrate the database connection information.
self::$databaseInfo[$new_key] = self::$databaseInfo[$old_key];
unset(self::$databaseInfo[$old_key]);
// Migrate over the DatabaseConnection object if it exists.
if (isset(self::$connections[$old_key])) {
self::$connections[$new_key] = self::$connections[$old_key];
unset(self::$connections[$old_key]);
}
return TRUE;
}
else {
return FALSE;
}
}
/**
* Remove a connection and its corresponding connection information.
*
* @param $key
* The connection key.
* @param $close
* Whether to close the connection.
* @return
* TRUE in case of success, FALSE otherwise.
*/
public static final function removeConnection($key, $close = TRUE) {
if (isset(self::$databaseInfo[$key])) {
if ($close) {
self::closeConnection(NULL, $key);
}
unset(self::$databaseInfo[$key]);
return TRUE;
}
else {
return FALSE;
}
}
/**
* Opens a connection to the server specified by the given key and target.
*
* @param $key
* The database connection key, as specified in settings.php. The default is
* "default".
* @param $target
* The database target to open.
*
* @throws DatabaseConnectionNotDefinedException
* @throws DatabaseDriverNotSpecifiedException
*/
protected static final function openConnection($key, $target) {
if (empty(self::$databaseInfo)) {
self::parseConnectionInfo();
}
// If the requested database does not exist then it is an unrecoverable
// error.
if (!isset(self::$databaseInfo[$key])) {
throw new DatabaseConnectionNotDefinedException('The specified database connection is not defined: ' . $key);
}
if (!($driver = self::$databaseInfo[$key][$target]['driver'])) {
throw new DatabaseDriverNotSpecifiedException('Driver not specified for this database connection: ' . $key);
}
// We cannot rely on the registry yet, because the registry requires an
// open database connection.
$driver_class = 'DatabaseConnection_' . $driver;
require_once DRUPAL_ROOT . '/includes/database/' . $driver . '/database.inc';
$new_connection = new $driver_class(self::$databaseInfo[$key][$target]);
$new_connection->setTarget($target);
$new_connection->setKey($key);
// If we have any active logging objects for this connection key, we need
// to associate them with the connection we just opened.
if (!empty(self::$logs[$key])) {
$new_connection->setLogger(self::$logs[$key]);
}
return $new_connection;
}
/**
* Closes a connection to the server specified by the given key and target.
*
* @param $target
* The database target name. Defaults to NULL meaning that all target
* connections will be closed.
* @param $key
* The database connection key. Defaults to NULL which means the active key.
*/
public static function closeConnection($target = NULL, $key = NULL) {
// Gets the active connection by default.
if (!isset($key)) {
$key = self::$activeKey;
}
// To close a connection, it needs to be set to NULL and removed from the
// static variable. In all cases, closeConnection() might be called for a
// connection that was not opened yet, in which case the key is not defined
// yet and we just ensure that the connection key is undefined.
if (isset($target)) {
if (isset(self::$connections[$key][$target])) {
self::$connections[$key][$target]->destroy();
self::$connections[$key][$target] = NULL;
}
unset(self::$connections[$key][$target]);
}
else {
if (isset(self::$connections[$key])) {
foreach (self::$connections[$key] as $target => $connection) {
self::$connections[$key][$target]->destroy();
self::$connections[$key][$target] = NULL;
}
}
unset(self::$connections[$key]);
}
}
/**
* Instructs the system to temporarily ignore a given key/target.
*
* At times we need to temporarily disable slave queries. To do so, call this
* method with the database key and the target to disable. That database key
* will then always fall back to 'default' for that key, even if it's defined.
*
* @param $key
* The database connection key.
* @param $target
* The target of the specified key to ignore.
*/
public static function ignoreTarget($key, $target) {
self::$ignoreTargets[$key][$target] = TRUE;
}
/**
* Load a file for the database that might hold a class.
*
* @param $driver
* The name of the driver.
* @param array $files
* The name of the files the driver specific class can be.
*/
public static function loadDriverFile($driver, array $files = array()) {
static $base_path;
if (empty($base_path)) {
$base_path = dirname(realpath(__FILE__));
}
$driver_base_path = "{$base_path}/{$driver}";
foreach ($files as $file) {
// Load the base file first so that classes extending base classes will
// have the base class loaded.
foreach (array(
"{$base_path}/{$file}",
"{$driver_base_path}/{$file}",
) as $filename) {
// The OS caches file_exists() and PHP caches require_once(), so
// we'll let both of those take care of performance here.
if (file_exists($filename)) {
require_once $filename;
}
}
}
}
}
/**
* Exception for when popTransaction() is called with no active transaction.
*/
class DatabaseTransactionNoActiveException extends Exception {
}
/**
* Exception thrown when a savepoint or transaction name occurs twice.
*/
class DatabaseTransactionNameNonUniqueException extends Exception {
}
/**
* Exception thrown when a commit() function fails.
*/
class DatabaseTransactionCommitFailedException extends Exception {
}
/**
* Exception to deny attempts to explicitly manage transactions.
*
* This exception will be thrown when the PDO connection commit() is called.
* Code should never call this method directly.
*/
class DatabaseTransactionExplicitCommitNotAllowedException extends Exception {
}
/**
* Exception thrown when a rollback() resulted in other active transactions being rolled-back.
*/
class DatabaseTransactionOutOfOrderException extends Exception {
}
/**
* Exception thrown for merge queries that do not make semantic sense.
*
* There are many ways that a merge query could be malformed. They should all
* throw this exception and set an appropriately descriptive message.
*/
class InvalidMergeQueryException extends Exception {
}
/**
* Exception thrown if an invalid query condition is specified.
*/
class InvalidQueryConditionOperatorException extends Exception {
}
/**
* Exception thrown if an insert query specifies a field twice.
*
* It is not allowed to specify a field as default and insert field, this
* exception is thrown if that is the case.
*/
class FieldsOverlapException extends Exception {
}
/**
* Exception thrown if an insert query doesn't specify insert or default fields.
*/
class NoFieldsException extends Exception {
}
/**
* Exception thrown if an undefined database connection is requested.
*/
class DatabaseConnectionNotDefinedException extends Exception {
}
/**
* Exception thrown if no driver is specified for a database connection.
*/
class DatabaseDriverNotSpecifiedException extends Exception {
}
/**
* A wrapper class for creating and managing database transactions.
*
* Not all databases or database configurations support transactions. For
* example, MySQL MyISAM tables do not. It is also easy to begin a transaction
* and then forget to commit it, which can lead to connection errors when
* another transaction is started.
*
* This class acts as a wrapper for transactions. To begin a transaction,
* simply instantiate it. When the object goes out of scope and is destroyed
* it will automatically commit. It also will check to see if the specified
* connection supports transactions. If not, it will simply skip any transaction
* commands, allowing user-space code to proceed normally. The only difference
* is that rollbacks won't actually do anything.
*
* In the vast majority of cases, you should not instantiate this class
* directly. Instead, call ->startTransaction(), from the appropriate connection
* object.
*/
class DatabaseTransaction {
/**
* The connection object for this transaction.
*
* @var DatabaseConnection
*/
protected $connection;
/**
* A boolean value to indicate whether this transaction has been rolled back.
*
* @var Boolean
*/
protected $rolledBack = FALSE;
/**
* The name of the transaction.
*
* This is used to label the transaction savepoint. It will be overridden to
* 'drupal_transaction' if there is no transaction depth.
*/
protected $name;
public function __construct(DatabaseConnection $connection, $name = NULL) {
$this->connection = $connection;
// If there is no transaction depth, then no transaction has started. Name
// the transaction 'drupal_transaction'.
if (!($depth = $connection->transactionDepth())) {
$this->name = 'drupal_transaction';
}
elseif (!$name) {
$this->name = 'savepoint_' . $depth;
}
else {
$this->name = $name;
}
$this->connection
->pushTransaction($this->name);
}
public function __destruct() {
// If we rolled back then the transaction would have already been popped.
if (!$this->rolledBack) {
$this->connection
->popTransaction($this->name);
}
}
/**
* Retrieves the name of the transaction or savepoint.
*/
public function name() {
return $this->name;
}
/**
* Rolls back the current transaction.
*
* This is just a wrapper method to rollback whatever transaction stack we are
* currently in, which is managed by the connection object itself. Note that
* logging (preferable with watchdog_exception()) needs to happen after a
* transaction has been rolled back or the log messages will be rolled back
* too.
*
* @see DatabaseConnection::rollback()
* @see watchdog_exception()
*/
public function rollback() {
$this->rolledBack = TRUE;
$this->connection
->rollback($this->name);
}
}
/**
* Represents a prepared statement.
*
* Some methods in that class are purposefully commented out. Due to a change in
* how PHP defines PDOStatement, we can't define a signature for those methods
* that will work the same way between versions older than 5.2.6 and later
* versions. See http://bugs.php.net/bug.php?id=42452 for more details.
*
* Child implementations should either extend PDOStatement:
* @code
* class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
* @endcode
* or define their own class. If defining their own class, they will also have
* to implement either the Iterator or IteratorAggregate interface before
* DatabaseStatementInterface:
* @code
* class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
* @endcode
*/
interface DatabaseStatementInterface extends Traversable {
/**
* Executes a prepared statement
*
* @param $args
* An array of values with as many elements as there are bound parameters in
* the SQL statement being executed.
* @param $options
* An array of options for this query.
*
* @return
* TRUE on success, or FALSE on failure.
*/
public function execute($args = array(), $options = array());
/**
* Gets the query string of this statement.
*
* @return
* The query string, in its form with placeholders.
*/
public function getQueryString();
/**
* Returns the number of rows affected by the last SQL statement.
*
* @return
* The number of rows affected by the last DELETE, INSERT, or UPDATE
* statement executed.
*/
public function rowCount();
/**
* Sets the default fetch mode for this statement.
*
* See http://php.net/manual/pdo.constants.php for the definition of the
* constants used.
*
* @param $mode
* One of the PDO::FETCH_* constants.
* @param $a1
* An option depending of the fetch mode specified by $mode:
* - for PDO::FETCH_COLUMN, the index of the column to fetch
* - for PDO::FETCH_CLASS, the name of the class to create
* - for PDO::FETCH_INTO, the object to add the data to
* @param $a2
* If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the
* constructor.
*/
// public function setFetchMode($mode, $a1 = NULL, $a2 = array());
/**
* Fetches the next row from a result set.
*
* See http://php.net/manual/pdo.constants.php for the definition of the
* constants used.
*
* @param $mode
* One of the PDO::FETCH_* constants.
* Default to what was specified by setFetchMode().
* @param $cursor_orientation
* Not implemented in all database drivers, don't use.
* @param $cursor_offset
* Not implemented in all database drivers, don't use.
*
* @return
* A result, formatted according to $mode.
*/
// public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
/**
* Returns a single field from the next record of a result set.
*
* @param $index
* The numeric index of the field to return. Defaults to the first field.
*
* @return
* A single field from the next record, or FALSE if there is no next record.
*/
public function fetchField($index = 0);
/**
* Fetches the next row and returns it as an object.
*
* The object will be of the class specified by DatabaseStatementInterface::setFetchMode()
* or stdClass if not specified.
*/
// public function fetchObject();
/**
* Fetches the next row and returns it as an associative array.
*
* This method corresponds to PDOStatement::fetchObject(), but for associative
* arrays. For some reason PDOStatement does not have a corresponding array
* helper method, so one is added.
*
* @return
* An associative array, or FALSE if there is no next row.
*/
public function fetchAssoc();
/**
* Returns an array containing all of the result set rows.
*
* @param $mode
* One of the PDO::FETCH_* constants.
* @param $column_index
* If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
* @param $constructor_arguments
* If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
*
* @return
* An array of results.
*/
// function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments);
/**
* Returns an entire single column of a result set as an indexed array.
*
* Note that this method will run the result set to the end.
*
* @param $index
* The index of the column number to fetch.
*
* @return
* An indexed array, or an empty array if there is no result set.
*/
public function fetchCol($index = 0);
/**
* Returns the entire result set as a single associative array.
*
* This method is only useful for two-column result sets. It will return an
* associative array where the key is one column from the result set and the
* value is another field. In most cases, the default of the first two columns
* is appropriate.
*
* Note that this method will run the result set to the end.
*
* @param $key_index
* The numeric index of the field to use as the array key.
* @param $value_index
* The numeric index of the field to use as the array value.
*
* @return
* An associative array, or an empty array if there is no result set.
*/
public function fetchAllKeyed($key_index = 0, $value_index = 1);
/**
* Returns the result set as an associative array keyed by the given field.
*
* If the given key appears multiple times, later records will overwrite
* earlier ones.
*
* @param $key
* The name of the field on which to index the array.
* @param $fetch
* The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
* PDO::FETCH_BOTH the returned value with be an array of arrays. For any
* other value it will be an array of objects. By default, the fetch mode
* set for the query will be used.
*
* @return
* An associative array, or an empty array if there is no result set.
*/
public function fetchAllAssoc($key, $fetch = NULL);
}
/**
* Default implementation of DatabaseStatementInterface.
*
* PDO allows us to extend the PDOStatement class to provide additional
* functionality beyond that offered by default. We do need extra
* functionality. By default, this class is not driver-specific. If a given
* driver needs to set a custom statement class, it may do so in its
* constructor.
*
* @see http://us.php.net/pdostatement
*/
class DatabaseStatementBase extends PDOStatement implements DatabaseStatementInterface {
/**
* Reference to the database connection object for this statement.
*
* The name $dbh is inherited from PDOStatement.
*
* @var DatabaseConnection
*/
public $dbh;
protected function __construct($dbh) {
$this->dbh = $dbh;
$this->setFetchMode(PDO::FETCH_OBJ);
}
public function execute($args = array(), $options = array()) {
if (isset($options['fetch'])) {
if (is_string($options['fetch'])) {
// Default to an object. Note: db fields will be added to the object
// before the constructor is run. If you need to assign fields after
// the constructor is run, see http://drupal.org/node/315092.
$this->setFetchMode(PDO::FETCH_CLASS, $options['fetch']);
}
else {
$this->setFetchMode($options['fetch']);
}
}
$logger = $this->dbh
->getLogger();
if (!empty($logger)) {
$query_start = microtime(TRUE);
}
$return = parent::execute($args);
if (!empty($logger)) {
$query_end = microtime(TRUE);
$logger->log($this, $args, $query_end - $query_start);
}
return $return;
}
public function getQueryString() {
return $this->queryString;
}
public function fetchCol($index = 0) {
return $this->fetchAll(PDO::FETCH_COLUMN, $index);
}
public function fetchAllAssoc($key, $fetch = NULL) {
$return = array();
if (isset($fetch)) {
if (is_string($fetch)) {
$this->setFetchMode(PDO::FETCH_CLASS, $fetch);
}
else {
$this->setFetchMode($fetch);
}
}
foreach ($this as $record) {
$record_key = is_object($record) ? $record->{$key} : $record[$key];
$return[$record_key] = $record;
}
return $return;
}
public function fetchAllKeyed($key_index = 0, $value_index = 1) {
$return = array();
$this->setFetchMode(PDO::FETCH_NUM);
foreach ($this as $record) {
$return[$record[$key_index]] = $record[$value_index];
}
return $return;
}
public function fetchField($index = 0) {
// Call PDOStatement::fetchColumn to fetch the field.
return $this->fetchColumn($index);
}
public function fetchAssoc() {
// Call PDOStatement::fetch to fetch the row.
return $this->fetch(PDO::FETCH_ASSOC);
}
}
/**
* Empty implementation of a database statement.
*
* This class satisfies the requirements of being a database statement/result
* object, but does not actually contain data. It is useful when developers
* need to safely return an "empty" result set without connecting to an actual
* database. Calling code can then treat it the same as if it were an actual
* result set that happens to contain no records.
*
* @see SearchQuery
*/
class DatabaseStatementEmpty implements Iterator, DatabaseStatementInterface {
public function execute($args = array(), $options = array()) {
return FALSE;
}
public function getQueryString() {
return '';
}
public function rowCount() {
return 0;
}
public function setFetchMode($mode, $a1 = NULL, $a2 = array()) {
return;
}
public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL) {
return NULL;
}
public function fetchField($index = 0) {
return NULL;
}
public function fetchObject() {
return NULL;
}
public function fetchAssoc() {
return NULL;
}
function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments = array()) {
return array();
}
public function fetchCol($index = 0) {
return array();
}
public function fetchAllKeyed($key_index = 0, $value_index = 1) {
return array();
}
public function fetchAllAssoc($key, $fetch = NULL) {
return array();
}
/* Implementations of Iterator. */
public function current() {
return NULL;
}
public function key() {
return NULL;
}
public function rewind() {
// Nothing to do: our DatabaseStatement can't be rewound.
}
public function next() {
// Do nothing, since this is an always-empty implementation.
}
public function valid() {
return FALSE;
}
}
/**
* The following utility functions are simply convenience wrappers.
*
* They should never, ever have any database-specific code in them.
*/
/**
* Executes an arbitrary query string against the active database.
*
* Use this function for SELECT queries if it is just a simple query string.
* If the caller or other modules need to change the query, use db_select()
* instead.
*
* Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
* be handled via db_insert(), db_update() and db_delete() respectively.
*
* @param $query
* The prepared statement query to run. Although it will accept both named and
* unnamed placeholders, named placeholders are strongly preferred as they are
* more self-documenting.
* @param $args
* An array of values to substitute into the query. If the query uses named
* placeholders, this is an associative array in any order. If the query uses
* unnamed placeholders (?), this is an indexed array and the order must match
* the order of placeholders in the query string.
* @param $options
* An array of options to control how the query operates.
*
* @return DatabaseStatementInterface
* A prepared statement object, already executed.
*
* @see DatabaseConnection::defaultOptions()
*/
function db_query($query, array $args = array(), array $options = array()) {
if (empty($options['target'])) {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->query($query, $args, $options);
}
/**
* Executes a query against the active database, restricted to a range.
*
* @param $query
* The prepared statement query to run. Although it will accept both named and
* unnamed placeholders, named placeholders are strongly preferred as they are
* more self-documenting.
* @param $from
* The first record from the result set to return.
* @param $count
* The number of records to return from the result set.
* @param $args
* An array of values to substitute into the query. If the query uses named
* placeholders, this is an associative array in any order. If the query uses
* unnamed placeholders (?), this is an indexed array and the order must match
* the order of placeholders in the query string.
* @param $options
* An array of options to control how the query operates.
*
* @return DatabaseStatementInterface
* A prepared statement object, already executed.
*
* @see DatabaseConnection::defaultOptions()
*/
function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
if (empty($options['target'])) {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->queryRange($query, $from, $count, $args, $options);
}
/**
* Executes a SELECT query string and saves the result set to a temporary table.
*
* The execution of the query string happens against the active database.
*
* @param $query
* The prepared SELECT statement query to run. Although it will accept both
* named and unnamed placeholders, named placeholders are strongly preferred
* as they are more self-documenting.
* @param $args
* An array of values to substitute into the query. If the query uses named
* placeholders, this is an associative array in any order. If the query uses
* unnamed placeholders (?), this is an indexed array and the order must match
* the order of placeholders in the query string.
* @param $options
* An array of options to control how the query operates.
*
* @return
* The name of the temporary table.
*
* @see DatabaseConnection::defaultOptions()
*/
function db_query_temporary($query, array $args = array(), array $options = array()) {
if (empty($options['target'])) {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->queryTemporary($query, $args, $options);
}
/**
* Returns a new InsertQuery object for the active database.
*
* @param $table
* The table into which to insert.
* @param $options
* An array of options to control how the query operates.
*
* @return InsertQuery
* A new InsertQuery object for this connection.
*/
function db_insert($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->insert($table, $options);
}
/**
* Returns a new MergeQuery object for the active database.
*
* @param $table
* The table into which to merge.
* @param $options
* An array of options to control how the query operates.
*
* @return MergeQuery
* A new MergeQuery object for this connection.
*/
function db_merge($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->merge($table, $options);
}
/**
* Returns a new UpdateQuery object for the active database.
*
* @param $table
* The table to update.
* @param $options
* An array of options to control how the query operates.
*
* @return UpdateQuery
* A new UpdateQuery object for this connection.
*/
function db_update($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->update($table, $options);
}
/**
* Returns a new DeleteQuery object for the active database.
*
* @param $table
* The table from which to delete.
* @param $options
* An array of options to control how the query operates.
*
* @return DeleteQuery
* A new DeleteQuery object for this connection.
*/
function db_delete($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->delete($table, $options);
}
/**
* Returns a new TruncateQuery object for the active database.
*
* @param $table
* The table from which to delete.
* @param $options
* An array of options to control how the query operates.
*
* @return TruncateQuery
* A new TruncateQuery object for this connection.
*/
function db_truncate($table, array $options = array()) {
if (empty($options['target']) || $options['target'] == 'slave') {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->truncate($table, $options);
}
/**
* Returns a new SelectQuery object for the active database.
*
* @param $table
* The base table for this query. May be a string or another SelectQuery
* object. If a query object is passed, it will be used as a subselect.
* @param $alias
* The alias for the base table of this query.
* @param $options
* An array of options to control how the query operates.
*
* @return SelectQuery
* A new SelectQuery object for this connection.
*/
function db_select($table, $alias = NULL, array $options = array()) {
if (empty($options['target'])) {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->select($table, $alias, $options);
}
/**
* Returns a new transaction object for the active database.
*
* @param string $name
* Optional name of the transaction.
* @param array $options
* An array of options to control how the transaction operates:
* - target: The database target name.
*
* @return DatabaseTransaction
* A new DatabaseTransaction object for this connection.
*/
function db_transaction($name = NULL, array $options = array()) {
if (empty($options['target'])) {
$options['target'] = 'default';
}
return Database::getConnection($options['target'])->startTransaction($name);
}
/**
* Sets a new active database.
*
* @param $key
* The key in the $databases array to set as the default database.
*
* @return
* The key of the formerly active database.
*/
function db_set_active($key = 'default') {
return Database::setActiveConnection($key);
}
/**
* Restricts a dynamic table name to safe characters.
*
* Only keeps alphanumeric and underscores.
*
* @param $table
* The table name to escape.
*
* @return
* The escaped table name as a string.
*/
function db_escape_table($table) {
return Database::getConnection()->escapeTable($table);
}
/**
* Restricts a dynamic column or constraint name to safe characters.
*
* Only keeps alphanumeric and underscores.
*
* @param $field
* The field name to escape.
*
* @return
* The escaped field name as a string.
*/
function db_escape_field($field) {
return Database::getConnection()->escapeField($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.
*/
function db_like($string) {
return Database::getConnection()->escapeLike($string);
}
/**
* Retrieves the name of the currently active database driver.
*
* @return
* The name of the currently active database driver.
*/
function db_driver() {
return Database::getConnection()->driver();
}
/**
* Closes the active database connection.
*
* @param $options
* An array of options to control which connection is closed. Only the target
* key has any meaning in this case.
*/
function db_close(array $options = array()) {
if (empty($options['target'])) {
$options['target'] = NULL;
}
Database::closeConnection($options['target']);
}
/**
* Retrieves a unique id.
*
* Use this function if for some reason you can't use a serial field. Using a
* serial field is preferred, and InsertQuery::execute() returns the value of
* the last ID inserted.
*
* @param $existing_id
* After a database import, it might be that the sequences table is behind, so
* by passing in a minimum ID, it can be assured that we never issue the same
* ID.
*
* @return
* An integer number larger than any number returned before for this sequence.
*/
function db_next_id($existing_id = 0) {
return Database::getConnection()->nextId($existing_id);
}
/**
* Returns a new DatabaseCondition, set to "OR" all conditions together.
*
* @return DatabaseCondition
*/
function db_or() {
return new DatabaseCondition('OR');
}
/**
* Returns a new DatabaseCondition, set to "AND" all conditions together.
*
* @return DatabaseCondition
*/
function db_and() {
return new DatabaseCondition('AND');
}
/**
* Returns a new DatabaseCondition, set to "XOR" all conditions together.
*
* @return DatabaseCondition
*/
function db_xor() {
return new DatabaseCondition('XOR');
}
/**
* Returns a new DatabaseCondition, set to the specified conjunction.
*
* Internal API function call. The db_and(), db_or(), and db_xor()
* functions are preferred.
*
* @param $conjunction
* The conjunction to use for query conditions (AND, OR or XOR).
* @return DatabaseCondition
*/
function db_condition($conjunction) {
return new DatabaseCondition($conjunction);
}
/**
* @} End of "defgroup database".
*/
/**
* @addtogroup schemaapi
* @{
*/
/**
* Creates a new table from a Drupal table definition.
*
* @param $name
* The name of the table to create.
* @param $table
* A Schema API table definition array.
*/
function db_create_table($name, $table) {
return Database::getConnection()->schema()
->createTable($name, $table);
}
/**
* Returns 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::getConnection()->schema()
->fieldNames($fields);
}
/**
* Checks if an index exists in the given table.
*
* @param $table
* The name of the table in drupal (no prefixing).
* @param $name
* The name of the index in drupal (no prefixing).
*
* @return
* TRUE if the given index exists, otherwise FALSE.
*/
function db_index_exists($table, $name) {
return Database::getConnection()->schema()
->indexExists($table, $name);
}
/**
* Checks if a table exists.
*
* @param $table
* The name of the table in drupal (no prefixing).
*
* @return
* TRUE if the given table exists, otherwise FALSE.
*/
function db_table_exists($table) {
return Database::getConnection()->schema()
->tableExists($table);
}
/**
* Checks if a column exists in the given table.
*
* @param $table
* The name of the table in drupal (no prefixing).
* @param $field
* The name of the field.
*
* @return
* TRUE if the given column exists, otherwise FALSE.
*/
function db_field_exists($table, $field) {
return Database::getConnection()->schema()
->fieldExists($table, $field);
}
/**
* Finds all tables that are like the specified base table name.
*
* @param $table_expression
* An SQL expression, for example "simpletest%" (without the quotes).
*
* @return
* Array, both the keys and the values are the matching tables.
*/
function db_find_tables($table_expression) {
return Database::getConnection()->schema()
->findTables($table_expression);
}
/**
* Finds all tables that are like the specified base table name. This is a
* backport of the change made to db_find_tables in Drupal 8 to work with
* virtual, un-prefixed table names. The original function is retained for
* Backwards Compatibility.
* @see https://www.drupal.org/node/2552435
*
* @param $table_expression
* An SQL expression, for example "simpletest%" (without the quotes).
*
* @return
* Array, both the keys and the values are the matching tables.
*/
function db_find_tables_d8($table_expression) {
return Database::getConnection()->schema()
->findTablesD8($table_expression);
}
function _db_create_keys_sql($spec) {
return Database::getConnection()->schema()
->createKeysSql($spec);
}
/**
* Renames a table.
*
* @param $table
* The current name of the table to be renamed.
* @param $new_name
* The new name for the table.
*/
function db_rename_table($table, $new_name) {
return Database::getConnection()->schema()
->renameTable($table, $new_name);
}
/**
* Drops a table.
*
* @param $table
* The table to be dropped.
*/
function db_drop_table($table) {
return Database::getConnection()->schema()
->dropTable($table);
}
/**
* Adds a new field to a table.
*
* @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.
*
* @see db_change_field()
*/
function db_add_field($table, $field, $spec, $keys_new = array()) {
return Database::getConnection()->schema()
->addField($table, $field, $spec, $keys_new);
}
/**
* Drops a field.
*
* @param $table
* The table to be altered.
* @param $field
* The field to be dropped.
*/
function db_drop_field($table, $field) {
return Database::getConnection()->schema()
->dropField($table, $field);
}
/**
* Sets the default value for a field.
*
* @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($table, $field, $default) {
return Database::getConnection()->schema()
->fieldSetDefault($table, $field, $default);
}
/**
* Sets a field to have no default value.
*
* @param $table
* The table to be altered.
* @param $field
* The field to be altered.
*/
function db_field_set_no_default($table, $field) {
return Database::getConnection()->schema()
->fieldSetNoDefault($table, $field);
}
/**
* Adds a primary key to a database table.
*
* @param $table
* Name of the table to be altered.
* @param $fields
* Array of fields for the primary key.
*/
function db_add_primary_key($table, $fields) {
return Database::getConnection()->schema()
->addPrimaryKey($table, $fields);
}
/**
* Drops the primary key of a database table.
*
* @param $table
* Name of the table to be altered.
*/
function db_drop_primary_key($table) {
return Database::getConnection()->schema()
->dropPrimaryKey($table);
}
/**
* Adds a unique key.
*
* @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($table, $name, $fields) {
return Database::getConnection()->schema()
->addUniqueKey($table, $name, $fields);
}
/**
* Drops a unique key.
*
* @param $table
* The table to be altered.
* @param $name
* The name of the key.
*/
function db_drop_unique_key($table, $name) {
return Database::getConnection()->schema()
->dropUniqueKey($table, $name);
}
/**
* Adds an index.
*
* @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($table, $name, $fields) {
return Database::getConnection()->schema()
->addIndex($table, $name, $fields);
}
/**
* Drops an index.
*
* @param $table
* The table to be altered.
* @param $name
* The name of the index.
*/
function db_drop_index($table, $name) {
return Database::getConnection()->schema()
->dropIndex($table, $name);
}
/**
* Changes 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('foo');
* db_change_field('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 $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($table, $field, $field_new, $spec, $keys_new = array()) {
return Database::getConnection()->schema()
->changeField($table, $field, $field_new, $spec, $keys_new);
}
/**
* @} End of "addtogroup schemaapi".
*/
/**
* Sets a session variable specifying the lag time for ignoring a slave server.
*/
function db_ignore_slave() {
$connection_info = Database::getConnectionInfo();
// Only set ignore_slave_server if there are slave servers being used, which
// is assumed if there are more than one.
if (count($connection_info) > 1) {
// Five minutes is long enough to allow the slave to break and resume
// interrupted replication without causing problems on the Drupal site from
// the old data.
$duration = variable_get('maximum_replication_lag', 300);
// Set session variable with amount of time to delay before using slave.
$_SESSION['ignore_slave_server'] = REQUEST_TIME + $duration;
}
}Functions
| Title | Deprecated | Summary |
|---|---|---|
| db_add_field | Adds a new field to a table. | |
| db_add_index | Adds an index. | |
| db_add_primary_key | Adds a primary key to a database table. | |
| db_add_unique_key | Adds a unique key. | |
| db_and | Returns a new DatabaseCondition, set to "AND" all conditions together. | |
| db_change_field | Changes a field definition. | |
| db_close | Closes the active database connection. | |
| db_condition | Returns a new DatabaseCondition, set to the specified conjunction. | |
| db_create_table | Creates a new table from a Drupal table definition. | |
| db_delete | Returns a new DeleteQuery object for the active database. | |
| db_driver | Retrieves the name of the currently active database driver. | |
| db_drop_field | Drops a field. | |
| db_drop_index | Drops an index. | |
| db_drop_primary_key | Drops the primary key of a database table. | |
| db_drop_table | Drops a table. | |
| db_drop_unique_key | Drops a unique key. | |
| db_escape_field | Restricts a dynamic column or constraint name to safe characters. | |
| db_escape_table | Restricts a dynamic table name to safe characters. | |
| db_field_exists | Checks if a column exists in the given table. | |
| db_field_names | Returns an array of field names from an array of key/index column specifiers. | |
| db_field_set_default | Sets the default value for a field. | |
| db_field_set_no_default | Sets a field to have no default value. | |
| db_find_tables | Finds all tables that are like the specified base table name. | |
| db_find_tables_d8 | Finds all tables that are like the specified base table name. This is a backport of the change made to db_find_tables in Drupal 8 to work with virtual, un-prefixed table names. The original function is retained for Backwards Compatibility. | |
| db_ignore_slave | Sets a session variable specifying the lag time for ignoring a slave server. | |
| db_index_exists | Checks if an index exists in the given table. | |
| db_insert | Returns a new InsertQuery object for the active database. | |
| db_like | Escapes characters that work as wildcard characters in a LIKE pattern. | |
| db_merge | Returns a new MergeQuery object for the active database. | |
| db_next_id | Retrieves a unique id. | |
| db_or | Returns a new DatabaseCondition, set to "OR" all conditions together. | |
| db_query | Executes an arbitrary query string against the active database. | |
| db_query_range | Executes a query against the active database, restricted to a range. | |
| db_query_temporary | Executes a SELECT query string and saves the result set to a temporary table. | |
| db_rename_table | Renames a table. | |
| db_select | Returns a new SelectQuery object for the active database. | |
| db_set_active | Sets a new active database. | |
| db_table_exists | Checks if a table exists. | |
| db_transaction | Returns a new transaction object for the active database. | |
| db_truncate | Returns a new TruncateQuery object for the active database. | |
| db_update | Returns a new UpdateQuery object for the active database. | |
| db_xor | Returns a new DatabaseCondition, set to "XOR" all conditions together. | |
| _db_create_keys_sql |
Classes
| Title | Deprecated | Summary |
|---|---|---|
| Database | Primary front-controller for the database system. | |
| DatabaseConnection | Base Database API class. | |
| DatabaseConnectionNotDefinedException | Exception thrown if an undefined database connection is requested. | |
| DatabaseDriverNotSpecifiedException | Exception thrown if no driver is specified for a database connection. | |
| DatabaseStatementBase | Default implementation of DatabaseStatementInterface. | |
| DatabaseStatementEmpty | Empty implementation of a database statement. | |
| DatabaseTransaction | A wrapper class for creating and managing database transactions. | |
| DatabaseTransactionCommitFailedException | Exception thrown when a commit() function fails. | |
| DatabaseTransactionExplicitCommitNotAllowedException | Exception to deny attempts to explicitly manage transactions. | |
| DatabaseTransactionNameNonUniqueException | Exception thrown when a savepoint or transaction name occurs twice. | |
| DatabaseTransactionNoActiveException | Exception for when popTransaction() is called with no active transaction. | |
| DatabaseTransactionOutOfOrderException | Exception thrown when a rollback() resulted in other active transactions being rolled-back. | |
| FieldsOverlapException | Exception thrown if an insert query specifies a field twice. | |
| InvalidMergeQueryException | Exception thrown for merge queries that do not make semantic sense. | |
| InvalidQueryConditionOperatorException | Exception thrown if an invalid query condition is specified. | |
| NoFieldsException | Exception thrown if an insert query doesn't specify insert or default fields. |
Interfaces
| Title | Deprecated | Summary |
|---|---|---|
| DatabaseStatementInterface | Represents a prepared statement. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.