Introduction to Drupal’s Database Abstraction Layer (DBTNG)

Authored by Steve Williams

The release of Drupal 7 introduced a new database abstraction layer build on top of PHP’s Data Object API (PDO). This new Database API provides an abstraction layer allowing for pluggable database drivers. The API is designed with an object-oriented approach providing the ability to dynamically build queries. DBTNG provides for extending, merging, transactions, and chaining of queries. This post will demonstrate how to build a query and return the output in a sortable table.

You can still write static queries using the legacy db_query method, but for building dynamic queries you will need to use db_select. The first step in building your query is to define a table and table alias. In our example, we will be querying the node table with “n” as the alias.

function mynode_list() {      $query = db_select('node', 'n');

With our node table selected we now define our fields. You can call all fields in a table.

   $query->fields('n')

You can also select specific fields by adding an array of field names.

   $query->fields('n', array('nid', 'title', 'status', 'created', 'changed'))

Conditions can be defined by specifying the table alias, field to act on, the value of the condition and the operator. In our query we will add a condition for type = page.

      ->condition('n.type', 'page', '=');

With our fields selected and our condition in place we can now define the table headers, provide translatable labels and include fields for sorting.

    $header = array(              array('data' => t('nid'), 'field' => 'nid', 'sort' => 'asc'),              array('data' => t('Title'), 'field' => 'title'),              array('data' => t('Status'), 'field' => 'status'),              array('data' => t('Created'), 'field' => 'created'),              array('data' => t('Changed'), 'field' => 'changed'),      );

In order to provide dynamic header sorting we need to extend our query to add sorting and ordering on the header array.

    $query->extend('TableSort')           ->orderByHeader($header);

With the building of our query complete we can now execute and loop through the results.

    // Execute the query.        $result = $query->execute();        // Loop through results and define map fields to a row output.          foreach ($result as $record) {              $output_rows[] = array(                  $record->nid,                  $record->title,                  $record->status,                  date("Y-M-d", $record->created),                  date("Y-M-d", $record->changed),              );          }

Finally, we pass the results into a table with sortable headers using Drupal’s theme API and return the output.

// Pass your header and output rows to Drupal's theme.        $output = theme('table', array('header' => $header, 'rows' => $output_rows ) );        return $output;    }

For additional functionality PHP’s PDO statements can be appended on execution.