Quick start guide
A sample schema data structure
As an example, here is an excerpt of the schema definition for Drupal's 'node' table:
<?php
$schema['node'] = array(
'description' => t('The base table for nodes.'),
'fields' => array(
'nid' => array(
'description' => t('The primary identifier for a node.'),
'type' => 'serial',
'unsigned' => TRUE,
'not null' => TRUE),
'vid' => array(
'description' => t('The current {node_revisions}.vid version identifier.'),
'type' => 'int',
'unsigned' => TRUE,
'not null' => TRUE,
'default' => 0),
'type' => array(
'description' => t('The {node_type} of this node.'),
'type' => 'varchar',
'length' => 32,
'not null' => TRUE,
'default' => ''),
'title' => array(
'description' => t('The title of this node, always treated a non-markup plain text.'),
'type' => 'varchar',
'length' => 255,
'not null' => TRUE,
'default' => ''),
),
'indexes' => array(
'node_changed' => array('changed'),
'node_created' => array('created'),
),
'unique keys' => array(
'nid_vid' => array('nid', 'vid'),
'vid' => array('vid')
),
'primary key' => array('nid'),
);
?>In this excerpt, the table 'node' has four fields (table columns) named 'nid', 'vid', 'type', and 'title'. Each field specifies its type ('serial', 'int', or 'varchar' in this example) and some additional optional parameters, including a description.
The table's primary key is the single field 'nid'. There are two unique keys: first named 'vid' on the field 'vid' and second called 'nid_vid' on fields 'nid' and 'vid'. Two indexes, one named 'node_changed' on field 'changed' and one named 'node_created' on the field 'created'.
Creating tables: hook_schema and .install files
For the Schema API to manage a module's tables, the module must have a .install file that implements hook_schema() (note: in a pre-release version, hook_schema() was in a .schema file but that is no longer used.) For example, mymodule's mymodule.install file might contain:
<?php
function mymodule_schema() {
$schema['mytable1'] = array(
// specification for mytable1
);
$schema['mytable2'] = array(
// specification for mytable2
);
return $schema;
}
function mymodule_install() {
// Create my tables.
drupal_install_schema('mymodule');
}
function mymodule_uninstall() {
// Drop my tables.
drupal_uninstall_schema('mymodule');
}
?>Updating your schema for new versions works just as it has since Drupal 4.7, using a hook_update_n() function. Suppose you add a new column called 'newcol' to mytable1. First, be sure to update your schema structure in mymodule_schema() so that newly created tables get the new column. Then, add an update function to mymodule.install:
<?php
function mymodule_update_1() {
$ret = array();
db_add_field($ret, 'mytable1', 'newcol', array('type' => 'int'));
return $ret;
?>Shortcut: Use the contributed schema.module to create an entire hook_schema() for you.
If you have an existing module that needs to begin making use of this new schema API structure, you do not have to manually create the schema definitions for your .install file. If you have the Schema contrib module, it will do it for you. With schema.module installed, visit Administer > Site building > Schema, then the "Inspect" tab.
On the Inspect tab, the Schema module generates and displays schema data structures for all tables in the database. Tables that are owned by a module are listed under that module name. Other tables are listed under the name "Unknown." Since your module's tables are not yet defined by a hook_schema, they will be in the Unknown group. Just copy and paste the schema structure for each of your tables in your module's hook_schema function in the .install file and remember to return $schema; at the end.
Schema module requires MySQL 5.02+
You cannot use schema module to generate reports on MySQL < 5.02. The module requires features only available for MySQL 5.
--
http://ken.blufftontoday.com/
http://new.savannahnow.com/user/2
Search first, ask good questions later.
Note, if you're upgrading
Note, if you're upgrading drupal 5 modules, you must first define skeleton table schemas for each module you want details for.
Eg: -- workflow_ng/states/states.install:
<?phpfunction states_schema() {
$schema['node_state'] = array();
$schema['users_state'] = array();
$schema['states_custom'] = array();
return $schema;
?>
Don't forget the return! This will give you all the fields that you might have previously not been able to see.
Reference: http://drupal.org/node/223952
Reorganize Document
I will suggest to move the "Shortcut: Use contributed schema.module..." to the TOP of the page.... I wasted some time writing the stuff by hand...