Update versions of API functions

Functions that are similar to normal API functions, but do not invoke hooks.

These simplified versions of core API functions are provided for use by update functions (hook_update_N() implementations).

During database updates the schema of any module could be out of date. For this reason, caution is needed when using any API function within an update function - particularly CRUD functions, functions that depend on the schema (for example by using drupal_write_record()), and any functions that invoke hooks.

Instead, a simplified utility function should be used. If a utility version of the API function you require does not already exist, then you should create a new function. The new utility function should be named _update_N_mymodule_my_function(). N is the schema version the function acts on (the schema version is the number N from the hook_update_N() implementation where this schema was introduced, or a number following the same numbering scheme), and mymodule_my_function is the name of the original API function including the module's name.

Examples:

• _update_7000_mymodule_save(): This function performs a save operation without invoking any hooks using the 7.x schema.
• _update_8000_mymodule_save(): This function performs the same save operation using the 8.x schema.

The utility function should not invoke any hooks, and should perform database operations using functions from the Database abstraction layer, like db_insert(), db_update(), db_delete(), db_query(), and so on.

If a change to the schema necessitates a change to the utility function, a new function should be created with a name based on the version of the schema it acts on. See _update_8000_bar_get_types() and _update_8001_bar_get_types() in the code examples that follow.

For example, foo.install could contain:

function foo_update_dependencies() {

  // foo_update_8010() needs to run after bar_update_8000().
  $dependencies['foo'][8010] = array(
    'bar' => 8000,
  );

  // foo_update_8036() needs to run after bar_update_8001().
  $dependencies['foo'][8036] = array(
    'bar' => 8001,
  );
  return $dependencies;
}
function foo_update_8000() {

  // No updates have been run on the {bar_types} table yet, so this needs
  // to work with the 7.x schema.
  foreach (_update_7000_bar_get_types() as $type) {

    // Rename a variable.
  }
}
function foo_update_8010() {

  // Since foo_update_8010() is going to run after bar_update_8000(), it
  // needs to operate on the new schema, not the old one.
  foreach (_update_8000_bar_get_types() as $type) {

    // Rename a different variable.
  }
}
function foo_update_8036() {

  // This update will run after bar_update_8001().
  foreach (_update_8001_bar_get_types() as $type) {
  }
}

And bar.install could contain:

function bar_update_8000() {
  // Type and bundle are confusing, so we renamed the table.
  db_rename_table('bar_types', 'bar_bundles');
}

function bar_update_8001() {
  // Database table names should be singular when possible.
  db_rename_table('bar_bundles', 'bar_bundle');
}

function _update_7000_bar_get_types() {
  db_query('SELECT * FROM {bar_types}')->fetchAll();
}

function _update_8000_bar_get_types() {
  db_query('SELECT * FROM {bar_bundles'})->fetchAll();
}

function _update_8001_bar_get_types() {
  db_query('SELECT * FROM {bar_bundle}')->fetchAll();
}

See also

hook_update_N()

hook_update_dependencies()

File

drupal/core/modules/system/system.api.php, line 3815

Hooks provided by Drupal core and the System module.

Functions

Name	Location	Description
_update_7000_field_create_field	drupal/core/modules/field/field.install	Creates a field by writing directly to the database.
_update_7000_field_create_instance	drupal/core/modules/field/field.install	Writes a field instance directly to the database.
_update_7000_field_delete_field	drupal/core/modules/field/field.install	Deletes a field stored in SQL storage directly from the database.
_update_7000_field_delete_instance	drupal/core/modules/field/field.install	Deletes an instance and all its data of a field stored in SQL Storage.
_update_7000_field_read_fields	drupal/core/modules/field/field.install	Fetches all of the field definitions from the database.
_update_7000_node_get_types	drupal/core/modules/node/node.install	Fetches node types directly from the database.
_update_8000_field_sql_storage_write	drupal/core/modules/field/modules/field_sql_storage/field_sql_storage.install	Writes field data directly to SQL storage.