ActionScheduler_DBStore is the default store implementation that persists actions in custom database tables. It lives in classes/data-stores/ActionScheduler_DBStore.php and extends the ActionScheduler_Store abstraction.

Storage Model

ActionScheduler_DBStore persists data across several custom tables (registered via ActionScheduler_StoreSchema):

• actionscheduler_actions — core action records
• actionscheduler_groups — group slug registry
• actionscheduler_claims — claim metadata

Key persistence fields used by this store:

• action_id (primary key)
• hook
• status
• scheduled_date_gmt, scheduled_date_local
• last_attempt_gmt, last_attempt_local
• args (JSON, indexed)
• extended_args (JSON overflow)
• schedule (serialized ActionScheduler_Schedule)
• group_id (foreign key to actionscheduler_groups)
• priority
• claim_id
• attempts

Args storage and indexing

• If the JSON-encoded args length is <= max_index_length (191), they are stored in args.
• If longer, args stores an MD5 hash and the full JSON goes into extended_args.

Initialization

• init() creates and registers custom tables using ActionScheduler_StoreSchema.

Public API

save_unique_action( ActionScheduler_Action $action, ?DateTime $scheduled_date = null )

Saves a new action only if no matching pending/running action with the same hook + group exists. Uses an INSERT … SELECT WHERE NOT EXISTS pattern.

save_action( ActionScheduler_Action $action, ?DateTime $scheduled_date = null )

Saves an action unconditionally. Persists:

• hook
• status (pending/complete)
• scheduled date (GMT/local)
• schedule (serialized)
• group_id (creates group if missing)
• priority
• args/extended_args

Triggers:

• action_scheduler_stored_action

fetch_action( $action_id )

Loads an action by ID, hydrates it into an ActionScheduler_Action instance, and returns ActionScheduler_NullAction on failure. Also normalizes NULL dates.

Triggers:

• action_scheduler_failed_fetch_action (on invalid args or schedule)

query_actions( $query = array(), $query_type = 'select' )

Runs a filtered query using custom SQL. Supports filtering by:

• hook, status (string or array), args, group
• date / modified date
• claim status
• search string
• ordering and pagination
• partial args matching (off, like, json)

Partial args matching

• off (default): exact match
• like: LIKE match against JSON
• json: JSON_EXTRACT match (requires MySQL 5.7+ / MariaDB 10.2+)

action_counts()

Returns counts grouped by action status.

cancel_action( $action_id )

Sets status to canceled and fires:

• action_scheduler_canceled_action

cancel_actions_by_hook( $hook )

cancel_actions_by_group( $group )

Bulk cancel helper methods that use bulk_cancel_actions() under the hood.

Triggers:

• action_scheduler_bulk_cancel_actions (for each batch)

delete_action( $action_id )

Deletes the action record and fires:

• action_scheduler_deleted_action

get_date( $action_id )

Returns the local scheduled date if pending, or last attempt date otherwise (converted from GMT).

stake_claim( $max_actions = 10, ?DateTime $before_date = null, $hooks = array(), $group = '' )

Creates a claim in actionscheduler_claims, marks matching actions as claimed, and returns an ActionScheduler_ActionClaim with IDs.

Ordering defaults to:

priority ASC, attempts ASC, scheduled_date_gmt ASC, action_id ASC

Filter:

• action_scheduler_claim_actions_order_by

The store uses SKIP LOCKED when supported (MySQL 8.0.1+ / MariaDB 10.6.0+).

get_claim_count()

Counts active claims across pending/running actions.

get_claim_id( $action_id )

Returns the claim_id column for an action.

find_actions_by_claim_id( $claim_id )

Returns action IDs for a claim, filtered by the before_date used during claim.

release_claim( ActionScheduler_ActionClaim $claim )

Releases claims on pending actions (by action_id), then deletes the claim record. Designed to avoid deadlocks.

unclaim_action( $action_id )

Clears claim_id on a single action.

mark_failure( $action_id )

Sets status to failed.

log_execution( $action_id )

Increments attempts and marks status as in-progress, updating last attempt timestamps. Throws if update fails.

mark_complete( $action_id )

Sets status to complete and updates last attempt timestamps.

Triggers:

• action_scheduler_completed_action

get_status( $action_id )

Returns the status string.

Filters and Actions

Filters

• action_scheduler_claim_actions_order_by

  • Customize the ORDER BY clause for claim selection.

• action_scheduler_db_supports_skip_locked

  • Override whether the DB supports SKIP LOCKED.

Actions

• action_scheduler_stored_action — after saving an action
• action_scheduler_failed_fetch_action — on invalid/failed hydration
• action_scheduler_canceled_action — after cancellation
• action_scheduler_bulk_cancel_actions — after a bulk cancel batch
• action_scheduler_deleted_action — after deletion
• action_scheduler_completed_action — after marking complete

Claim Filters (Internal State)

The DB store supports internal claim filters:

• set_claim_filter( $filter_name, $filter_values )
• get_claim_filter( $filter_name )

Supported filters:

• group
• hooks
• exclude-groups

These are used by claim_actions() when stake_claim() is called.