- Patch #69659 by derek: improved documentation of db abstraction layer.

update.php

@@ -28,9 +28,11 @@ function update_sql($sql) {
  * Save result of SQL commands in $ret array.
  *
  * Note: when you add a column with NOT NULL and you are not sure if there are
- * already rows in the table, you MUST also add DEFAULT. Otherwise PostgreSQL won't
- * work when the table is not empty. If NOT NULL and DEFAULT are set the
- * PostgreSQL version will set values of the added column in old rows to the
+ * already rows in the table, you MUST also add DEFAULT. Otherwise PostgreSQL
+ * won't work when the table is not empty, and db_add_column() will fail.
+ * To have an empty string as the default, you must use: 'default' => "''"
+ * in the $attributes array. If NOT NULL and DEFAULT are set the PostgreSQL
+ * version will set values of the added column in old rows to the
  * DEFAULT value.
  *
  * @param $ret
@@ -44,7 +46,7 @@ function update_sql($sql) {
  * @param $attributes
  *   Additional optional attributes. Recognized attributes:
  *     not null => TRUE|FALSE
- *     default  => NULL|FALSE|value (with or without '', it won't be added)
+ *     default  => NULL|FALSE|value (the value must be enclosed in '' marks)
  * @return
  *   nothing, but modifies $ret parameter.
  */