Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Database API overview

Last updated on
October 14, 2016 - 21:12

The Drupal 7 Database API provides a standard, vendor-agnostic abstraction layer for accessing database servers. The API is designed to preserve the syntax and power of SQL as much as possible, but also:

  • to support multiple database servers easily;
  • to allow developers to leverage more complex functionality, such as transactions;
  • to provide a structured interface for the dynamic construction of queries;
  • to enforce security checks and other good practices;
  • to provide modules with a clean interface for intercepting and modifying a site's queries.

The main Database API documentation is derived directly from comments in the code. This Handbook section augments those API docs by providing a tutorial for module authors who wish to interact with the database system, as well as an overview of the system from an administrator's point of view. Note that this Handbook may not cover every feature of the API.

In Drupal 8, the API is pretty much the same, but you should almost never be making database calls directly unless you are developing core APIs. Generally use entity queries, etc.

The Database API was built with object-oriented design concepts, and this document therefore assumes at least a partial familiarity with those concepts. However, most common operations have a procedural front-end as well, and developers may choose to use the procedural style for more readable code.