CHAPTER 5 ■ WORKING WITH DATABASES

'primary key' => array('bid'), 'indexes' => array(

'tons' => array('tons'),

),

);

return $schema;

}

Inserting a new record is easy, as is updating a record:

$table = 'bunnies'; $record = new stdClass();

$record->name = t('Bortha'); $record->tons = 2; drupal_write_record($table, $record);

//The new bunny ID, $record->bid, was set by drupal_write_record()

//since $record is passed by reference.

watchdog('bunny', 'Added bunny with id %id.', array('%id' => $record->bid));

//Change our mind about the name. $record->name = t('Bertha');

//Now update the record in the database.

//For updates we pass in the name of the table's primary key. drupal_write_record($table, $record, 'bid');

watchdog('bunny', 'Updated bunny with id %id.', array('%id' => $record->bid));

Array syntax is also supported, though if $record is an array, drupal_write_record() will convert the array to an object internally.

The Schema API

Drupal supports multiple databases (MySQL, PostreSQL, SQLite, etc.) through its database abstraction layer. Each module that wants to have a database table describes that table to Drupal using a schema definition. Drupal then translates the definition into syntax that is appropriate for the database.

99

100

CHAPTER 5 ■ WORKING WITH DATABASES

Figure 5-3. The schema definition is used to create the database tables.

Let’s take a look at the schema definition for Drupal’s book table, found in modules/book/book.install:

/**

* Implements hook_schema(). */

function book_schema() { $schema['book'] = array(

'description' => 'Stores book outline information. Uniquely connects each node in the outline to a link in {menu_links}',

'fields' => array( 'mlid' => array( 'type' => 'int',

'unsigned' => TRUE, 'not null' => TRUE,

101

CHAPTER 5 ■ WORKING WITH DATABASES

'default' => 0,

'description' => "The book page's {menu_links}.mlid.",

),

'nid' => array( 'type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,

'description' => "The book page's {node}.nid.",

),

'bid' => array( 'type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,

'description' => "The book ID is the {book}.nid of the top-level page.",

),

),

'primary key' => array('mlid'), 'unique keys' => array(

'nid' => array('nid'),

),

'indexes' => array( 'bid' => array('bid'),

),

);

return $schema;

}

This schema definition describes the book table, which has three fields of type int. It also has a primary key, a unique index (which means all entries in that field are unique), and a regular index. Notice that when a field from another table is referred to in the field description, curly brackets are used. That enables the schema module (see the next section) to build handy hyperlinks to table descriptions.

Using the Schema Module

At this point, you may be thinking, “What a pain! Building these big descriptive arrays to tell Drupal about my tables is going to be sheer drudgery.” But do not fret. Simply download the schema module from http://drupal.org/project/schema and enable it on your site. Going to Structure -> Schema will give you the ability to see a schema definition for any database table by clicking the Inspect tab. So if you have used SQL to create your table, you can get the schema definition by using the schema module, and then copy and paste it into your .install file.

102