Implementation:TobikoData Sqlmesh Model PlanAction

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, Plan_Management, State_Management
Last Updated	2026-02-07 20:00 GMT

Overview

State management model for SQLMesh plan actions tracking plan lifecycle states and determining UI behavior.

Description

ModelPlanAction represents the current state of a SQLMesh plan operation in the web UI, managing transitions between states like Run, Running, Applying, Cancelling, and Done. The class provides computed properties for checking specific states and helper methods for determining appropriate UI labels and available actions based on plan tracker states.

Key features include comprehensive state checking properties (isRun, isDone, isApply variants, isProcessing), static method getPlanAction() that computes current state from multiple trackers (overview, apply, cancel), displayStatus() for user-facing status messages, and getActionDisplayName() for button/action labels.

The model supports different application modes: ApplyVirtual (virtual environment update), ApplyBackfill (backfill only), ApplyChangesAndBackfill (both changes and backfill), and ApplyMetadata (metadata only).

Usage

Use this class to manage plan state in the UI, determining when to show progress indicators, enable/disable action buttons, and display appropriate status messages to users.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/models/plan-action.ts

Signature

export class ModelPlanAction<
  T extends InitialPlanAction = InitialPlanAction
> extends ModelInitial<T> {
  private readonly _value: PlanAction

  constructor(initial?: T | ModelPlanAction<T>)

  get value(): PlanAction
  get isRun(): boolean
  get isDone(): boolean
  get isApplyVirtual(): boolean
  get isApplyBackfill(): boolean
  get isApplyChangesAndBackfill(): boolean
  get isApplyMetadata(): boolean
  get isApply(): boolean
  get isCancelling(): boolean
  get isApplying(): boolean
  get isRunning(): boolean
  get isRunningTask(): boolean
  get isProcessing(): boolean
  get isIdle(): boolean

  displayStatus(planOverview: ModelPlanOverviewTracker): string

  static getActionDisplayName(
    action: ModelPlanAction,
    options: PlanAction[],
    fallback: string
  ): string

  static getPlanAction(params: {
    planOverview: ModelPlanOverviewTracker
    planApply: ModelPlanApplyTracker
    planCancel: ModelPlanCancelTracker
  }): PlanAction
}

export const EnumPlanAction = {
  Done: 'done',
  Run: 'run',
  Running: 'running',
  RunningTask: 'running-task',
  ApplyVirtual: 'apply-virtual',
  ApplyBackfill: 'apply-backfill',
  ApplyChangesAndBackfill: 'apply-changes-and-backfill',
  ApplyMetadata: 'apply-metadata',
  Applying: 'applying',
  Cancelling: 'cancelling',
} as const

Import

import { ModelPlanAction, EnumPlanAction } from '@models/plan-action'

I/O Contract

Inputs

Name	Type	Required	Description
initial	ModelPlanAction	No	Initial plan action state (defaults to 'run')

Outputs

Property	Type	Description
value	PlanAction	Current action state
isRun	boolean	True if ready to run plan
isDone	boolean	True if plan completed
isApply	boolean	True for any apply variant
isApplyVirtual	boolean	True for virtual environment update
isApplyBackfill	boolean	True for backfill only
isApplyChangesAndBackfill	boolean	True for changes + backfill
isApplyMetadata	boolean	True for metadata update only
isApplying	boolean	True during apply execution
isRunning	boolean	True during plan execution
isCancelling	boolean	True during cancellation
isProcessing	boolean	True if running, applying, or cancelling
isIdle	boolean	True if not processing

Usage Examples

// Create action from current plan state
const action = new ModelPlanAction({
  value: EnumPlanAction.Run
})

// Check state
if (action.isRun) {
  console.log('Ready to run plan')
}

// Determine action from trackers
const currentAction = ModelPlanAction.getPlanAction({
  planOverview: overviewTracker,
  planApply: applyTracker,
  planCancel: cancelTracker
})

// Returns:
// - 'run' if all trackers are empty
// - 'cancelling' if cancel is running
// - 'applying' if apply is running
// - 'running' if overview is running
// - 'done' if finished
// - 'apply-virtual' | 'apply-backfill' | 'apply-changes-and-backfill' | 'apply-metadata'
//   based on plan overview state

// Get display status for UI
const status = action.displayStatus(planOverview)
console.log(status)
// Returns: "Getting Changes...", "Checking Plan...", "Applying Plan...", etc.

// Get action button label
const buttonLabel = ModelPlanAction.getActionDisplayName(
  action,
  [EnumPlanAction.Run, EnumPlanAction.ApplyVirtual],
  'Plan'
)
console.log(buttonLabel)
// Returns: "Plan" for Run, "Apply Virtual Update" for ApplyVirtual

// Disable UI during processing
if (action.isProcessing) {
  button.disabled = true
}

// Show different UI based on apply type
if (action.isApplyVirtual) {
  console.log('Virtual update - no backfill needed')
} else if (action.isApplyBackfill) {
  console.log('Backfill operation')
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment