? sites/default/files
? sites/default/settings.php
Index: includes/database/schema.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/schema.inc,v
retrieving revision 1.11
diff -u -p -r1.11 schema.inc
--- includes/database/schema.inc	24 Feb 2009 16:34:46 -0000	1.11
+++ includes/database/schema.inc	11 Mar 2009 18:15:39 -0000
@@ -493,6 +493,22 @@ abstract class DatabaseSchema {
     }
     return $ret;
   }
+
+  /**
+   * Prepare a table or column comment for database query.
+   * 
+   * @param $comment
+   *   The comment string to prepare.
+   * @param $length
+   *   Optional upper limit on the returned string length.
+   * @return
+   *   The prepared comment.
+   */
+  public function prepareComment($comment, $length = NULL) {
+    // Decode HTML-encoded comments.
+    $comment = decode_entities(strip_tags($comment));
+    return $this->connection->quote($comment);
+  }
 }
 
 /**
Index: includes/database/mysql/schema.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/mysql/schema.inc,v
retrieving revision 1.11
diff -u -p -r1.11 schema.inc
--- includes/database/mysql/schema.inc	26 Jan 2009 14:08:41 -0000	1.11
+++ includes/database/mysql/schema.inc	11 Mar 2009 18:15:39 -0000
@@ -15,6 +15,16 @@
 class DatabaseSchema_mysql extends DatabaseSchema {
 
   /**
+   * Maximum length of a table comment in MySQL.
+   */
+  const COMMENT_MAX_TABLE = 60;
+
+  /**
+   * Maximum length of a column comment in MySQL.
+   */
+  const COMMENT_MAX_COLUMN = 255;
+
+  /**
    * Build a condition to match a table name against a standard information_schema.
    *
    * MySQL uses databases like schemas rather than catalogs so when we build
@@ -50,7 +60,7 @@ class DatabaseSchema_mysql extends Datab
    */
   protected function createTableSql($name, $table) {
     if (empty($table['mysql_suffix'])) {
-      $table['mysql_suffix'] = "/*!40100 DEFAULT CHARACTER SET UTF8 */";
+      $table['mysql_suffix'] = 'DEFAULT CHARACTER SET UTF8';
     }
 
     $sql = "CREATE TABLE {" . $name . "} (\n";
@@ -71,6 +81,11 @@ class DatabaseSchema_mysql extends Datab
 
     $sql .= $table['mysql_suffix'];
 
+    // Add table comment.
+    if (!empty($table['description'])) {
+      $sql .= ' COMMENT ' . $this->prepareComment($table['description'], self::COMMENT_MAX_TABLE);
+    }
+
     return array($sql);
   }
 
@@ -122,6 +137,11 @@ class DatabaseSchema_mysql extends Datab
       $sql .= ' DEFAULT NULL';
     }
 
+    // Add column comment.
+    if (!empty($spec['description'])) {
+      $sql .= ' COMMENT ' . $this->prepareComment($spec['description'], self::COMMENT_MAX_COLUMN);
+    }
+
     return $sql;
   }
 
@@ -325,6 +345,36 @@ class DatabaseSchema_mysql extends Datab
     $ret[] = update_sql($sql);
   }
 
+  public function prepareComment($comment, $length = NULL) {
+    // Decode HTML-encoded comments.
+    $comment = decode_entities(strip_tags($comment));
+
+    // Work around a bug in some versions of PDO, see http://bugs.php.net/bug.php?id=41125
+    $comment = str_replace("'", '’', $comment);
+ 
+    // Truncate comment to maximum comment length.
+    if (isset($length)) {
+      // Add table prefixes before truncating.
+      $comment = truncate_utf8($this->connection->prefixTables($comment), $length, TRUE, TRUE);
+    }
+
+    return $this->connection->quote($comment);
+  }
+
+  /**
+   * Retrieve a table or column comment.
+   */
+  public function getComment($table, $column = NULL) {
+    $condition = $this->buildTableNameCondition($this->connection->prefixTables('{' . $table . '}'));
+    if (isset($column)) {
+      $condition->condition('column_name', $column);
+      $condition->compile($this->connection);
+      return db_query("SELECT column_comment FROM information_schema.columns WHERE " . (string) $condition, $condition->arguments())->fetchField();
+    }
+    $condition->compile($this->connection);
+    return db_query("SELECT table_comment FROM information_schema.tables WHERE " . (string) $condition, $condition->arguments())->fetchField();
+  }
+
 }
 
 /**
Index: includes/database/pgsql/schema.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/pgsql/schema.inc,v
retrieving revision 1.8
diff -u -p -r1.8 schema.inc
--- includes/database/pgsql/schema.inc	24 Feb 2009 16:34:46 -0000	1.8
+++ includes/database/pgsql/schema.inc	11 Mar 2009 18:15:39 -0000
@@ -109,6 +109,18 @@ class DatabaseSchema_pgsql extends Datab
       }
     }
 
+    // Add table comment.
+    if (!empty($table['description'])) {
+      $statements[] = 'COMMENT ON TABLE {' . $name . '} IS ' . $this->prepareComment($table['description']);
+    }
+
+    // Add column comments.
+    foreach ($table['fields'] as $field_name => $field) {
+      if (!empty($field['description'])) {
+        $statements[] = 'COMMENT ON COLUMN {' . $name . '}.' . $field_name . ' IS ' . $this->prepareComment($field['description']);
+      }
+    }
+
     return $statements;
   }
 
@@ -322,6 +334,10 @@ class DatabaseSchema_pgsql extends Datab
     if (isset($new_keys)) {
       $this->_createKeys($ret, $table, $new_keys);
     }
+    // Add column comment.
+    if (!empty($spec['description'])) {
+      $ret[] = update_sql('COMMENT ON COLUMN {' . $table . '}.' . $field . ' IS ' . $this->prepareComment($spec['description']));
+    }
   }
 
   /**
@@ -567,4 +583,15 @@ class DatabaseSchema_pgsql extends Datab
       }
     }
   }
+
+  /**
+   * Retrieve a table or column comment.
+   */
+  public function getComment($table, $column = NULL) {
+    $table = $this->connection->prefixTables('{' . $table . '}');
+    if (isset($column)) {
+      return db_query('SELECT col_description(oid, attnum) FROM pg_class, pg_attribute WHERE attrelid = oid AND relname = ? AND attname = ?', array($table, $column))->fetchField();
+    }
+    return db_query('SELECT obj_description(oid, ?) FROM pg_class WHERE relname = ?', array('pg_class', $table))->fetchField();
+  }
 }
Index: modules/simpletest/tests/schema.test
===================================================================
RCS file: /cvs/drupal/drupal/modules/simpletest/tests/schema.test,v
retrieving revision 1.3
diff -u -p -r1.3 schema.test
--- modules/simpletest/tests/schema.test	16 Nov 2008 19:41:14 -0000	1.3
+++ modules/simpletest/tests/schema.test	11 Mar 2009 18:15:39 -0000
@@ -24,6 +24,7 @@ class SchemaTestCase extends DrupalWebTe
   function testSchema() {
     // Try creating a table.
     $table_specification = array(
+      'description' => 'Schema table description.',
       'fields' => array(
         'id'  => array(
           'type' => 'int',
@@ -32,6 +33,7 @@ class SchemaTestCase extends DrupalWebTe
         'test_field'  => array(
           'type' => 'int',
           'not null' => TRUE,
+          'description' => 'Schema column description.',
         ),
       ),
     );
@@ -41,6 +43,12 @@ class SchemaTestCase extends DrupalWebTe
     // Assert that the table exists.
     $this->assertTrue(db_table_exists('test_table'), t('The table exists.'));
 
+    // Assert that the table comment has been set.
+    $this->checkSchemaComment($table_specification['description'], 'test_table');
+
+    // Assert that the column comment has been set.
+    $this->checkSchemaComment($table_specification['fields']['test_field']['description'], 'test_table', 'test_field');
+
     // An insert without a value for the column 'test_table' should fail.
     $this->assertFalse($this->tryInsert(), t('Insert without a default failed.'));
 
@@ -72,10 +80,16 @@ class SchemaTestCase extends DrupalWebTe
     // Recreate the table.
     db_create_table($ret, 'test_table', $table_specification);
     db_field_set_default($ret, 'test_table', 'test_field', 0);
-    db_add_field($ret, 'test_table', 'test_serial', array('type' => 'int', 'not null' => TRUE, 'default' => 0));
+    db_add_field($ret, 'test_table', 'test_serial', array('type' => 'int', 'not null' => TRUE, 'default' => 0, 'description' => 'Added column description.'));
+
+    // Assert that the column comment has been set.
+    $this->checkSchemaComment('Added column description.', 'test_table', 'test_serial');
 
     // Change the new field to a serial column.
-    db_change_field($ret, 'test_table', 'test_serial', 'test_serial', array('type' => 'serial', 'not null' => TRUE), array('primary key' => array('test_serial')));
+    db_change_field($ret, 'test_table', 'test_serial', 'test_serial', array('type' => 'serial', 'not null' => TRUE, 'description' => 'Changed column description.'), array('primary key' => array('test_serial')));
+
+    // Assert that the column comment has been set.
+    $this->checkSchemaComment('Changed column description.', 'test_table', 'test_serial');
 
     $this->assertTrue($this->tryInsert(), t('Insert with a serial succeeded.'));
     $max1 = db_query('SELECT MAX(test_serial) FROM {test_table}')->fetchField();
@@ -96,4 +110,21 @@ class SchemaTestCase extends DrupalWebTe
       return FALSE;
     }
   }
+
+  /**
+   * Checks that a table or column comment matches a given description.
+   *
+   * @param $description
+   *   The asserted description.
+   * @param $table
+   *   The table to test.
+   * @param $column
+   *   Optional column to test.
+   */
+  function checkSchemaComment($description, $table, $column = NULL) {
+    if (method_exists(Database::getConnection()->schema(), 'getComment')) {
+      $comment = Database::getConnection()->schema()->getComment($table, $column);
+      $this->assertEqual($comment, $description, t('The comment matches the schema description.'));
+    }
+  }
 }