#164983 by multiple contributors: document the core database schemas

1 files changed, 290 insertions, 66 deletions

diff --git a/modules/node/node.install b/modules/node/node.install
index 5c1489d89..9779c2ef1 100644
--- a/modules/node/node.install
+++ b/modules/node/node.install
@@ -6,23 +6,89 @@
  */
 function node_schema() {
   $schema['node'] = array(
+    'description' => t('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),
-    ),
+      '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' => ''),
+      'language' => array(
+        'description' => t('The {languages}.language of this node.'),
+        'type' => 'varchar',
+        'length' => 12,
+        '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' => ''),
+      'uid' => array(
+        'description' => t('The {users}.uid that owns this node; initially, this is the user that created it.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'status' => array(
+        'description' => t('Boolean indicating whether the node is published (visible to non-administrators).'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 1),
+      'created' => array(
+        'description' => t('The Unix timestamp when the node was created.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'changed' => array(
+        'description' => t('The Unix timestamp when the node was most recently saved.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'comment' => array(
+        'description' => t('Whether comments are allowed on this node: 0 = no, 1 = read only, 2 = read/write.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'promote' => array(
+        'description' => t('Boolean indicating whether the node should displayed on the front page.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'moderate' => array(
+        'description' => t('Previously, a boolean indicating whether the node was "in moderation"; mostly no longer used.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'sticky' => array(
+        'description' => t('Boolean indicating whether the node should be displayed at the top of lists in which it appears.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'tnid' => array(
+        'description' => t('The translation set id for this node, which equals the node id of the source post in each set.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0),
+      'translate' => array(
+        'description' => t('A boolean indicating whether this translation page needs to be updated.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      ),
     'indexes' => array(
       'node_changed'        => array('changed'),
       'node_created'        => array('created'),
@@ -35,78 +101,236 @@ function node_schema() {
       'uid'                 => array('uid'),
       'tnid'                => array('tnid'),
       'translate'           => array('translate'),
-    ),
+      ),
     'unique keys' => array(
       'nid_vid' => array('nid', 'vid'),
       'vid'     => array('vid')
-    ),
+      ),
     'primary key' => array('nid'),
-  );
+    );
 
   $schema['node_access'] = array(
+    'description' => t('Identifies which realm/grant pairs a user must possess in order to view, update, or delete specific nodes.'),
     'fields' => array(
-      'nid'          => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'gid'          => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'realm'        => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => ''),
-      'grant_view'   => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0, 'size' => 'tiny'),
-      'grant_update' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0, 'size' => 'tiny'),
-      'grant_delete' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0, 'size' => 'tiny')
-    ),
-    'primary key' => array(
-      'nid',
-      'gid',
-      'realm'
-    ),
-  );
+      'nid' => array(
+        'description' => t('The {node}.nid this record affects.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0),
+      'gid' => array(
+        'description' => t("The grant ID a user must possess in the specified realm to gain this row's privileges on the node."),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0),
+      'realm' => array(
+        'description' => t('The realm in which the user must possess the grant ID. Each node access node can define one or more realms.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => ''),
+      'grant_view' => array(
+        'description' => t('Boolean indicating whether a user with the realm/grant pair can view this node.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny'),
+      'grant_update' => array(
+        'description' => t('Boolean indicating whether a user with the realm/grant pair can edit this node.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny'),
+      'grant_delete' => array(
+        'description' => t('Boolean indicating whether a user with the realm/grant pair can delete this node.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny')
+      ),
+    'primary key' => array('nid', 'gid', 'realm'),
+    );
 
   $schema['node_counter'] = array(
+    'description' => t('Access statistics for {node}s.'),
     'fields' => array(
-      'nid'        => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
-      'totalcount' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0, 'size' => 'big'),
-      'daycount'   => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0, 'size' => 'medium'),
-      'timestamp'  => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0)
-    ),
+      'nid' => array(
+        'description' => t('The {node}.nid for these statistics.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'totalcount' => array(
+        'description' => t('The total number of times the {node} has been viewed.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'big'),
+      'daycount' => array(
+        'description' => t('The total number of times the {node} has been viewed today.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'medium'),
+      'timestamp' => array(
+        'description' => t('The most recent time the {node} has been viewed.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0)
+      ),
     'primary key' => array('nid'),
-  );
+    );
 
   $schema['node_revisions'] = array(
+    'description' => t('Stores information about each saved version of a {node}.'),
     'fields' => array(
-      'nid'       => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'vid'       => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE),
-      'uid'       => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
-      'title'     => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => ''),
-      'body'      => array('type' => 'text', 'not null' => TRUE, 'size' => 'big'),
-      'teaser'    => array('type' => 'text', 'not null' => TRUE, 'size' => 'big'),
-      'log'       => array('type' => 'text', 'not null' => TRUE, 'size' => 'big'),
-      'timestamp' => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
-      'format'    => array('type' => 'int', 'not null' => TRUE, 'default' => 0)
-    ),
+      'nid' => array(
+        'description' => t('The {node} this version belongs to.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0),
+      'vid' => array(
+        'description' => t('The primary identifier for this version.'),
+        'type' => 'serial',
+        'unsigned' => TRUE,
+        'not null' => TRUE),
+      'uid' => array(
+        'description' => t('The {users}.uid that created this version.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'title' => array(
+        'description' => t('The title of this version.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => ''),
+      'body' => array(
+        'description' => t('The body of this version.'),
+        'type' => 'text',
+        'not null' => TRUE,
+        'size' => 'big'),
+      'teaser' => array(
+        'description' => t('The teaser of this version.'),
+        'type' => 'text',
+        'not null' => TRUE,
+        'size' => 'big'),
+      'log' => array(
+        'description' => t('The log entry explaining the changes in this version.'),
+        'type' => 'text',
+        'not null' => TRUE,
+        'size' => 'big'),
+      'timestamp' => array(
+        'description' => t('A Unix timestamp indicating when this version was created.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0),
+      'format' => array(
+        'description' => t("The input format used by this version's body."),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0)
+      ),
     'indexes' => array(
       'nid' => array('nid'),
       'uid' => array('uid')
-    ),
+      ),
     'primary key' => array('vid'),
-  );
+    );
 
   $schema['node_type'] = array(
+    'description' => t('Stores information about all defined {node} types.'),
     'fields' => array(
-      'type'           => array('type' => 'varchar', 'length' => 32, 'not null' => TRUE),
-      'name'           => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => ''),
-      'module'         => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE),
-      'description'    => array('type' => 'text', 'not null' => TRUE, 'size' => 'medium'),
-      'help'           => array('type' => 'text', 'not null' => TRUE, 'size' => 'medium'),
-      'has_title'      => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'size' => 'tiny'),
-      'title_label'    => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => ''),
-      'has_body'       => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'size' => 'tiny'),
-      'body_label'     => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => ''),
-      'min_word_count' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'size' => 'small'),
-      'custom'         => array('type' => 'int', 'not null' => TRUE, 'default' => 0, 'size' => 'tiny'),
-      'modified'       => array('type' => 'int', 'not null' => TRUE, 'default' => 0, 'size' => 'tiny'),
-      'locked'         => array('type' => 'int', 'not null' => TRUE, 'default' => 0, 'size' => 'tiny'),
-      'orig_type'      => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => '')
-    ),
+      'type' => array(
+        'description' => t('The machine-readable name of this type.'),
+        'type' => 'varchar',
+        'length' => 32,
+        'not null' => TRUE),
+      'name' => array(
+        'description' => t('The human-readable name of this type.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => ''),
+      'module' => array(
+        'description' => t('The module that implements this type.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE),
+      'description'    => array(
+        'description' => t('A brief description of this type.'),
+        'type' => 'text',
+        'not null' => TRUE,
+        'size' => 'medium'),
+      'help' => array(
+        'description' => t('Help information shown to the user when creating a {node} of this type.'),
+        'type' => 'text',
+        'not null' => TRUE,
+        'size' => 'medium'),
+      'has_title' => array(
+        'description' => t('Boolean indicating whether this type uses the {node}.title field.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'size' => 'tiny'),
+      'title_label' => array(
+        'description' => t('The label displayed for the title field on the edit form.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => ''),
+      'has_body' => array(
+        'description' => t('Boolean indicating whether this type uses the {node}.body field.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'size' => 'tiny'),
+      'body_label' => array(
+        'description' => t('The label displayed for the body field on the edit form.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => ''),
+      'min_word_count' => array(
+        'description' => t('The minimum number of words the body must contain.'),
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'size' => 'small'),
+      'custom' => array(
+        'description' => t('A boolean indicating whether this type is defined by a module (FALSE) or by a user via a module like the Content Construction Kit (TRUE).'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny'),
+      'modified' => array(
+        'description' => t('A boolean indicating whether this type has been modified by an administrator; currently not used in any way.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny'),
+      'locked' => array(
+        'description' => t('A boolean indicating whether the administrator can change the machine name of this type.'),
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'size' => 'tiny'),
+      'orig_type' => array(
+        'description' => t('The original machine-readable name of this node type. This may be different from the current type name if the locked field is 0.'),
+        'type' => 'varchar',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => '')
+      ),
     'primary key' => array('type'),
-  );
+    );
 
   return $schema;
 }