Common definitions

The Drupal database layer is built on top of the PHP PDO library. PDO provides a unified, object-oriented API for accessing various databases, but it does not offer abstraction for the different SQL dialects used by different database systems.

Drivers

Because different databases require different types of interaction, Drupal’s database layer requires a driver for each database type. A driver consists of a series of files located in include/database/driver, where driver is a string representing a unique key for that driver. In most cases, the driver key is a lowercase version of the database name, such as “mysql”, “pgsql”, or “mycustomdriver”.

Each driver consists of several classes that inherit from the parent classes in the base database system. These driver-specific classes may override any behavior necessary to properly support that database type. Driver-specific classes are always named after their parent class, followed by an underscore and then the driver name. For example, the MySQL-specific version of InsertQuery is called InsertQuery_mysql.

Connections

A connection is an object of the class DatabaseConnection, which inherits from the PDO class. Each database Drupal connects to has one associated connection object. This connection object must be subclassed for each specific driver.

To access (and if necessary, open) the connection object, use:

$database = \Drupal::database();
// Or
$database = \Drupal::service('database');

If services are not yet available, you can use \Drupal\Core\Database\Database::getConnection() to get a database connection.

For more information about connection keys and targets, see the Database Configuration documentation page.

To get access to the currently active connection, use:

$conn =  \Drupal\Core\Database\Database::getConnection();

This retrieves the default target for the active connection.

Note that in the vast majority of cases, you don’t need to request the connection object directly. Instead, procedural wrappers will do this for you. The only reason you would ever need direct access to the connection object is if you are performing complex manipulation with multiple databases and don’t want to switch the active database.

To set the active connection, use:

$conn = \Drupal\Core\Database\Database::setActiveConnection('external');

See the next section, Database Configuration, for details on connection keys and targets.

Queries

A query is a SQL statement that will be sent to a database connection. The database system supports six types of queries: static, dynamic, insert, update, delete, and merge. Some queries are written as SQL string templates (prepared statements), while others use object-oriented query builders. A “query object” refers to an instance of a query builder for one of these query types.

Statements

A statement object is the result of a select query. It will always be of type DatabaseStatement, or possibly a subclass of DatabaseStatement. DatabaseStatement extends the PDOStatement class.

Drupal uses prepared statements for all queries. A prepared statement is a query template where values will be inserted at execution time. Think of a prepared statement as the SQL equivalent of a function that is later invoked with arguments.

In standard PDO, you must explicitly prepare a statement object and then execute it with specific values bound to placeholders in the query. The statement can then be iterated as a result set. In effect, the statement and result set are synonymous—but only after the statement has been executed.

Drupal does not expose the prepared statement directly. Instead, the module developer uses a query object or one-time SQL string to execute the query, and a statement object for that query is returned. Thus, the terms “statement object” and “result set object” are more or less synonymous.