Drupal 6.x

A field's default value, if it has one, must be of a type that is compatible with the field's database type. Database engines typically have type-conversion rules so that, for example, if your provide the string '0' for an integer column it is converted into the integer 0, but it is still better to specify the correct data type in the schema definition.

The following table defines the correct types and shows correct and incorrect examples.

[Note: the following only applies when MySQL (5) is not running in Strict Mode. Every developer is encouraged to enable Strict Mode to produce standard conformant SQL and avoid sloppy coding.]

MySQL does not enforce the "standard" SQL rules for NOT NULL and default values on columns. It gives all columns an "implicit default value" even if no default value is specified for the column, making it possible to insert rows without providing a value for a NOT NULL, no default column. For example, consider this table:

$schema['T'] = array(
  'fields' => array(
    'i1' => array('type' => 'int'),
    'i2' => array('type' => 'int', 'not null' => TRUE),
  ));

In "standard" SQL, the statement INSERT INTO T (i1) VALUES (NULL) is illegal because no value is provided for the NOT NULL column i2. In MySQL, it is legal because i2 gets the "implicit default value" for integers of 0. This behavior is not portable to other database systems and code that relies on it is flawed and considered sloppy. Unfortunately, because so many Drupal and PHP programmers learned SQL using MySQL, INSERT queries that depend on this behavior often occur.

Suppose you have an existing table T and want to add a new type 'text' column named C that will be NOT NULL and have no default value. If table T already contains rows (or, on some DBMS's, even if the table is empty), you cannot add a NOT NULL column without providing a value for every row. There are two potential solutions:

1. Add the column with a default value and then, after it is created, remove the default value property. This does not work for column types that do not allow default values at all (such as 'text' and 'blob' on MySQL).
2. Add the column without NOT NULL so all rows get a NULL value, UPDATE the column to set a value for all rows, then add the NOT NULL property to the column. This works for all column types.

The Schema API db_add_field() function supports option 2. The function accepts a field specification array to add to a table. The specification may contain the parameter 'initial' and the newly created field will be set to the value of the key in all rows. db_add_field() creates the column as NULLable, performs the UPDATE statement and then, if appropriate, sets it to NOT NULL. The 'initial' parameter works for all columns but is the only way to create NOT NULL columns with no default value in existing tables.

SQL databases require that all columns involved in a table's primary key be declared as NOT NULL. If you declare a primary key column to allow NULL values, MySQL and PostgresQL (probably among others) silently convert the columns to NOT NULL, but you should not rely on this behavior.

For example, this table specification is incorrect: