8 database.inc db_query($query, array $args = array(), array $options = array())
4.6 database.inc db_query($query)
4.7 database.inc db_query($query)
5 database.inc db_query($query)
6 database.pgsql.inc db_query($query)
6 database.mysql-common.inc db_query($query)
7 database.inc db_query($query, array $args = array(), array $options = array())

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.


string|\Drupal\Core\Database\StatementInterface $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. If the argument corresponding to a placeholder is an array of values to be expanded, e.g. for an IN query, the placeholder should be named with a trailing bracket like :example[]

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

array $options: An array of options to control how the query operates.

Return value

\Drupal\Core\Database\StatementInterface A prepared statement object, already executed.


as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get a database connection injected into your service from the container and call query() on it. E.g. $injected_database->query($query, $args, $options);

See also



Related topics

160 calls to db_query()
AggregatorCronTest::testCron in core/modules/aggregator/src/Tests/AggregatorCronTest.php
Adds feeds and updates them via cron process.
AggregatorTestBase::createFeed in core/modules/aggregator/src/Tests/AggregatorTestBase.php
Creates an aggregator feed.
AggregatorTestBase::uniqueFeed in core/modules/aggregator/src/Tests/AggregatorTestBase.php
Checks whether the feed name and URL are unique.
AggregatorTestBase::updateAndDelete in core/modules/aggregator/src/Tests/AggregatorTestBase.php
Adds and deletes feed items and ensure that the count is zero.
AggregatorTestBase::updateFeedItems in core/modules/aggregator/src/Tests/AggregatorTestBase.php
Updates the feed items.

... See full list

2 string references to 'db_query'
Error::decodeException in core/lib/Drupal/Core/Utility/Error.php
Decodes an exception and retrieves the correct caller.
LoggingTest::testEnableLogging in core/modules/system/src/Tests/Database/LoggingTest.php
Tests that we can log the existence of a query.


core/includes/database.inc, line 56
Core systems for the database layer.


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


It should be noted that db_query() is way faster than db_select() to build the query, see https://drupal.org/node/1785086#comment-6533072

This is important for pages running a big number of queries.