Implementation:TobikoData Sqlmesh Api Channels

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

Overview

Server-Sent Events (SSE) channel manager for real-time communication between the SQLMesh web client and server.

Description

The Api_Channels module implements a robust EventSource-based pub/sub system for subscribing to server events. It provides automatic reconnection handling, channel management, and message parsing for real-time updates in the SQLMesh web UI. The EventSourceConnection class manages the underlying EventSource connection with built-in retry logic and automatic resubscription after disconnections.

Usage

Use this module when you need to establish real-time communication channels with the SQLMesh backend server, such as for plan progress updates, test execution status, or deployment notifications.

Code Reference

Source Location

• Repository: TobikoData_Sqlmesh
• File: web/client/src/api/channels.ts

Signature

export type EventSourceChannel = <TData = any>(
  topic: string,
  callback?: ChannelCallback<TData>,
) => Channel

export interface Channel {
  subscribe: () => void
  unsubscribe: () => void
}

export function useChannelEvents(): EventSourceChannel

Import

import { useChannelEvents } from '@api/channels'

I/O Contract

Inputs

Name	Type	Required	Description
topic	string	Yes	Event topic/channel name to subscribe to
callback	ChannelCallback<TData>	No	Function called when messages are received on the channel

Outputs

Name	Type	Description
Channel	Object	Object with subscribe() and unsubscribe() methods for managing the subscription

Implementation Details

Key Features

• Auto-reconnection: Reconnects after 3 seconds on errors, 20 seconds on ping timeout
• Channel persistence: Automatically resubscribes to all channels after reconnection
• JSON parsing: Automatically parses incoming message data as JSON
• Singleton pattern: Single EventSource connection shared across all channels

Event Handling

The system listens for two built-in events:

• error: Triggers immediate reconnection attempt
• ping: Resets reconnection timer to maintain long-lived connections

Usage Examples

import { useChannelEvents } from '@api/channels'

// Create channel instance
const createChannel = useChannelEvents()

// Subscribe to plan updates
const planChannel = createChannel('plan/progress', (data) => {
  console.log('Plan progress:', data.percentage)
})

planChannel.subscribe()

// Later, unsubscribe
planChannel.unsubscribe()

Related Pages

• TobikoData_Sqlmesh_Api_Instance
• Environment:TobikoData_Sqlmesh_Web_UI_Stack