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.

Parameters

$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.

$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.

$options: An associative array of options to control how the query is run. See the documentation for DatabaseConnection::defaultOptions() for details.

Return value

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

13 calls to DatabaseConnection::query()

DatabaseConnection::popCommittableTransactions in includes/database/database.inc

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

DatabaseConnection::pushTransaction in includes/database/database.inc

Increases the depth of transaction nesting.

DatabaseConnection::rollback in includes/database/database.inc

Rolls back the transaction entirely or to a named savepoint.

DatabaseConnection_mysql::nextId in includes/database/mysql/database.inc

Retrieves an unique id from a given sequence.

DatabaseConnection_mysql::nextIdDelete in includes/database/mysql/database.inc

... See full list

1 method overrides DatabaseConnection::query()

DatabaseConnection_pgsql::query in includes/database/pgsql/database.inc

Executes a query string against the database.

File

includes/database/database.inc, line 728

Class

DatabaseConnection

Base Database API class.

Code

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;
    }
}

---