When Drupal is installed, and when modules are enabled the install system runs the hook_install() functions for each module.
These install functions usually create tables in the database, add rows to some tables (for instance a module that has a custom node type may add the node type to the node_type table), or settings my be added to the variables table.
Here is an example of an install function from Content Templates module:
<?php
function contemplate_install() {
switch ($GLOBALS['db_type']) {
case 'mysql':
case 'mysqli':
db_query("CREATE TABLE {contemplate} (
type varchar(32) NOT NULL default '',
teaser text NOT NULL,
body text NOT NULL,
rss text NOT NULL,
enclosure varchar(128) NOT NULL,
flags int(8) unsigned NOT NULL default '7',
KEY type (type)
) /*!40100 DEFAULT CHARACTER SET utf8 */;");
db_query("CREATE TABLE {contemplate_files} (
site varchar(255) NOT NULL,
`data` longblob NOT NULL,
UNIQUE KEY site (site(255))
) /*!40100 DEFAULT CHARACTER SET utf8 */;");
db_query("UPDATE {system} SET weight = 10 WHERE name = 'contemplate'");
break;
case 'pgsql':
db_query("CREATE TABLE {contemplate} (
type varchar(32) NOT NULL default '',
teaser text NOT NULL,
body text NOT NULL,
rss text NOT NULL,
enclosure varchar(128) NOT NULL,
flags int_unsigned NOT NULL default '0',
PRIMARY KEY (type)
);");
db_query("CREATE TABLE {contemplate_files} (
site varchar(255) NOT NULL,
data bytea NOT NULL
);"); // This code is untested. Please post a fix to the issue queue if incorrect
db_query("CREATE UNIQUE INDEX {contemplate_files}_site_idx ON {contemplate_files} (site)");
db_query("UPDATE {system} SET weight = 10 WHERE name = 'contemplate'");
break;
}
drupal_set_message(t('Database tables for ConTemplate module have been installed.'));
}
?> You will see here that multiple database queries were run (based on the database type) creating 2 tables, then a message was set for the user to notity that the tables were installed.
There can also be hook_update_N() functions
example of hook_update_N() function from Content Templates module:
<?php
function contemplate_update_1() {
$ret = array();
switch ($GLOBALS['db_type']) {
case 'mysql':
case 'mysqli':
$ret[] = update_sql('ALTER TABLE {contemplate} ADD rss text NOT NULL');
$ret[] = update_sql('ALTER TABLE {contemplate} ADD enclosure varchar(128) NOT NULL');
$ret[] = update_sql("ALTER TABLE {contemplate} ADD flags int(8) unsigned NOT NULL default '7'");
break;
}
return $ret;
}
function contemplate_update_2() {
$ret = array();
switch ($GLOBALS['db_type']) {
case 'mysql':
case 'mysqli':
$ret[] = update_sql('CREATE TABLE {contemplate_files} (
site varchar(255) NOT NULL,
data longblob NOT NULL,
UNIQUE KEY site (site(255))
) /*!40100 DEFAULT CHARACTER SET utf8 */;');
break;
}
return $ret;
}
?> These update functions are meant to change older versions of this module's tables so they have the same structure as the tables created in the install function. Each of these update functions has a number associated with it. This number is the database schema version for this version of the module.
When this version of Content Templates is installed the installer takes a look at the hook_update_N() functions for the module and determines that this modules is using database schema version 2. The current database schema version is recorded in the system table for this module keyed by the module's short name 'contemplate'
When an new version of Content Templates is released there may be a change to the database schema for the module. We don't want the installer to run the hook_install() function again, we would get back a number of errors telling us that the tables already exist. There would be a new hook_update_N() function in the install file, probably called contemplate_update_3(). This function would have code that, when executed, would bring the old database schema version 2 to the same structure as schema version 3. The new database schema version is then recorded in the system table.
The hook_update_N() function should be run as soon as the new code is installed, because there probably is some code in the updated module that requires the new database schema. When you goto the page update.php you can start the process of updating your database by running the hook_update_N() functions in Drupal core and all contributed modules.
