Upgrading ImpulseCore

Core upgrades are a drop-in archive replacement. The activate hook runs idempotent schema migrations in place — no manual SQL, no downtime beyond a normal addon reload.

Last updated 20 days ago

Upgrading ImpulseCore

ImpulseCore is designed to be upgraded in place. Drop the new archive over the old files, re-trigger the activate hook, and you're done. There is no separate migration runner and no manual SQL.

When to upgrade Core

Upgrade Core whenever:

  • A module you're about to install pins a newer `core_min_version` in its manifest. Activating that module will hard-fail until Core is at least that version.
  • A module release note says "requires ImpulseCore X.Y.Z or later." Upgrade Core first, then the module.
  • A Core release notes a bug fix or security item you care about.

You do not need to upgrade modules in lockstep with Core. Modules pin a minimum, not an exact version, so newer Core works with older modules.

The upgrade procedure

  1. Take a database backup. Schema changes are idempotent and reversible in practice, but a backup is cheap insurance.
  2. Extract the new release archive over the existing `modules/addons/impulsecore/` directory. The release ships the same layout you installed originally — `impulsecore.php`, `impulse_module.json`, `lib/`, `templates/`, `schema/`.
  3. Re-trigger the activate hook. In WHMCS Admin go to System Settings → Addon Modules, find ImpulseCore, click Deactivate, then Activate. WHMCS runs the activate hook again.
cd /path/to/whmcs unzip -o /tmp/impulsecore-X.Y.Z.zip

The activate hook walks schema/ and applies any new migrations that haven't been recorded yet. Existing data is preserved. Existing `mod_impulsecore_*` rows are not touched except where a migration explicitly alters them.

What the activate hook does on upgrade

The hook is fully idempotent — running it twice is identical to running it once. On an upgrade run it:

  • Applies any new SQL migrations in schema/ and records them so they don't re-run.
  • Updates Core's row in mod_impulsecore_modules with the new version string.
  • Re-seeds default settings only if their rows are missing.
  • Re-registers Core's own cron tasks (audit_purge, license_refresh, the Security & Maintenance pipeline tasks). Existing rows are updated, not duplicated.

No customer-visible downtime. The cron runner picks back up on its next 5-minute tick. Admin tabs reload immediately.

Verify the upgrade

Open Addons → ImpulseCore → Overview. The version string in the header should match the archive you dropped in. The Audit log will carry an impulsecore.activated event with the new version in context.

If a module had been refusing to activate because of a version mismatch, retry it now — the core_min_version check will pass.

Rollback

Core's activate hook is non-destructive. Schema migrations add columns and tables; they do not drop or rewrite existing data. To roll back to an older Core release:

  1. Extract the older release archive over modules/addons/impulsecore/.
  2. Deactivate then re-activate the addon.

The older code will skip migrations it doesn't know about; the newer columns remain in the database harmlessly. If you need to roll back across a breaking schema change, restore the database from the backup you took in step 1 of the upgrade procedure.

Related