This document describes how Action Scheduler manages schema versions and upgrades for its custom tables.
The behavior is defined in classes/abstracts/ActionScheduler_Abstract_Schema.php and the concrete schema
classes in classes/schema/.

Schema version numbers

• ActionScheduler_StoreSchema sets protected $schema_version = 8 for the actions, claims, and groups tables.
• ActionScheduler_LoggerSchema sets protected $schema_version = 3 for the logs table.

Incrementing these values triggers a schema update on the next registration run.

Version storage

Each schema class stores its current version in WordPress options under a class-based key:

schema-ActionScheduler_StoreSchema
schema-ActionScheduler_LoggerSchema

When a schema update completes, the option value is saved as a string in the format:

<schema_version>.0.<unix_timestamp>

This timestamped value is used to avoid race conditions while still reflecting the numeric schema version.

Update detection

ActionScheduler_Abstract_Schema::schema_update_required() compares the stored option value
to the class schema_version using version_compare(). If the stored version is lower, an update runs.

When no option exists, the method also checks for legacy options created by the Action Scheduler
Custom Tables plugin:

• schema-Action_SchedulerCustom_TablesDB_Store_Table_Maker
• schema-Action_SchedulerCustom_TablesDB_Logger_Table_Maker

If found, it uses that value and deletes the legacy option.

Update flow

Schema registration happens via register_tables() in the abstract base class:

1. Registers table names with $wpdb so they are globally available.
2. If an update is required (or forced), iterates each table and:
   • Fires action_scheduler_before_schema_update with the table name and stored db version.
   • Calls dbDelta() with the CREATE TABLE statement from get_table_definition().
   • Fires action_scheduler/created_table when dbDelta() reports a new table creation.
3. Writes the updated version option when complete.

Targeted upgrade hooks

Some schema changes cannot be done via dbDelta(). To handle these, the schema classes attach
version-specific upgrade methods to the action_scheduler_before_schema_update hook:

Store schema

ActionScheduler_StoreSchema::update_schema_5_0() runs only when:

• the table is actionscheduler_actions, and
• the stored version is below 5.

It runs a direct ALTER TABLE to change datetime columns to allow NULL with a default
'0000-00-00 00:00:00' to avoid issues on servers using sql_mode=NO_ZERO_DATE.

Affected columns:

• scheduled_date_gmt
• scheduled_date_local
• last_attempt_gmt
• last_attempt_local

Logger schema

ActionScheduler_LoggerSchema::update_schema_3_0() runs only when:

• the table is actionscheduler_logs, and
• the stored version is below 3.

It runs a direct ALTER TABLE to change datetime columns to allow NULL with a default
'0000-00-00 00:00:00'.

Affected columns:

• log_date_gmt
• log_date_local