Index: modules/system/system.api.php =================================================================== RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v retrieving revision 1.218 diff -u -r1.218 system.api.php --- modules/system/system.api.php 1 Dec 2010 00:23:36 -0000 1.218 +++ modules/system/system.api.php 7 Dec 2010 17:17:26 -0000 @@ -2804,23 +2804,82 @@ /** * Define the current version of the database schema. * - * 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 must live in your module's .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. - * - * See the Schema API Handbook at http://drupal.org/node/146843 for - * details on schema definition structures. + * A Drupal schema definition is an array structure representing one or more + * tables and their related keys and indexes. A schema is defined in an + * implementation of hook_schema(), which is usually put into the + * modulename.install file. For more information on the structure of the + * schema definition, see the return value section below and the sample + * function body, as well as the + * @link http://drupal.org/node/146843 Schema API handbook @endlink + * + * As of Drupal 7, implementing hook_schema() is all that you need to do to + * have your module's database tables created when your module is first + * installed, and dropped when the module is uninstalled, on all supported + * database engines. * * @return * A schema definition structure array. For each element of the * array, the key is a table name and the value is a table structure - * definition. + * definition array. Each table structure definition has the following + * elements: + * - 'description': A string in non-markup plain text 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. Each specification is an array + * with the following elements: + * - 'description': A string in non-markup plain text 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_revision}.vid + * value for this nid." + * - 'type': The generic datatype: 'char', 'varchar', 'text', 'blob', 'int', + * 'float', 'numeric', 'serial', 'date', 'datetime' or 'time'. Most types + * map to the database-engine-specific datatypes. Use 'serial' for auto + * incrementing fields. This will expand to 'INT auto_increment' on MySQL. + * - 'serialize': A boolean indicating whether the field will be stored as + * a serialized string. + * - '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 DatabaseSchema::getFieldTypeMap() for + * possible combinations. + * - 'not null': If true, no NULL values will be allowed in this field. + * 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 'char', '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 that form + * the primary key. 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. + * - 'unique keys': An associative array of unique keys ('keyname' => + * specification). Each specification is an array of one or more + * key column specifiers (see primary key) that form a unique key on the + * table. + * - 'foreign keys': An associative array of relations ('my_relation' => + * specification). Each specification is an array containing the name of + * the referenced table ('table'), and an array of column mappings + * ('columns'). Column mappings are defined by key pairs ('source_column' => + * 'referenced_column'). + * - 'indexes': An associative array of indexes ('indexname' => + * specification). Each specification is an array of one or more key column + * specifiers (see primary key) that form an index on the table. * * @ingroup schemaapi */ Index: includes/database/schema.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/database/schema.inc,v retrieving revision 1.42 diff -u -r1.42 schema.inc --- includes/database/schema.inc 29 Nov 2010 04:45:10 -0000 1.42 +++ includes/database/schema.inc 7 Dec 2010 17:17:26 -0000 @@ -12,142 +12,17 @@ * @defgroup schemaapi Schema API * @{ * - * 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. + * A Drupal schema definition is an array structure representing one or more + * tables and their related keys and indexes. A schema is defined in an + * implementation of hook_schema(), which is usually put into the + * modulename.install file. For more information on the structure of the + * schema definition, see the hook_schema() documentation, and the + * @link http://drupal.org/node/146843 Schema API handbook @endlink * - * 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 in non-markup plain text 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 in non-markup plain text 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_revision}.vid value for this nid." - * - 'type': The generic datatype: 'char', 'varchar', 'text', 'blob', 'int', - * 'float', 'numeric', 'serial', 'date', 'datetime' or 'time'. Most types - * 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. - * - 'serialize': A boolean indicating whether the field will be stored as - * a serialized string. - * - '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 - * DatabaseSchema::getFieldTypeMap() 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 'char', '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 keys': 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. - * - 'foreign keys': An associative array of relations ('my_relation' => - * specification). Each specification is an array containing the name of - * the referenced table ('table'), and an array of column mappings - * ('columns'). Column mappings are defined by key pairs ('source_column' => - * 'referenced_column'). - * - 'indexes': An associative array of indexes ('indexname' => - * 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': - * - * @code - * $schema['node'] = array( - * 'description' => 'The base table for nodes.', - * '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' => ''), - * 'language' => array('type' => 'varchar','length' => 12,'not null' => TRUE,'default' => ''), - * 'title' => array('type' => 'varchar','length' => 255,'not null' => TRUE, 'default' => ''), - * 'uid' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'status' => array('type' => 'int', 'not null' => TRUE, 'default' => 1), - * 'created' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'changed' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'comment' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'promote' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'moderate' => array('type' => 'int', 'not null' => TRUE,'default' => 0), - * 'sticky' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * 'tnid' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0), - * 'translate' => array('type' => 'int', 'not null' => TRUE, 'default' => 0), - * ), - * 'indexes' => array( - * 'node_changed' => array('changed'), - * 'node_created' => array('created'), - * 'node_moderate' => array('moderate'), - * 'node_frontpage' => array('promote', 'status', 'sticky', 'created'), - * 'node_status_type' => array('status', 'type', 'nid'), - * 'node_title_type' => array('title', array('type', 4)), - * 'node_type' => array(array('type', 4)), - * 'uid' => array('uid'), - * 'tnid' => array('tnid'), - * 'translate' => array('translate'), - * ), - * 'unique keys' => array( - * 'vid' => array('vid'), - * ), - * 'foreign keys' => array( - * 'node_revision' => array( - * 'table' => 'node_revision', - * 'columns' => array('vid' => 'vid'), - * ), - * 'node_author' => array( - * 'table' => 'users', - * 'columns' => array('uid' => 'uid'), - * ), - * ), - * 'primary key' => array('nid'), - * ); - * @endcode - * - * @see drupal_install_schema() + * As of Drupal 7, implementing hook_schema() is all that you need to do to + * have your module's database tables created when your module is first + * installed, and dropped when the module is uninstalled, on all supported + * database engines. */ abstract class DatabaseSchema implements QueryPlaceholderInterface {