Implementation:TobikoData Sqlmesh API Plan

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_Server, REST_API
Last Updated	2026-02-07 20:00 GMT

Overview

Concrete tool for generating and managing SQLMesh plans provided by the SQLMesh web server.

Description

This module exposes FastAPI endpoints for plan operations. The /plan endpoint initiates asynchronous plan generation with validation, changes detection, and backfill analysis tracked through stage-based progress reporting. The /plan/cancel endpoint cancels running plan operations using a circuit breaker pattern. Plan generation creates a PlanBuilder that analyzes snapshot changes (added, removed, modified), computes missing intervals for backfills, and supports categorization for change management.

Usage

These endpoints are called by the SQLMesh web UI during the plan workflow. The initiate endpoint starts plan generation when users create or update environments. The UI subscribes to plan events to display real-time progress through validation, changes, and backfills stages. The cancel endpoint is invoked when users abort long-running plan operations.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/server/api/endpoints/plan.py

Signature

@router.post("", response_model=t.Optional[models.PlanOverviewStageTracker])
async def initiate_plan(
    request: Request,
    response: Response,
    context: Context = Depends(get_loaded_context),
    environment: t.Optional[str] = Body(None),
    plan_dates: t.Optional[models.PlanDates] = None,
    plan_options: t.Optional[models.PlanOptions] = None,
    categories: t.Optional[t.Dict[str, SnapshotChangeCategory]] = None,
) -> t.Optional[models.PlanOverviewStageTracker]

@router.post("/cancel", response_model=t.Optional[models.PlanCancelStageTracker])
async def cancel_plan(
    request: Request,
    response: Response,
) -> t.Optional[models.PlanCancelStageTracker]

Import

from web.server.api.endpoints.plan import router

I/O Contract

Inputs

Endpoint	Method	Parameters	Description
/api/plan	POST	environment, plan_dates, plan_options, categories	Initiates asynchronous plan generation with tracking
/api/plan/cancel	POST	None	Cancels running plan operation

Outputs

Endpoint	Response Type	Description
/api/plan	PlanOverviewStageTracker	Returns None with 204; progress tracked via events
/api/plan/cancel	PlanCancelStageTracker	Returns None with 204; cancellation status via events

Usage Examples

# Initiate plan for environment
import httpx
response = httpx.post(
    "http://localhost:8000/api/plan",
    json={
        "environment": "dev",
        "plan_dates": {"start": "2024-01-01", "end": "2024-01-31"},
        "plan_options": {
            "skip_tests": False,
            "skip_backfill": False,
            "include_unmodified": False,
            "no_gaps": True,
            "forward_only": False
        }
    }
)

# Initiate plan with categorization choices
response = httpx.post(
    "http://localhost:8000/api/plan",
    json={
        "environment": "dev",
        "categories": {
            "my_schema.my_model": "BREAKING"
        }
    }
)

# Cancel running plan
response = httpx.post("http://localhost:8000/api/plan/cancel")

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment