CHAPTER 5 ■ WORKING WITH DATABASES

■ Tip You should rarely have to write a schema from scratch. Instead, use your existing table(s) and the schema module’s Inspect tab to have the schema module build the schema for you. You can also use other tools like the Table Wizard module (http://drupal.org/project/tw) to expose the details of any table in Drupal to the Views module.

The schema module also allows you to view the schema of any module. For example, Figure 5-4 shows the schema module’s display of the book module’s schema. Note how the table names that were in curly brackets in the table and field descriptions have been turned into helpful links.

Figure 5-4. The schema module displays the schema of the book module.

Field Type Mapping from Schema to Database

The field type that is declared in the schema definition maps to a native field type in the database. For example, an integer field with the declared size of tiny becomes a TINYINT field in MySQL but a small int field in PostgreSQL. The actual map can be viewed by printing the results of getFieldTypeMap() or by looking in Table 5-1 later in this chapter.

Textual

Textual fields contain text.

103

CHAPTER 5 ■ WORKING WITH DATABASES

Varchar

The varchar, or variable length character field, is the most frequently used field type for storing text less than 256 characters in length. A maximum length, in characters, is defined by the length key. MySQL varchar field lengths are 0–255 characters (MySQL 5.0.2 and earlier) and 0–65,535 characters (MySQL 5.0.3 and later); PostgreSQL varchar field lengths may be larger.

$field['fieldname'] = array(

'type' => 'varchar', // Required. 'length' => 255, // Required.

'not null' => TRUE, // Defaults to FALSE. 'default' => 'chocolate', // See below.

'description' => t('Always state the purpose of your field.'),

);

If the default key has not been set and the not null key has been set to FALSE, the default will be set to NULL.

Char

Char fields are fixed-length character fields. The length of the field, in characters, is defined by the length key. MySQL char field lengths are 0–255 characters.

'description' => t('Always state the purpose of your field.'),

);

If the default key has not been set and the not null key has been set to FALSE, the default will be set to NULL.

Text

Text fields are used for textual data that can be quite large. For example, the body field of the node_revisions table (where node body text is stored) is of this type. Default values may not be used for text fields.

$field['fieldname'] = array( 'type' => 'text', // Required.

'size' => 'small', // tiny | small | normal | medium | big 'not null' => TRUE, // Defaults to FALSE.

'description' => t('Always state the purpose of your field.'),

);

104

CHAPTER 5 ■ WORKING WITH DATABASES

Numerical

Numerical data types are used for storing numbers and include the integer, serial, float, and numeric types.

Integer

This field type is used for storing integers, such as node IDs. If the unsigned key is TRUE, negative integers will not be allowed.

$field['fieldname'] = array( 'type' => 'int', // Required.

'unsigned' => TRUE, // Defaults to FALSE.

'size' => 'small', // tiny | small | medium | normal | big 'not null' => TRUE, // Defaults to FALSE.

'description' => t('Always state the purpose of your field.'),

);

Serial

A serial field keeps a number that increments. For example, when a node is added, the nid field of the node table is incremented. This is done by inserting a row and calling db_last_insert_id(). If a row is added by another thread between the insertion of a row and the retrieval of the last ID, the correct ID is still returned because it is tracked on a per-connection basis. A serial field must be indexed; it is usually indexed as the primary key.

$field['fieldname'] = array(

);

Float

Floating point numbers are stored using the float data type. There is typically no difference between the tiny, small, medium, and normal sizes for a floating point number; in contrast, the big size specifies a double-precision field.

105

CHAPTER 5 ■ WORKING WITH DATABASES

Numeric

The numeric data type allows you to specify the precision and scale of a number. Precision is the total number of significant digits in the number; scale is the total number of digits to the right of the decimal point. For example, 123.45 has a precision of 5 and a scale of 2. The size key is not used. At the time of this writing, numeric fields are not used in the schema of the Drupal core.

$field['fieldname'] = array( 'type' => 'numeric', // Required.

'unsigned' => TRUE, // Defaults to FALSE. 'precision' => 5, // Significant digits.

'scale' => 2, // Digits to the right of the decimal. 'not null' => TRUE, // Defaults to FALSE.

'description' => t('Always state the purpose of your field.'),

);

Date and Time: Datetime

The Drupal core does not use this data type, preferring to use Unix timestamps in integer fields. The datetime format is a combined format containing both the date and the time.

$field['fieldname'] = array(

'type' => 'datetime', // Required.

'not null' => TRUE, // Defaults to FALSE.

'description' => t('Always state the purpose of your field.'),

);

Binary: Blob

The binary large object data (blob) type is used to store binary data (for example, Drupal’s cache table to store the cached data). Binary data may include music, images, or video. Two sizes are available, normal and big.

'description' => t('Always state the purpose of your field.'),

);

Declaring a Specific Column Type with mysql_type

If you know the exact column type for your database engine, you can set the mysql_type (or pgsql_type) key in your schema definition. This will override the type and size keys for that database engine. For example, MySQL has a field type called TINYBLOB for small binary large objects. To specify that Drupal should use TINYBLOB if it is running on MySQL but fall back to using the regular BLOB type if it is running on a different database engine, the field could be declared like so:

106

CHAPTER 5 ■ WORKING WITH DATABASES

The native types for MySQL and PostgreSQL are shown in Table 5-1.

Table 5-1. How Type and Size Keys in Schema Definitions Map to Native Database Types

107