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

  1. Frontend processes CREATE/ALTER/DROP TASK through TaskStorage, retaining the account, default database, and creator identity. SHOW TASKS and SHOW TASK RUNS read definitions and history.

  2. 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.

  3. 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.

  4. Manual EXECUTE TASK uses the same executor and records MANUAL, without waiting for cron. SUSPEND does not block this entry point.

Distinctions that matter

  • Definitions and history differ. Dropping a definition retains history; absence from SHOW TASKS does not mean a Task never ran.

  • A scheduled trigger is not a successful execution. SCHEDULED identifies the trigger; SUCCESS identifies 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 TIMEOUT is 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.