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.
$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.
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.
PDOException
Overrides DatabaseConnection::query
public function query($query, array $args = array(), $options = array()) {
$options += $this
->defaultOptions();
// The PDO PostgreSQL driver has a bug which
// doesn't type cast booleans correctly when
// parameters are bound using associative
// arrays.
// See http://bugs.php.net/bug.php?id=48383
foreach ($args as &$value) {
if (is_bool($value)) {
$value = (int) $value;
}
}
try {
if ($query instanceof DatabaseStatementInterface) {
$stmt = $query;
$stmt
->execute(NULL, $options);
}
else {
$this
->expandArguments($query, $args);
$stmt = $this
->prepareQuery($query);
$stmt
->execute($args, $options);
}
switch ($options['return']) {
case Database::RETURN_STATEMENT:
return $stmt;
case Database::RETURN_AFFECTED:
return $stmt
->rowCount();
case Database::RETURN_INSERT_ID:
return $this
->lastInsertId($options['sequence_name']);
case Database::RETURN_NULL:
return;
default:
throw new PDOException('Invalid return directive: ' . $options['return']);
}
} catch (PDOException $e) {
if ($options['throw_exception']) {
// Add additional debug information.
if ($query instanceof DatabaseStatementInterface) {
$e->query_string = $stmt
->getQueryString();
}
else {
$e->query_string = $query;
}
$e->args = $args;
throw $e;
}
return NULL;
}
}