SQL Tasks and internal TaskService¶
This chapter targets v4.2.5 (source tag v4.2.5, commit 1a44f3db3056e32975fde86ca0ab69a094996a3f). User SQL Tasks are one kind of work hosted by TaskService. Internal asynchronous tasks, daemon tasks, CDC, and other background work are not all CREATE TASK objects.
Definition, scheduling, and execution¶
Frontend processes
CREATE/ALTER/DROP TASKthrough TaskStorage, retaining the account, default database, and creator identity.SHOW TASKSandSHOW TASK RUNSread definitions and history.The SQL cron service periodically reads enabled scheduled definitions, builds six-field cron timers with a timezone, and checks the current definition on a trigger. It updates timing and trigger counts and creates an asynchronous task from the context.
The task runner invokes SQLTaskExecutor. For each attempt, the executor acquires a run record and overlap protection, evaluates
WHEN, executes body statements in order, and stores success, failure, skip, or timeout history.Manual
EXECUTE TASKuses the same executor and recordsMANUAL, without waiting for cron.SUSPENDdoes not block this entry point.
Distinctions that matter¶
Definitions and history differ. Dropping a definition retains history; absence from
SHOW TASKSdoes not mean a Task never ran.A scheduled trigger is not a successful execution.
SCHEDULEDidentifies the trigger;SUCCESSidentifies completion. Seconds in cron do not guarantee end-to-end latency.Each body statement is sent to InternalExecutor individually. The body is not one transaction; retries start again and business logic must handle repeated writes.
Timeouts are stored as whole seconds, with subsecond values becoming zero. Gate evaluation has a separate internal timeout. Body
TIMEOUTis not a deadline for the entire scheduling path.Creator context is passed into internal execution; it does not grant cross-account access. Isolation, crash recovery, and multi-CN takeover need separate topology and privilege experiments.
Source and verification entry points¶
These links are pinned to v4.2.5 to distinguish later changes:
The 2026-10-14 single-CN probe covered manual and cron runs, gates, retries, timeouts, overlap rejection, and retained history. It did not certify cross-CN crash recovery or exactly-once execution.