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) |
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:
Not all sizes are available for all data types. See db_type_map() for possible combinations.
All parameters apart from 'type' are optional except that type 'numeric' columns must specify 'precision' and 'scale'.
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)), ), );
_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().
$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().
_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().
_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().
_db_process_field | ( | $ | field | ) |
Set database-engine specific properties for a field.
$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().
_drupal_initialize_schema | ( | $ | module, | |
&$ | schema | |||
) |
Fill in required default values for table definitions returned by hook_schema().
$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.
$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. |
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().
db_add_index | ( | &$ | ret, | |
$ | table, | |||
$ | name, | |||
$ | fields | |||
) |
Add an index.
$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().
db_add_primary_key | ( | &$ | ret, | |
$ | table, | |||
$ | fields | |||
) |
Add a primary key.
$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().
db_add_unique_key | ( | &$ | ret, | |
$ | table, | |||
$ | name, | |||
$ | fields | |||
) |
Add a unique key.
$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().
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') );
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.
$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().
db_create_table | ( | &$ | ret, | |
$ | name, | |||
$ | table | |||
) |
Create a new table from a Drupal table definition.
$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().
db_create_table_sql | ( | $ | name, | |
$ | table | |||
) |
Generate SQL to create a new table from a Drupal schema definition.
$name | The name of the table to create. | |
$table | A Schema API table definition array. |
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().
db_drop_field | ( | &$ | ret, | |
$ | table, | |||
$ | field | |||
) |
Drop a field.
$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().
db_drop_index | ( | &$ | ret, | |
$ | table, | |||
$ | name | |||
) |
Drop an index.
$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().
db_drop_primary_key | ( | &$ | ret, | |
$ | table | |||
) |
Drop the primary key.
$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().
db_drop_table | ( | &$ | ret, | |
$ | table | |||
) |
Drop a table.
$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().
db_drop_unique_key | ( | &$ | ret, | |
$ | table, | |||
$ | name | |||
) |
Drop a unique key.
$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().
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.
$fields | An array of key/index column specifiers. |
Definition at line 519 of file database.inc.
db_field_set_default | ( | &$ | ret, | |
$ | table, | |||
$ | field, | |||
$ | default | |||
) |
Set the default value for a field.
$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().
db_field_set_no_default | ( | &$ | ret, | |
$ | table, | |||
$ | field | |||
) |
Set a field to have no default value.
$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().
db_last_insert_id | ( | $ | table, | |
$ | field | |||
) |
Returns the last insert id.
$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().
db_rename_table | ( | &$ | ret, | |
$ | table, | |||
$ | new_name | |||
) |
Rename a table.
$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().
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.
$type | The Schema API type of a field. |
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().
$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().
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().
$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().
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.
$module | The module for which the tables will be created. |
Definition at line 3088 of file common.inc.
References $name, _drupal_initialize_schema(), db_create_table(), and drupal_get_schema_unprocessed().
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.
$table | The name of the table from which to retrieve fields. | |
An | optional prefix to to all fields. |
Definition at line 3192 of file common.inc.
References drupal_get_schema().
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.
$module | The module for which the tables will be removed. |
Definition at line 3113 of file common.inc.
References _drupal_initialize_schema(), db_drop_table(), and drupal_get_schema_unprocessed().
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.
$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. |
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().