Upgrading Burst Statistics

This document covers the upgrade process for Burst Statistics, including automatic database migrations, available hooks, and breaking changes developers should be aware of.

Overview

When Burst Statistics detects a version change (by comparing burst-current-version in the options table against BURST_VERSION), it automatically:

1. Fires the burst_upgrade_before action.
2. Runs any version-specific PHP upgrade routines (e.g. scheduling DB migrations).
3. Re-initialises database tables via burst_table_init.
4. Regenerates the frontend JS file.
5. Schedules a burst_upgrade_iteration cron event (60 seconds out) to begin background DB migrations.
6. Fires the burst_upgrade_after action.
7. Saves the new version to burst-current-version.

Database migrations run in the background via WordPress cron (burst_upgrade_iteration, repeating every minute) and are also nudged forward whenever an admin visits the Burst dashboard (?page=burst). Progress is shown as a dismissible notice in the Burst admin UI.

caution

Upgrades only run when an admin-level user is logged in (or when WP-Cron fires with an active admin session context). On sites where WP-Cron is disabled or unreliable, migrations will still be triggered every time an administrator visits the Burst dashboard page.

---

Upgrade Progress

While a migration is in progress, a notice is shown in the Burst dashboard:

"An upgrade is running in the background, and is currently at X%. For large databases this process may take a while. Your data will be tracked as usual."

Progress is stored per-migration as WordPress transients (burst_progress_<upgrade_name>) and is visible without page refresh via the tasks/warnings system.

---

Preventing Upgrades

Define the constant BURST_NO_UPGRADE as true before the plugin loads to completely disable all DB upgrade processing:

// In wp-config.php or a must-use plugin:
define( 'BURST_NO_UPGRADE', true );

caution

This prevents all schema migrations from running. Use only in controlled environments (e.g. read-only replicas, staging clones) where you do not want the database modified.

---

Hooks

burst_upgrade_before

Fires immediately before any upgrade logic runs, after the new DB tables are installed. Receives the previous version string.

Parameters:

Parameter	Type	Description
$prev_version	string|false	The previously installed version, or false on fresh installs

Example:

add_action( 'burst_upgrade_before', function( $prev_version ) {
    if ( $prev_version && version_compare( $prev_version, '3.3.0', '<' ) ) {
        // Run your own pre-upgrade logic here.
    }
} );

---

burst_upgrade_after

Fires after all upgrade routines have completed and the version option has been updated.

Parameters:

Parameter	Type	Description
$prev_version	string|false	The previously installed version, or false on fresh installs

Example:

add_action( 'burst_upgrade_after', function( $prev_version ) {
    // Flush your own caches after Burst upgrades.
} );

---

burst_db_upgrades

Filter the full list of database upgrade tasks. Pro add-ons use this filter to register additional migrations. Tasks with a pro_ prefix are treated as pro-only and processed via burst_upgrade_pro_iteration after all free tasks complete.

Parameters:

Parameter	Type	Description
$upgrades	array	Associative array of version => string[] pairs, where each string is a migration task identifier

Example:

add_filter( 'burst_db_upgrades', function( array $upgrades ): array {
    $upgrades['1.0.0'] = [ 'pro_my_custom_migration' ];
    return $upgrades;
} );

caution

Task identifiers prefixed with pro_ are run via burst_upgrade_pro_iteration, not the standard burst_upgrade_iteration cron event. Free task identifiers must not start with pro_.

---

burst_upgrade_iteration (WP-Cron action)

Scheduled single cron event that drives free migration batches. Each run processes one pending migration and reschedules itself (1-minute interval) until all free migrations complete.

---

burst_upgrade_pro_iteration (WP-Cron action)

Fires after all free migrations complete. Pro add-ons hook into this action to run their own batched DB migrations.

Example:

add_action( 'burst_upgrade_pro_iteration', function() {
    // Process your pro migration batch.
} );

---

burst_tasks

Used internally to inject an upgrade-progress warning into the Burst tasks/notices system. See DB_Upgrade::add_progress_notice().

---

Database Migrations by Version

All migrations are idempotent — each is tracked by a WordPress option (burst_db_upgrade_<name>). The option is deleted when the migration completes successfully.

v1.4.2.1

Migration	Description
bounces	Corrects bounce flags: clears bounce on sessions with ≥ 2 pageviews and clears bounce where time_on_page > 5000.
goals_remove_columns	Drops the event and action columns from burst_goals.

v1.5.2

Migration	Description
goals_set_conversion_metric	Sets conversion_metric = 'pageviews' on all goals where the field is NULL or empty.

v1.5.3

Migration	Description
empty_referrer_when_current_domain	Nullifies referrer values in burst_statistics that begin with the site's own home URL.
strip_domain_names_from_entire_page_url	Strips the home URL prefix from the entire_page_url column.
drop_user_agent	Drops the user_agent column from burst_statistics.

Also removes the legacy burst-statistics-endpoint.php file from the web root if present.

v1.7.0

Migrates string-based device/browser/platform/OS values to normalised lookup tables (burst_browsers, burst_browser_versions, burst_platforms, burst_devices).

Migration	Description
create_lookup_tables	Populates lookup tables with distinct values from burst_statistics.
init_lookup_ids	Sets sentinel value 999999 on all *_id columns to track migration progress.
upgrade_lookup_tables	Batch-updates *_id columns in burst_statistics by joining against lookup tables (100 000 rows per batch).
upgrade_lookup_tables_drop_columns	Drops the now-redundant browser, browser_version, device_resolution, device, and platform text columns from burst_statistics.
drop_page_id_column	Drops the old page_id integer column from burst_statistics.

v1.7.1

Migration	Description
rename_entire_page_url_column	Changes the parameters column type to TEXT.
drop_path_from_parameters_column	Extracts query strings from entire_page_url into parameters, then drops entire_page_url (batched at 50 000 rows).

v2.0.4

Migration	Description
fix_missing_session_ids	No-op cleanup (option deleted immediately; logic was removed).
clean_orphaned_session_ids	No-op cleanup (option deleted immediately; logic was removed).

v2.2.3

Removes duplicate rows from burst_goal_statistics to prepare for a UNIQUE constraint (runs inline during check_upgrade, not as a background task).

v2.2.6

Migration	Description
add_page_ids	Backfills page_id and page_type columns in burst_statistics by matching stored page URLs against WordPress posts (5 posts per batch).

v3.1.4

Migration	Description
move_referrers_to_sessions	Migrates normalised referrer values (domain only, no protocol, no www.) from the first pageview of each session in burst_statistics to the referrer column in burst_sessions (100 000 sessions per batch).

v3.1.4.1

Migration	Description
fix_trailing_slash_on_referrers	Removes trailing slashes from referrers in burst_sessions that were recorded after 2024-12-21.

v3.2.0

Migration	Description
move_reports_to_new_tables	Migrates the legacy email_reports_mailinglist option into the new burst_reports table structure. Existing entries are grouped by frequency and saved as Report objects.

v3.3.0

Breaking change

move_columns_to_sessions drops browser_id, browser_version_id, platform_id, device_id, first_time_visit, and bounce from burst_statistics. These columns are added to burst_sessions and populated before the old columns are removed. See Breaking Changes below.

Migration

Description

move_columns_to_sessions

Moves browser_id, browser_version_id, platform_id, device_id, first_time_visit, and bounce from burst_statistics to burst_sessions. Rows in burst_statistics are processed in batches (100 000 rows); sentinel value 9999 on browser_id marks a row as processed. Once all rows are processed, the six columns are dropped from burst_statistics. The burst_sessions table gains corresponding columns (browser_id INT NOT NULL DEFAULT 0, browser_version_id INT NOT NULL DEFAULT 0, platform_id INT NOT NULL DEFAULT 0, device_id INT NOT NULL DEFAULT 0, first_time_visit TINYINT NOT NULL DEFAULT 0, bounce TINYINT DEFAULT 1) with indexes. Triggered for all sites upgrading from versions prior to 3.3.0.

---

Breaking Changes

v3.3.0 — Columns removed from burst_statistics

Breaking change

In v3.3.0 the browser_id, browser_version_id, platform_id, device_id, first_time_visit, and bounce columns are migrated to burst_sessions and then dropped from burst_statistics. At the same time, burst_sessions gains these six columns. Any custom queries or third-party code that reads these columns directly from burst_statistics will break after this migration completes.

Migrate affected queries to join burst_sessions on session_id:

global $wpdb;
$results = $wpdb->get_results(
    "SELECT st.page_url, se.browser_id, se.bounce
     FROM {$wpdb->prefix}burst_statistics st
     INNER JOIN {$wpdb->prefix}burst_sessions se ON st.session_id = se.ID"
);

---

v3.2.0 — Email reports storage format changed

caution

The email_reports_mailinglist option is removed during the move_reports_to_new_tables migration. Code that reads or writes this option directly will no longer work after upgrading to v3.2.0.

---

v1.7.0 — Browser/platform/device columns removed from burst_statistics

caution

The plain-text browser, browser_version, device_resolution, device, and platform columns are dropped from burst_statistics after the lookup-table migration completes. Custom queries must join the corresponding lookup tables (burst_browsers, burst_browser_versions, burst_devices, burst_platforms) instead.

---

v1.5.3 — user_agent column removed

caution

The user_agent column is permanently removed from burst_statistics when upgrading from versions prior to 1.5.3.

---

Developer Notes

Checking upgrade progress programmatically

$db_upgrade = new \Burst\Admin\DB_Upgrade\DB_Upgrade();
$percentage = $db_upgrade->get_progress( 'all', 'all' ); // 0–100
$is_done    = $db_upgrade->progress_complete();          // bool

Option naming convention

Each migration task <name> is tracked by a WordPress option:

burst_db_upgrade_<name>

The option is set to true when a migration is scheduled and deleted (delete_option) when it completes. You can check any specific migration:

$pending = (bool) get_option( 'burst_db_upgrade_move_columns_to_sessions' );

Registering pro migrations

Pro add-ons register their own migrations via the burst_db_upgrades filter (task names must begin with pro_) and process them on the burst_upgrade_pro_iteration action:

// Register the migration.
add_filter( 'burst_db_upgrades', function( array $upgrades ): array {
    $upgrades['1.0.0'][] = 'pro_my_feature_migration';
    return $upgrades;
} );

// Schedule the migration flag during the standard upgrade hook.
add_action( 'burst_upgrade_after', function( $prev_version ) {
    if ( $prev_version && version_compare( $prev_version, '1.0.0', '<' ) ) {
        update_option( 'burst_db_upgrade_pro_my_feature_migration', true, false );
    }
} );

// Process the migration batch.
add_action( 'burst_upgrade_pro_iteration', function() {
    if ( ! get_option( 'burst_db_upgrade_pro_my_feature_migration' ) ) {
        return;
    }
    // ... run your migration ...
    delete_option( 'burst_db_upgrade_pro_my_feature_migration' );
} );