Environment:TobikoData Sqlmesh Web UI Stack

Knowledge Sources	TobikoData/sqlmesh
Domains	Web Development, UI, FastAPI
Last Updated	2026-02-07 21:00 GMT

Overview

Web UI server/client environment providing interactive SQLMesh interface through FastAPI backend and React TypeScript frontend.

Description

The Web UI stack combines a FastAPI-based backend server with a React TypeScript frontend client to provide an interactive interface for SQLMesh operations. The backend uses Uvicorn as the ASGI server with SSE-Starlette for real-time updates and PyArrow for efficient data serialization. The frontend is built with React and TypeScript using pnpm for package management. Docker support enables containerized deployments with docker-compose orchestration.

Usage

This environment is required when running SQLMesh's web-based UI for visual plan creation, model exploration, environment management, and interactive data transformations. The UI provides an alternative to CLI operations with graphical workflow management and real-time execution monitoring.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	Cross-platform support
Python	>= 3.9	For backend server
Node.js	>= 18.0.0	For frontend development
pnpm	Latest	Package manager for frontend
Docker	Optional	For containerized deployment
Browser	Modern browser	Chrome, Firefox, Safari, Edge

Dependencies

System Packages

Node.js and npm (for frontend development)
pnpm (install via npm: npm install -g pnpm)
Docker and docker-compose (optional, for containerized deployment)

Python Packages

fastapi==0.115.5 - Modern web framework for API backend
uvicorn[standard]==0.22.0 - ASGI server with performance optimizations
watchfiles>=0.19.0 - Hot reload for development
sse-starlette>=0.2.2 - Server-Sent Events for real-time updates
pyarrow - Efficient data serialization for large datasets

Frontend Packages

React - UI library
TypeScript - Type-safe JavaScript
Additional packages managed via pnpm (see web/client/package.json)

Credentials

Environment variables for UI configuration:

PROJECT_PATH - Path to SQLMesh project directory
UI_MODE - UI operation mode (development/production)
CONFIG - Path to custom config file
GATEWAY - Gateway name for multi-gateway setups
SQLMESH_HOME - SQLMesh home directory (inherited from Python runtime)

Additional configuration from core Python runtime:

SQLMESH_DEBUG - Enable debug logging
SQLMESH_GATEWAY - Alternative gateway specification

Quick Install

# Install SQLMesh with web UI support
pip install "sqlmesh[web]"

# Start UI server from Python (recommended)
sqlmesh ui

# Or specify custom project path and gateway
sqlmesh ui --project-path /path/to/project --gateway my_gateway

# For frontend development
cd web/client
pnpm install
pnpm run dev

# Using Docker
cd web
docker-compose up

# Or use make targets
make ui-up      # Start UI in Docker
make ui-down    # Stop UI
make ui-logs    # View logs

Code Evidence

# File: pyproject.toml:128-134
web = [
    "fastapi==0.115.5",
    "watchfiles>=0.19.0",
    "uvicorn[standard]==0.22.0",
    "sse-starlette>=0.2.2",
    "pyarrow",
]

# File: sqlmesh/cli/main.py:916-924
@ui.command("start")
@click.option("--project-path", envvar="PROJECT_PATH", help="Path to the SQLMesh project")
@click.option("--mode", envvar="UI_MODE", default="default", help="UI mode")
@click.option("--config", envvar="CONFIG", help="Path to config file")
@click.option("--gateway", envvar="GATEWAY", help="Gateway name")
def ui_start(project_path: str, mode: str, config: str, gateway: str) -> None:
    """Start the SQLMesh web UI server."""
    from sqlmesh.cli.ui_server import start_ui_server
    start_ui_server(project_path, mode, config, gateway)

# File: web/server/main.py
"""FastAPI application entry point for SQLMesh web UI."""
from fastapi import FastAPI
from sqlmesh.core.context import Context

app = FastAPI(title="SQLMesh Web UI")

@app.on_event("startup")
async def startup_event():
    """Initialize SQLMesh context on startup."""
    global sqlmesh_context
    sqlmesh_context = Context()

# ... API route definitions

# File: web/client/package.json (example structure)
{
  "name": "sqlmesh-ui",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.0.0",
    "typescript": "^5.0.0"
  }
}

Common Errors

Error Message	Cause	Solution
ModuleNotFoundError: No module named 'fastapi'	Web dependencies not installed	Install with pip install "sqlmesh[web]"
Port 8000 already in use	Another process using default port	Specify different port with --port flag
pnpm: command not found	pnpm not installed globally	Install with npm install -g pnpm
Cannot connect to server	Server not running	Start server with sqlmesh ui
Project not found	Invalid PROJECT_PATH	Verify path contains sqlmesh project (config.yaml)
SSE connection failed	Browser incompatibility or network issue	Use modern browser; check firewall settings

Compatibility Notes

FastAPI pinned to 0.115.5 for stability
Uvicorn pinned to 0.22.0 (standard bundle includes WebSockets)
PyArrow provides efficient data transfer for large result sets
SSE-Starlette enables real-time plan updates without polling
Watchfiles enables hot reload during development
Frontend requires Node.js 18+ for modern JavaScript features
pnpm preferred over npm for faster installs and disk efficiency
Docker setup uses multi-stage builds for optimized images
Web UI supports all SQLMesh operations available via CLI
Context operations (plan, apply, test) exposed via REST API
WebSocket support available through uvicorn[standard]
Cross-origin requests (CORS) configured for local development

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment