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_6000_mymodule_save(): This function performs a save operation without invoking any hooks using the 6.x schema.
• _update_7000_mymodule_save(): This function performs the same save operation using the 7.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_7000_bar_get_types() and _update_7001_bar_get_types() in the code examples that follow.

For example, foo.install could contain:

function foo_update_dependencies() {
  // foo_update_7010() needs to run after bar_update_7000().
  $dependencies['foo'][7010] = array(
    'bar' => 7000,
  );

  // foo_update_7036() needs to run after bar_update_7001().
  $dependencies['foo'][7036] = array(
    'bar' => 7001,
  );

  return $dependencies;
}

function foo_update_7000() {
  // No updates have been run on the {bar_types} table yet, so this needs
  // to work with the 6.x schema.
  foreach (_update_6000_bar_get_types() as $type) {
    // Rename a variable.
  }
}

function foo_update_7010() {
   // Since foo_update_7010() is going to run after bar_update_7000(), it
   // needs to operate on the new schema, not the old one.
   foreach (_update_7000_bar_get_types() as $type) {
     // Rename a different variable.
   }
}

function foo_update_7036() {
  // This update will run after bar_update_7001().
  foreach (_update_7001_bar_get_types() as $type) {
  }
}

And bar.install could contain:

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

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

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

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

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

See also

hook_update_N()

hook_update_dependencies()

File

drupal-7.x/modules/system/system.api.php, line 4790

Hooks provided by Drupal core and the System module.

Functions

Name	Location	Description
_update_7000_field_create_field	drupal-7.x/modules/field/field.install	Utility function: create a field by writing directly to the database.
_update_7000_field_create_instance	drupal-7.x/modules/field/field.install	Utility function: write a field instance directly to the database.
_update_7000_field_delete_field	drupal-7.x/modules/field/field.install	Utility function: delete a field stored in SQL storage directly from the database.
_update_7000_field_delete_instance	drupal-7.x/modules/field/field.install	Utility function: delete an instance and all its data of a field stored in SQL Storage.
_update_7000_field_read_fields	drupal-7.x/modules/field/field.install	Utility function: fetch all the field definitions from the database.
_update_7000_field_sql_storage_write	drupal-7.x/modules/field/modules/field_sql_storage/field_sql_storage.install	Utility function: write field data directly to SQL storage.
_update_7000_node_get_types	drupal-7.x/modules/node/node.install	Utility function: fetch the node types directly from the database.
_update_7000_user_role_grant_permissions	drupal-7.x/modules/user/user.install	Utility function: grant a set of permissions to a role during update.
_update_7002_taxonomy_get_vocabularies	drupal-7.x/modules/taxonomy/taxonomy.install	Utility function: get the list of vocabularies directly from the database.