How to use CiviX upgrade hooks?

Question

I'm developing an upgrade to an extension and when this version is installed it's going to need to update the database.

The module extension has been made with civix and I notice there's a CRM_XXX_Upgrader_Base class that looks useful but I can't figure out where I'd put the code I need to run.

Are there any good examples of extension upgrade hooks that I could learn from?

I've looked at a couple of popular extensions, but they don't seem to have used/needed them, so I'm stabbing in the dark a bit.

Answer 1

Here is an example of one I have used:

 public function upgrade_1002() {
    $this->ctx->log->info('Applying update 1002 (add country)id to civicrm_project table and renaming manager_id in civicrm_programme table)');
    if (CRM_Core_DAO::checkTableExists('civicrm_project')) {
      if (!CRM_Core_DAO::checkFieldExists('civicrm_project', 'country_id')) {
        CRM_Core_DAO::executeQuery('ALTER TABLE civicrm_project ADD COLUMN country_id INT(11) DEFAULT NULL');
      }
      if (CRM_Core_DAO::checkFieldExists('civicrm_programme' , 'contact_id_manager')) {
        CRM_Core_DAO::executeQuery('ALTER TABLE civicrm_programme CHANGE contact_id_manager manager_id INT(11)');
      }
    }
    return TRUE;
  }

Does this explain it a little? And obviously you also have to make sure your install query is fixed as this will be used when installing, not the upgrades.

And another one with the sql in a separate file:

  /**
   * Upgrade 1003 - add table civicrm_case_project
   */
  public function upgrade_1003() {
    $this->ctx->log->info('Applying update 1003 (create civicrm_case_project table');
    if (!CRM_Core_DAO::checkTableExists('civicrm_case_project')) {
      $this->executeSqlFile('sql/createCaseProject.sql');
    }
    return TRUE;
  }