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' => 'The base table for nodes.',
'fields' => array(
'nid' => array(
'description' => 'The primary identifier for a node.',
'type' => 'serial',
'unsigned' => TRUE,
'not null' => TRUE),
'vid' => array(
'description' => 'The current {node_revisions}.vid version identifier.',
'type' => 'int',
'unsigned' => TRUE,
'not null' => TRUE,
'default' => 0),
'type' => array(
'description' => 'The {node_type} of this node.',
'type' => 'varchar',
'length' => 32,
'not null' => TRUE,
'default' => ''),
'title' => array(
'description' => '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: one named 'vid' on the field 'vid' and another called 'nid_vid' on fields 'nid' and 'vid'. And there are 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');
}
?>Making sure your schema gets updated
If you release a new version of your module and it needs to have a new database schema, you need to do two things to make this change work. First, be sure to update the schema structure in mymodule_schema() so that new installations of your module get the new database table structure. Second, use a hook_update_N() function, as in previous versions of Drupal, to make sure that existing installations of your module can be updated to your new version. For example, suppose you add a new column called 'newcol' to table 'mytable1' in your module. You would need to add an update function to mymodule.install:
<?php
function mymodule_update_6100() {
$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 into 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
You can also just comment
You can also just comment out the following lines from the "schema_mysql_inspect()" function found in the file "engines/schema_mysql.inc" (for mysql at least):
<?php
// Ignore tables not in Drupal's schema.
if (!isset($schema[$r['TABLE_NAME']])) {
continue;
}
?>
That way you can still get the schema definitions without modifying your modules. This is for the Drupal 5 version of the Schema module.
What Drupal data types are supported?
I just want a list of the supported Drupal data types in an .install file. Where can
I find this?
Thanks,
Andy
Never mind ... I found it in
Never mind ... I found it in http://api.drupal.org/api/group/schemaapi/6 , in case anyone else needs it.
Sorry for missing it originally.
'created' and 'changed' fields not in example code
Although the example is an excerpt from the actual 'node' table schema, it might be useful for the consistency of the reference to include the fields 'changed' and 'created' in the code so as to not be confused about the 'indexes' section of the table definition. I know it states "And there are two indexes, one named 'node_changed' on field 'changed' and one named 'node_created' on the field 'created'" but I completely missed that the first time around :P.
Example above with added fields from node.install:
<?php$schema['node'] = array(
'description' => 'The base table for nodes.',
'fields' => array(
'nid' => array(
'description' => 'The primary identifier for a node.',
'type' => 'serial',
'unsigned' => TRUE,
'not null' => TRUE),
'vid' => array(
'description' => 'The current {node_revisions}.vid version identifier.',
'type' => 'int',
'unsigned' => TRUE,
'not null' => TRUE,
'default' => 0),
'type' => array(
'description' => 'The {node_type} of this node.',
'type' => 'varchar',
'length' => 32,
'not null' => TRUE,
'default' => ''),
'title' => array(
'description' => 'The title of this node, always treated a non-markup plain text.',
'type' => 'varchar',
'length' => 255,
'not null' => TRUE,
'default' => ''),
'created' => array(
'description' => 'The Unix timestamp when the node was created.',
'type' => 'int',
'not null' => TRUE,
'default' => 0),
'changed' => array(
'description' => 'The Unix timestamp when the node was most recently saved.',
'type' => 'int',
'not null' => TRUE,
'default' => 0),
),
'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'),
);
?>