Implementation:TobikoData Sqlmesh Model TrackerPlan

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

Overview

Base tracker class for monitoring SQLMesh plan operation states including execution status, timing, and completion.

Description

ModelPlanTracker is a generic base class for tracking asynchronous plan operations (overview, apply, cancel) in the SQLMesh web UI. It maintains current state, metadata with status tracking, start/end timestamps, plan options, and fetching state. The class provides computed properties for determining operation lifecycle states like isRunning, isFinished, isSuccessful, and isFailed based on metadata status values.

Key features include optional fetching state management separate from operation completion, duration tracking in metadata, status-based state determination (init = running, success/fail = finished), and reset() method for clearing tracker state between operations.

This is an abstract base class extended by specific tracker types for different plan operations (overview, apply, cancel).

Usage

Use this class as the foundation for implementing specific plan trackers that monitor long-running operations in the UI, providing consistent state management and status checking.

Code Reference

Source Location

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

Signature

export class ModelPlanTracker<
  TData extends PlanTracker = PlanTracker
> extends ModelInitial<TData> {
  _current: Optional<TData>
  _isFetching: boolean = false

  constructor(model?: ModelPlanTracker<TData>)

  get current(): Optional<TData>
  get environment(): Optional<string>
  get meta(): Optional<PlanTrackerMeta>
  get plan_options(): Optional<PlanOptions>
  get start(): Optional<PlanOverviewStageTrackerStart>
  get end(): Optional<PlanOverviewStageTrackerEnd>
  get duration(): number
  get isFinished(): boolean
  get isRunning(): boolean
  get isSuccessful(): boolean
  get isFailed(): boolean
  get isEmpty(): boolean
  get isFetching(): boolean
  set isFetching(value: boolean)

  reset(): void
}

export interface PlanTracker {
  environment: string
  meta: PlanTrackerMeta
  plan_options: PlanOptions
  start?: PlanOverviewStageTrackerStart
  end?: PlanOverviewStageTrackerEnd
}

export interface PlanTrackerMeta extends TrackableMeta {
  duration?: number
}

Import

import { ModelPlanTracker } from '@models/tracker-plan'

I/O Contract

Inputs

Name	Type	Required	Description
model	ModelPlanTracker<TData>	No	Existing tracker to copy state from

Outputs

Property	Type	Description
current	Optional<TData>	Current tracker data (undefined if no operation)
environment	Optional<string>	Target environment name
meta	Optional<PlanTrackerMeta>	Operation metadata with status and timing
plan_options	Optional<PlanOptions>	Plan configuration options
start	Optional<PlanOverviewStageTrackerStart>	Operation start metadata
end	Optional<PlanOverviewStageTrackerEnd>	Operation end metadata
duration	number	Operation duration in milliseconds (-1 if not available)
isFinished	boolean	True if operation completed (done=true and not fetching)
isRunning	boolean	True if operation in progress (done=false or fetching)
isSuccessful	boolean	True if finished with success status
isFailed	boolean	True if finished with fail status or no metadata
isEmpty	boolean	True if no current operation data
isFetching	boolean	True if currently fetching data

Usage Examples

// Create a tracker for plan overview
const overviewTracker = new ModelPlanTracker<PlanOverviewTracker>()

// Set fetching state before API call
overviewTracker.isFetching = true

// Update with operation data
overviewTracker._current = {
  environment: 'prod',
  meta: {
    done: false,
    status: Status.init,
    duration: 0
  },
  plan_options: {
    auto_apply: false,
    no_prompts: true
  },
  start: {
    ts: Date.now()
  }
}

// Check operation state
if (overviewTracker.isRunning) {
  console.log('Plan is running...')
}

// After completion
overviewTracker._current.meta.done = true
overviewTracker._current.meta.status = Status.success
overviewTracker._current.meta.duration = 5000
overviewTracker.isFetching = false

// Check completion
if (overviewTracker.isSuccessful) {
  console.log(`Plan completed in ${overviewTracker.duration}ms`)
}

// Reset for next operation
overviewTracker.reset()
console.log(overviewTracker.isEmpty) // true

// Check failure
if (overviewTracker.isFailed) {
  console.error('Operation failed')
}

// Multiple trackers for complete plan state
const planAction = ModelPlanAction.getPlanAction({
  planOverview: overviewTracker,
  planApply: applyTracker,
  planCancel: cancelTracker
})

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment