Schema API


	drupal_get_schema ($table=NULL, $rebuild=FALSE)
	drupal_install_schema ($module)
	drupal_uninstall_schema ($module)
	drupal_get_schema_unprocessed ($module, $table=NULL)
	_drupal_initialize_schema ($module, &$schema)
	drupal_schema_fields_sql ($table, $prefix=NULL)
	drupal_write_record ($table, &$object, $update=array())
	db_create_table_sql ($name, $table)
	_db_create_keys_sql ($spec)
	_db_create_key_sql ($fields)
	_db_process_field ($field)
	_db_create_field_sql ($name, $spec)
	db_rename_table (&$ret, $table, $new_name)
	db_drop_table (&$ret, $table)
	db_add_field (&$ret, $table, $field, $spec, $keys_new=array())
	db_drop_field (&$ret, $table, $field)
	db_field_set_default (&$ret, $table, $field, $default)
	db_field_set_no_default (&$ret, $table, $field)
	db_add_primary_key (&$ret, $table, $fields)
	db_drop_primary_key (&$ret, $table)
	db_add_unique_key (&$ret, $table, $name, $fields)
	db_drop_unique_key (&$ret, $table, $name)
	db_add_index (&$ret, $table, $name, $fields)
	db_drop_index (&$ret, $table, $name)
	db_change_field (&$ret, $table, $field, $field_new, $spec, $keys_new=array())
	db_last_insert_id ($table, $field)
	db_type_map ()
	_db_create_index_sql ($table, $name, $fields)
	_db_create_keys (&$ret, $table, $new_keys)
Functions
	db_create_table (&$ret, $name, $table)
	db_field_names ($fields)
	db_type_placeholder ($type)

Detailed Description

End of "defgroup database".

A Drupal schema definition is an array structure representing one or more tables and their related keys and indexes. A schema is defined by hook_schema(), which usually lives in a modulename.install file.

By implementing hook_schema() and specifying the tables your module declares, you can easily create and drop these tables on all supported database engines. You don't have to deal with the different SQL dialects for table creation and alteration of the supported database engines.

hook_schema() should return an array with a key for each table that the module defines.

The following keys are defined:

'description': A string describing this table and its purpose. References to other tables should be enclosed in curly-brackets. For example, the node_revisions table description field might contain "Stores per-revision title and body data for each {node}."
'fields': An associative array ('fieldname' => specification) that describes the table's database columns. The specification is also an array. The following specification parameters are defined:

'description': A string describing this field and its purpose. References to other tables should be enclosed in curly-brackets. For example, the node table vid field description might contain "Always holds the largest (most recent) {node_revisions}.vid value for this nid."
'type': The generic datatype: 'varchar', 'int', 'serial' 'float', 'numeric', 'text', 'blob' or 'datetime'. Most types just map to the according database engine specific datatypes. Use 'serial' for auto incrementing fields. This will expand to 'int auto_increment' on mysql.
'size': The data size: 'tiny', 'small', 'medium', 'normal', 'big'. This is a hint about the largest value the field will store and determines which of the database engine specific datatypes will be used (e.g. on MySQL, TINYINT vs. INT vs. BIGINT). 'normal', the default, selects the base type (e.g. on MySQL, INT, VARCHAR, BLOB, etc.).

Not all sizes are available for all data types. See db_type_map() for possible combinations.

'not null': If true, no NULL values will be allowed in this database column. Defaults to false.
'default': The field's default value. The PHP type of the value matters: '', '0', and 0 are all different. If you specify '0' as the default value for a type 'int' field it will not work because '0' is a string containing the character "zero", not an integer.
'length': The maximal length of a type 'varchar' or 'text' field. Ignored for other field types.
'unsigned': A boolean indicating whether a type 'int', 'float' and 'numeric' only is signed or unsigned. Defaults to FALSE. Ignored for other field types.
'precision', 'scale': For type 'numeric' fields, indicates the precision (total number of significant digits) and scale (decimal digits right of the decimal point). Both values are mandatory. Ignored for other field types.

All parameters apart from 'type' are optional except that type 'numeric' columns must specify 'precision' and 'scale'.

'primary key': An array of one or more key column specifiers (see below) that form the primary key.
'unique key': An associative array of unique keys ('keyname' => specification). Each specification is an array of one or more key column specifiers (see below) that form a unique key on the table.
'indexes': An associative array of indexes ('indexame' => specification). Each specification is an array of one or more key column specifiers (see below) that form an index on the table.

A key column specifier is either a string naming a column or an array of two elements, column name and length, specifying a prefix of the named column.

As an example, here is a SUBSET of the schema definition for Drupal's 'node' table. It show four fields (nid, vid, type, and title), the primary key on field 'nid', a unique key named 'vid' on field 'vid', and two indexes, one named 'nid' on field 'nid' and one named 'node_title_type' on the field 'title' and the first four bytes of the field 'type':

 $schema['node'] = array(
   'fields' => array(
     'nid'      => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE),
     'vid'      => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
     'type'     => array('type' => 'varchar', 'length' => 32, 'not null' => TRUE, 'default' => ''),
     'title'    => array('type' => 'varchar', 'length' => 128, 'not null' => TRUE, 'default' => ''),
   ),
   'primary key' => array('nid'),
   'unique keys' => array(
     'vid'     => array('vid')
   ),
   'indexes' => array(
     'nid'                 => array('nid'),
     'node_title_type'     => array('title', array('type', 4)),
   ),
 );

See also:: drupal_install_schema()

Function Documentation

_db_create_field_sql	(	$	name,
		$	spec
	)

Create an SQL string for a field to be used in table creation or alteration.

Before passing a field out of a schema definition into this function it has to be processed by _db_process_field().

Parameters:

	$name	Name of the field.
	$spec	The field specification, as per the schema data structure format.

Definition at line 156 of file database.mysql-common.inc.

References $name.

Referenced by db_add_field(), db_change_field(), and db_create_table_sql().

_db_create_index_sql	(	$	table,
		$	name,
		$	fields
	)

Definition at line 527 of file database.pgsql.inc.

References $name, and _db_create_key_sql().

Referenced by db_add_index(), and db_create_table_sql().

Here is the call graph for this function:

_db_create_key_sql ( $ fields )

Definition at line 107 of file database.mysql-common.inc.

Referenced by _db_create_index_sql(), _db_create_keys_sql(), db_add_index(), db_add_primary_key(), and db_add_unique_key().

_db_create_keys	(	&$	ret,
		$	table,
		$	new_keys
	)

Definition at line 546 of file database.pgsql.inc.

References $name, db_add_index(), db_add_primary_key(), and db_add_unique_key().

Referenced by db_add_field(), and db_change_field().

Here is the call graph for this function:

_db_create_keys_sql ( $ spec )

Definition at line 87 of file database.mysql-common.inc.

References _db_create_key_sql().

Referenced by db_add_field(), db_change_field(), and db_create_table_sql().

Here is the call graph for this function:

_db_process_field ( $ field )

Set database-engine specific properties for a field.

Parameters:

$field

A field description array, as specified in the schema documentation.

Definition at line 126 of file database.mysql-common.inc.

References db_type_map().

Referenced by db_add_field(), db_change_field(), and db_create_table_sql().

Here is the call graph for this function:

_drupal_initialize_schema	(	$	module,
		&$	schema
	)

Fill in required default values for table definitions returned by hook_schema().

Parameters:

	$module	The module for which hook_schema() was invoked.
	$schema	The schema definition array as it was returned by the module's hook_schema().

Definition at line 3170 of file common.inc.

References $name.

Referenced by drupal_get_schema(), drupal_install_schema(), and drupal_uninstall_schema().

db_add_field	(	&$	ret,
		$	table,
		$	field,
		$	spec,
		$	keys_new = `array()`
	)

Add a new field to a table.

Parameters:

	$ret	Array to which query results will be added.
	$table	Name of the table to be altered.
	$field	Name of the field to be added.
	$spec	The field specification array, as taken from a schema definition. The specification may also contain the key 'initial', the newly created field will be set to the value of the key in all rows. This is most useful for creating NOT NULL columns with no default value in existing tables.
	$keys_new	Optional keys and indexes specification to be created on the table along with adding the field. The format is the same as a table specification but without the 'fields' element. If you are adding a type 'serial' field, you MUST specify at least one key or index including it in this array.

See also:: db_change_field for more explanation why.

Definition at line 287 of file database.mysql-common.inc.

References $result, _db_create_field_sql(), _db_create_keys_sql(), _db_process_field(), check_plain(), db_change_field(), db_query(), db_type_placeholder(), and update_sql().

Referenced by db_change_field(), and update_fix_d6_requirements().

Here is the call graph for this function:

db_add_index	(	&$	ret,
		$	table,
		$	name,
		$	fields
	)

Add an index.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$name	The name of the index.
	$fields	An array of field names.

Definition at line 432 of file database.mysql-common.inc.

References $name, _db_create_key_sql(), and update_sql().

Referenced by _db_create_keys().

Here is the call graph for this function:

db_add_primary_key	(	&$	ret,
		$	table,
		$	fields
	)

Add a primary key.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$fields	Fields for the primary key.

Definition at line 372 of file database.mysql-common.inc.

References _db_create_key_sql(), and update_sql().

Referenced by _db_create_keys().

Here is the call graph for this function:

db_add_unique_key	(	&$	ret,
		$	table,
		$	name,
		$	fields
	)

Add a unique key.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$name	The name of the key.
	$fields	An array of field names.

Definition at line 401 of file database.mysql-common.inc.

References $name, _db_create_key_sql(), and update_sql().

Referenced by _db_create_keys().

Here is the call graph for this function:

db_change_field	(	&$	ret,
		$	table,
		$	field,
		$	field_new,
		$	spec,
		$	keys_new = `array()`
	)

Change a field definition.

IMPORTANT NOTE: To maintain database portability, you have to explicitly recreate all indices and primary keys that are using the changed field.

That means that you have to drop all affected keys and indexes with db_drop_{primary_key,unique_key,index}() before calling db_change_field(). To recreate the keys and indices, pass the key definitions as the optional $keys_new argument directly to db_change_field().

For example, suppose you have:

 $schema['foo'] = array(
   'fields' => array(
     'bar' => array('type' => 'int', 'not null' => TRUE)
   ),
   'primary key' => array('bar')
 );

and you want to change foo.bar to be type serial, leaving it as the primary key. The correct sequence is:

 db_drop_primary_key($ret, 'foo');
 db_change_field($ret, 'foo', 'bar', 'bar',
   array('type' => 'serial', 'not null' => TRUE),
   array('primary key' => array('bar')));

The reasons for this are due to the different database engines:

On PostgreSQL, changing a field definition involves adding a new field and dropping an old one which* causes any indices, primary keys and sequences (from serial-type fields) that use the changed field to be dropped.

On MySQL, all type 'serial' fields must be part of at least one key or index as soon as they are created. You cannot use db_add_{primary_key,unique_key,index}() for this purpose because the ALTER TABLE command will fail to add the column without a key or index specification. The solution is to use the optional $keys_new argument to create the key or index at the same time as field.

You could use db_add_{primary_key,unique_key,index}() in all cases unless you are converting a field to be type serial. You can use the $keys_new argument in all cases.

Parameters:

	$ret	Array to which query results will be added.
	$table	Name of the table.
	$field	Name of the field to change.
	$field_new	New name for the field (set to the same as $field if you don't want to change the name).
	$spec	The field specification for the new field.
	$keys_new	Optional keys and indexes specification to be created on the table along with changing the field. The format is the same as a table specification but without the 'fields' element.

Definition at line 514 of file database.mysql-common.inc.

References _db_create_field_sql(), _db_create_keys_sql(), _db_process_field(), and update_sql().

Referenced by db_add_field().

Here is the call graph for this function:

db_create_table	(	&$	ret,
		$	name,
		$	table
	)

Create a new table from a Drupal table definition.

Parameters:

	$ret	Array to which query results will be added.
	$name	The name of the table to create.
	$table	A Schema API table definition array.

Definition at line 501 of file database.inc.

References $name, db_create_table_sql(), and update_sql().

Referenced by drupal_install_schema(), update_create_batch_table(), and update_fix_d6_requirements().

Here is the call graph for this function:

db_create_table_sql	(	$	name,
		$	table
	)

Generate SQL to create a new table from a Drupal schema definition.

Parameters:

	$name	The name of the table to create.
	$table	A Schema API table definition array.

Returns:: An array of SQL statements to create the table.

Definition at line 60 of file database.mysql-common.inc.

References $name, _db_create_field_sql(), _db_create_keys_sql(), and _db_process_field().

Referenced by db_create_table().

Here is the call graph for this function:

db_drop_field	(	&$	ret,
		$	table,
		$	field
	)

Drop a field.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$field	The field to be dropped.

Definition at line 321 of file database.mysql-common.inc.

References update_sql().

Referenced by db_change_field().

Here is the call graph for this function:

db_drop_index	(	&$	ret,
		$	table,
		$	name
	)

Drop an index.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$name	The name of the index.

Definition at line 447 of file database.mysql-common.inc.

References $name, and update_sql().

Here is the call graph for this function:

db_drop_primary_key	(	&$	ret,
		$	table
	)

Drop the primary key.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.

Definition at line 385 of file database.mysql-common.inc.

References update_sql().

Here is the call graph for this function:

db_drop_table	(	&$	ret,
		$	table
	)

Drop a table.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be dropped.

Definition at line 260 of file database.mysql-common.inc.

References update_sql().

Referenced by drupal_uninstall_schema(), and DrupalWebTestCase::tearDown().

Here is the call graph for this function:

db_drop_unique_key	(	&$	ret,
		$	table,
		$	name
	)

Drop a unique key.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$name	The name of the key.

Definition at line 416 of file database.mysql-common.inc.

References $name, and update_sql().

Here is the call graph for this function:

db_field_names ( $ fields )

Return an array of field names from an array of key/index column specifiers.

This is usually an identity function but if a key/index uses a column prefix specification, this function extracts just the name.

Parameters:

$fields

An array of key/index column specifiers.

Returns:: An array of field names.

Definition at line 519 of file database.inc.

db_field_set_default	(	&$	ret,
		$	table,
		$	field,
		$	default
	)

Set the default value for a field.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$field	The field to be altered.
	$default	Default value to be set. NULL for 'default NULL'.

Definition at line 337 of file database.mysql-common.inc.

References update_sql().

Here is the call graph for this function:

db_field_set_no_default	(	&$	ret,
		$	table,
		$	field
	)

Set a field to have no default value.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be altered.
	$field	The field to be altered.

Definition at line 358 of file database.mysql-common.inc.

References update_sql().

Here is the call graph for this function:

db_last_insert_id	(	$	table,
		$	field
	)

Returns the last insert id.

Parameters:

	$table	The name of the table you inserted into.
	$field	The name of the autoincrement field.

Definition at line 531 of file database.mysql-common.inc.

References db_query(), and db_result().

Referenced by actions_save(), batch_process(), block_add_block_form_submit(), drupal_write_record(), and menu_link_save().

Here is the call graph for this function:

db_rename_table	(	&$	ret,
		$	table,
		$	new_name
	)

Rename a table.

Parameters:

	$ret	Array to which query results will be added.
	$table	The table to be renamed.
	$new_name	The new name for the table.

Definition at line 248 of file database.mysql-common.inc.

References update_sql().

Here is the call graph for this function:

db_type_map ( )

End of "ingroup database". This maps a generic data type in combination with its data size to the engine-specific data type.

Definition at line 441 of file database.pgsql.inc.

db_type_placeholder ( $ type )

Given a Schema API field type, return the correct -placeholder.

Embed the placeholder in a query to be passed to db_query and and pass as an argument to db_query a value of the specified type.

Parameters:

$type

The Schema API type of a field.

Returns:: The placeholder string to embed in a query for that type.

Definition at line 543 of file database.inc.

References $type.

Referenced by db_add_field(), db_placeholders(), and drupal_write_record().

drupal_get_schema	(	$	table = `NULL`,
		$	rebuild = `FALSE`
	)

Get the schema definition of a table, or the whole database schema.

The returned schema will include any modifications made by any module that implements hook_schema_alter().

Parameters:

	$table	The name of the table. If not given, the schema of all tables is returned.
	$rebuild	If true, the schema will be rebuilt instead of retrieved from the cache.

Definition at line 3037 of file common.inc.

References _drupal_initialize_schema(), cache_get(), cache_set(), drupal_alter(), module_implements(), module_invoke(), and module_load_all_includes().

Referenced by drupal_schema_fields_sql(), drupal_write_record(), profile_field_form_validate(), and DrupalWebTestCase::tearDown().

Here is the call graph for this function:

drupal_get_schema_unprocessed	(	$	module,
		$	table = `NULL`
	)

Returns the unprocessed and unaltered version of a module's schema.

Use this function only if you explicitly need the original specification of a schema, as it was defined in a module's hook_schema(). No additional default values will be set, hook_schema_alter() is not invoked and these unprocessed definitions won't be cached.

This function can be used to retrieve a schema specification in hook_schema(), so it allows you to derive your tables from existing specifications.

It is also used by drupal_install_schema() and drupal_uninstall_schema() to ensure that a module's tables are created exactly as specified without any changes introduced by a module that implements hook_schema_alter().

Parameters:

	$module	The module to which the table belongs.
	$table	The name of the table. If not given, the module's complete schema is returned.

Definition at line 3148 of file common.inc.

References module_invoke(), and module_load_install().

Referenced by drupal_install_schema(), and drupal_uninstall_schema().

Here is the call graph for this function:

drupal_install_schema ( $ module )

Create all tables that a module defines in its hook_schema().

Note: This function does not pass the module's schema through hook_schema_alter(). The module's tables will be created exactly as the module defines them.

Parameters:

$module

The module for which the tables will be created.

Returns:: An array of arrays with the following key/value pairs: success: a boolean indicating whether the query succeeded query: the SQL query(s) executed, passed through check_plain()

Definition at line 3088 of file common.inc.

References $name, _drupal_initialize_schema(), db_create_table(), and drupal_get_schema_unprocessed().

Here is the call graph for this function:

drupal_schema_fields_sql	(	$	table,
		$	prefix = `NULL`
	)

Retrieve a list of fields from a table schema. The list is suitable for use in a SQL query.

Parameters:

	$table	The name of the table from which to retrieve fields.
	An	optional prefix to to all fields.

Returns:: An array of fields.

Definition at line 3192 of file common.inc.

References drupal_get_schema().

Here is the call graph for this function:

drupal_uninstall_schema ( $ module )

Remove all tables that a module defines in its hook_schema().

Note: This function does not pass the module's schema through hook_schema_alter(). The module's tables will be created exactly as the module defines them.

Parameters:

$module

The module for which the tables will be removed.

Returns:: An array of arrays with the following key/value pairs: success: a boolean indicating whether the query succeeded query: the SQL query(s) executed, passed through check_plain()

Definition at line 3113 of file common.inc.

References _drupal_initialize_schema(), db_drop_table(), and drupal_get_schema_unprocessed().

Here is the call graph for this function:

drupal_write_record	(	$	table,
		&$	object,
		$	update = `array()`
	)

Save a record to the database based upon the schema.

Default values are filled in for missing items, and 'serial' (auto increment) types are filled in with IDs.

Parameters:

	$table	The name of the table; this must exist in schema API.
	$object	The object to write. This is a reference, as defaults according to the schema may be filled in on the object, as well as ID on the serial type(s). Both array an object types may be passed.
	$update	If this is an update, specify the primary keys' field names. It is the caller's responsibility to know if a record for this object already exists in the database. If there is only 1 key, you may pass a simple string.

Returns:: Failure to write a record will return FALSE. Otherwise SAVED_NEW or SAVED_UPDATED is returned depending on the operation performed. The $object parameter contains values for any serial fields defined by the $table. For example, $object->nid will be populated after inserting a new node.

Definition at line 3230 of file common.inc.

References $return, db_last_insert_id(), db_query(), db_type_placeholder(), and drupal_get_schema().

Referenced by contact_admin_edit_submit(), and file_save_upload().

Here is the call graph for this function:

Schema API

Functions

Detailed Description

Function Documentation