function db_change_field in Drupal 8

Same name and namespace in other branches

1. 6 includes/database.mysql-common.inc \db_change_field()
2. 6 includes/database.pgsql.inc \db_change_field()
3. 7 includes/database/database.inc \db_change_field()

Changes a field definition.

IMPORTANT NOTE: To maintain database portability, you have to explicitly recreate all indices and primary keys that are using the changed field.

That means that you have to drop all affected keys and indexes with \Drupal::database()->schema()->drop{PrimaryKey,UniqueKey,Index}() before calling \Drupal\Core\Database\Schema::changeField(). To recreate the keys and indices, pass the key definitions as the optional $keys_new argument directly to \Drupal\Core\Database\Schema::changeField().

For example, suppose you have:

$schema['foo'] = array(
  'fields' => array(
    'bar' => array(
      'type' => 'int',
      'not null' => TRUE,
    ),
  ),
  'primary key' => array(
    'bar',
  ),
);

and you want to change foo.bar to be type serial, leaving it as the primary key. The correct sequence is:

$schema = \Drupal::database()
  ->schema();
$schema
  ->dropPrimaryKey('foo');
$schema
  ->changeField('foo', 'bar', 'bar', array(
  'type' => 'serial',
  'not null' => TRUE,
), array(
  'primary key' => array(
    'bar',
  ),
));

The reasons for this are due to the different database engines:

On PostgreSQL, changing a field definition involves adding a new field and dropping an old one which causes any indices, primary keys and sequences (from serial-type fields) that use the changed field to be dropped.

On MySQL, all type 'serial' fields must be part of at least one key or index as soon as they are created. You cannot use \Drupal::database()->schema()->add{PrimaryKey,UniqueKey,Index}() for this purpose because the ALTER TABLE command will fail to add the column without a key or index specification. The solution is to use the optional $keys_new argument to create the key or index at the same time as field.

You could use \Drupal::database()->schema()->add{PrimaryKey,UniqueKey,Index}() in all cases unless you are converting a field to be type serial. You can use the $keys_new argument in all cases.

Parameters

$table: Name of the table.

$field: Name of the field to change.

$field_new: New name for the field (set to the same as $field if you don't want to change the name).

$spec: The field specification for the new field.

array $keys_new: (optional) Keys and indexes specification to be created on the table along with changing the field. The format is the same as a table specification but without the 'fields' element.

See also

https://www.drupal.org/node/2993033

\Drupal\Core\Database\Schema::changeField()

Related topics

1 call to db_change_field()

DatabaseLegacyTest::testDbChangeField in core/tests/Drupal/KernelTests/Core/Database/DatabaseLegacyTest.php

Tests the db_change_field() function is deprecated.

File

core/includes/database.inc, line 1120

Core systems for the database layer.

Code

function db_change_field($table, $field, $field_new, $spec, $keys_new = []) {
  @trigger_error('db_change_field() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call changeField() on it. For example, $injected_database->schema()->changeField($table, $field, $field_new, $spec, $keys_new). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
  return Database::getConnection()
    ->schema()
    ->changeField($table, $field, $field_new, $spec, $keys_new);
}