Writing .install files (Drupal 6.x)
A .install file is run the first time a module is enabled, and is used to run setup procedures as required by the module. The most common task is creating database tables and fields. The .install file does not have any special syntax. It is merely a PHP file with a different extension.
.install files are also used to perform updates when a new version of a module needs it.
Instructions
Install instructions are enclosed in a _install() function. This hook will be called when the module is first enabled. Any number of functions can reside here, but the most typical use is to create the necessary tables for your module.
As of Drupal 6.x the database tables are created using the Schema API .
The Schema API allows modules to declare their database tables in a structured array (similar to the Form API) and provides API functions for creating, dropping, and changing tables, columns, keys, and indexes.
A sample schema data structure (taken from the Schema Api Documentation)
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;
?>There is also a module available called as Schema Module which provides additional Schema-related functionality not provided by the core Schema API that is useful for module developers. Currently, this includes:
- Schema documentation: hyperlinked display of the schema's embedded documentation explaining what each table and field is for.
- Schema structure generation: the module examines the live database and creates Schema API data structures for all tables that match the live database.
- Schema comparison: the module compares the live database structure with the schema structure declared by all enabled modules, reporting on any missing or incorrect tables.
Schema API looks a good
Schema API looks a good option for generating tables in a DB independent fashion. But I could not find solutions to some issues (like how to specify the Engine for MySql, or foreign key constraints or creating Stored Procedures & Functions).
Looks like this has to be done by getting a sql script executed. But the above doc does not detail how to get a Sql script executed during install/uninstall?
Can somebody document this aspect a bit??
--
I always think tomorrow will have more time than today.
And every today seems to pass-by faster than yesterday.
http://www.rahulsingla.com
You can still execute your sql in hook_install
The hook_install is executing the schema built earlier. Once that is executed the control is handed over to what ever is the next fucntion. You can execute any sql code using drupal database api.
function mymodule_install() {// Create my tables.
drupal_install_schema('mymodule');
//run custom sql query
db_query($sql, $parms);
}
http://www.m4manas.com
http://www.taxlaw.co.in
Interesting article about
Interesting article about using an install file to store frontend interactions of a Drupal project:
http://sachachua.com/wp/2009/04/23/drupal-staging-and-deployment-tips-it...
-------------------------------
peach from All Drupal Themes
Writing .install file after module has been activated
If you are writing the .install file LAST (ie after module has been activated), you need to make sure you disable the module and uninstall it first. Be careful though, as uninstalling removes everything in the table. Then by reactivating it, it should create the new table.
My suggestion before uninstalling is to rename the table name ie instead of 'node' name it to like 'node1'. You will get an error message, but at least it will not drop the entire 'node' table
Sometimes however...
Sometimes however happens that you have already enabled a module and you wanna add later the .install file to it. This way you cannot uninstall it because there's nothing installed, but the system doesn't see your new .install file.
To quickly solve this issue delete the entry of your module inside the system table.