Implementation:TobikoData Sqlmesh App Context

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

Overview

Global application state store managing SQLMesh environments, models, confirmations, and core UI state.

Description

The App_Context module implements the primary Zustand store for the SQLMesh web application. It manages environments (prod, dev, local, remote), models (SQLMesh data transformation definitions), confirmations (user approval dialogs), modules (file system organization), and application version information. The store provides methods for environment switching, model lookups, and synchronization between local and remote states.

Usage

Use this context throughout the SQLMesh web UI to access and modify global application state. It serves as the single source of truth for environment management, model data, and user interactions requiring confirmation.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/context/context.ts

Signature

interface ContextStore {
  version?: string
  showConfirmation: boolean
  confirmations: Confirmation[]
  environment: ModelEnvironment
  environments: Set<ModelEnvironment>
  lastSelectedModel?: ModelSQLMeshModel
  models: Map<string, ModelSQLMeshModel>
  modules: ModelModuleController
  splitPaneSizes: number[]

  setLastSelectedModel: (model?: ModelSQLMeshModel) => void
  setSplitPaneSizes: (splitPaneSizes: number[]) => void
  setModules: (modules: ModelModuleController) => void
  setVersion: (version?: string) => void
  setShowConfirmation: (showConfirmation: boolean) => void
  addConfirmation: (confirmation: Confirmation) => void
  removeConfirmation: () => void
  setModels: (models?: Model[]) => void
  isModel: (nameOrPath: string) => boolean
  isExistingEnvironment: (environment: ModelEnvironment | EnvironmentName) => boolean
  getNextEnvironment: () => ModelEnvironment
  setEnvironment: (environment: ModelEnvironment) => void
  addLocalEnvironment: (environment: EnvironmentName, created_from?: EnvironmentName) => void
  removeLocalEnvironment: (environments: ModelEnvironment) => void
  addRemoteEnvironments: (environments: Environment[], defaultEnvironment?: string, pinnedEnvironments?: string[]) => void
  hasRemoteEnvironments: () => boolean
}

export const useStoreContext = create<ContextStore>()

Import

import { useStoreContext } from '~/context/context'

I/O Contract

Key State Properties

Name	Type	Description
version	string	SQLMesh version string
environment	ModelEnvironment	Currently active environment
environments	Set<ModelEnvironment>	All available environments (local and remote)
models	Map<string, ModelSQLMeshModel>	Model registry indexed by name, fqn, and path
confirmations	Confirmation[]	Queue of pending user confirmation dialogs
modules	ModelModuleController	File system module tree structure

Key Methods

Name	Parameters	Description
setEnvironment	ModelEnvironment	Switch to a different environment and persist choice
addLocalEnvironment	name, created_from	Create new local development environment
addRemoteEnvironments	environments[], default, pinned[]	Sync remote environments from server
setModels	Model[]	Update model registry with new/changed models
isModel	nameOrPath	Check if given identifier corresponds to a model
addConfirmation	Confirmation	Add user confirmation dialog to queue

Implementation Details

Environment Management

Local environments: Created by users for development work
Remote environments: Synced from SQLMesh backend (prod, staging, etc.)
Pinned environments: User-marked favorites for quick access
Default environment: Automatically selected on application load

Model Registry

Models are indexed by three keys for flexible lookup:

name: Simple model name (e.g., "orders")
fqn: Fully qualified name (e.g., "db.schema.orders")
path: File system path (e.g., "models/orders.sql")

Confirmation System

Queue-based system for user approvals:

First-in-first-out (FIFO) confirmation display
Supports async operations with callbacks
Prevents accidental destructive actions

Persistence

Environment selections are persisted to localStorage via ModelEnvironment.save() for session continuity.

Usage Examples

import { useStoreContext } from '~/context/context'

function ModelSelector() {
  const { models, environment, setEnvironment } = useStoreContext()

  // Get current environment
  console.log('Active:', environment.name)

  // Switch environment
  const devEnv = Array.from(environments).find(e => e.name === 'dev')
  if (devEnv) {
    setEnvironment(devEnv)
  }

  // Check if model exists
  const hasModel = isModel('my_model')

  // Get model by any identifier
  const model = models.get('orders')
            || models.get('db.schema.orders')
            || models.get('models/orders.sql')

  return <div>{model?.name}</div>
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment