Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.langsight.dev/llms.txt

Use this file to discover all available pages before exploring further.

LangSight uses a dual-storage architecture by default: PostgreSQL for metadata and ClickHouse for analytics. Both run via docker compose up -d.
Note: SQLite mode (mode: sqlite) remains available for local development and evaluation but is not supported for production. It is not recommended for multi-user deployments — use dual mode with Docker Compose for any shared or persistent installation.

​
Dual (default — production topology)

Routes each operation to the right backend automatically:
  • PostgreSQL (metadata): users, projects, API keys, model pricing, SLOs, invite tokens, alert config, audit logs
  • ClickHouse (analytics): spans, traces, health results, reliability stats, costs, sessions
storage:
  mode: dual   # default — no further config needed when using docker compose
Start both backends: 
cp .env.example .env   # fill in POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, etc.
docker compose up -d

​
PostgreSQL only

Metadata operations only — no span analytics, no langsight costs, no session tracing. 
storage:
  mode: postgres
  postgres_url: postgresql://user:password@localhost:5432/langsight
Best for: deployments that only need health check history and user management, without the analytics workload.

​
ClickHouse only

Analytics operations only — no user management, no RBAC, no API keys in DB. 
storage:
  mode: clickhouse
  clickhouse_url: http://localhost:8123
  clickhouse_database: langsight
  clickhouse_username: langsight
  clickhouse_password: ""
Best for: read-only analytics deployments where auth is handled externally.

​
Migration path

Any v0.1.x SQLite deployment  → docker compose up -d  → mode: dual
Postgres-only deployment       → add ClickHouse        → mode: dual
ClickHouse-only deployment     → add Postgres          → mode: dual

​
Database migrations (PostgreSQL)

LangSight uses Alembic for schema migrations. When using PostgreSQL, run migrations after each update: 
uv run alembic upgrade head
The migration chain (as of v0.7.0):
RevisionDescription
5a5d53a4c81aInitial schema — api_keys, health_results, schema_snapshots, agent_slos
e368ec31ce04Users and invite_tokens
dc0bf058f21cProjects and project_members
0eaccc40f932model_pricing with seed data
ClickHouse schema is managed automatically on startup.

​
v0.7.0 schema changes (auto-applied on restart)

The following changes apply when upgrading to v0.7.0. No manual migration step is required — they are applied automatically when the API container starts.

​
PostgreSQL

TableChange
health_resultsproject_id column added via ALTER TABLE ... ADD COLUMN IF NOT EXISTS — no data loss, new rows tagged with project context
audit_logsproject_id column added via ALTER TABLE ... ADD COLUMN IF NOT EXISTS — existing rows retain NULL for this column
Both changes use IF NOT EXISTS — safe to apply on a running instance and idempotent on repeated restarts.

​
ClickHouse

ObjectChange
mv_agent_sessionsMaterialized view rebuilt with project_id — the view is DROPped and re-created on startup, then backfilled from mcp_tool_calls. No span data is lost; the source table is unchanged.
The mv_agent_sessions rebuild may take a few seconds on large datasets while the backfill from mcp_tool_calls runs. The API is available immediately; sessions data returns to normal once the backfill completes.