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.

​
Standard upgrade procedure

Every upgrade follows the same four steps: 
# 1. Pull the latest images
docker compose pull

# 2. Restart containers (zero data loss — data lives in named volumes)
docker compose up -d

# 3. Apply any new PostgreSQL schema migrations
docker compose exec api uv run alembic upgrade head

# 4. Verify the API is healthy
curl http://localhost:8000/api/readiness
ClickHouse schema changes are applied automatically on API startup. PostgreSQL changes require the explicit alembic upgrade head step.
Named Docker volumes (langsight_postgres_data, langsight_clickhouse_data) persist across docker compose down and docker compose pull. Your data is not affected by image updates.

​
Before you upgrade

Back up first. Especially for production deployments: 
# PostgreSQL — pg_dump
docker compose exec postgres pg_dump -U langsight langsight > backup_$(date +%Y%m%d).sql

# ClickHouse — freeze all partitions
docker compose exec clickhouse clickhouse-client \
  --query "ALTER TABLE mcp_tool_calls FREEZE"
See Backup & Restore for the full procedure.

​
Version-specific notes

​
Upgrading to v0.14.x (current)

No breaking changes. Standard procedure applies. New env vars introduced across v0.14.x:
VariableDefaultWhat it does
LANGSIGHT_WORKERS1Uvicorn worker count; requires Redis if > 1
LANGSIGHT_REDIS_URL—Redis connection string for multi-worker mode
LANGSIGHT_TRUSTED_PROXY_CIDRS127.0.0.1/32,::1/128CIDRs of trusted reverse proxies
LANGSIGHT_METRICS_TOKEN—Bearer token for /metrics (Prometheus)
All new variables are optional. Existing deployments continue to work without them.

​
Upgrading to v0.7.0

Schema changes are applied automatically on restart — no manual SQL required. The alembic upgrade head step handles them idempotently. PostgreSQL changes (auto-applied via IF NOT EXISTS):
TableChange
health_resultsproject_id TEXT NOT NULL DEFAULT '' column added
audit_logsproject_id TEXT NOT NULL DEFAULT '' column added
Existing rows retain project_id = '' (unscoped / global). ClickHouse changes (auto-applied on startup):
ObjectChange
mv_agent_sessionsMaterialized view rebuilt to include project_id; backfilled from mcp_tool_calls
The backfill runs in the background. Sessions data returns to normal once it completes (usually seconds on small datasets, a few minutes at high volume).

​
Upgrading from SQLite to dual (Postgres + ClickHouse)

If you started with mode: sqlite for evaluation and want to move to production storage:
  1. Export your current server configs from the UI (Settings → MCP Servers)
  2. Start the full stack: docker compose up -d
  3. Update .env / .langsight.yaml:
storage:
  mode: dual
  postgres_url: postgresql://langsight:${POSTGRES_PASSWORD}@postgres:5432/langsight
  clickhouse_url: http://clickhouse:8123
  1. Apply migrations: docker compose exec api uv run alembic upgrade head
  2. Re-create your API keys and users via the dashboard (SQLite users are not migrated)
Historical span data from SQLite is not migrated (it was stored in memory or SQLite files). New spans start flowing to ClickHouse immediately.

​
Rollback procedure

If an upgrade causes issues, roll back the image and reverse the migration: 
# 1. Pin to the previous image version
# Edit docker-compose.yml: image: langsight/api:0.14.11

# 2. Reverse the last Alembic migration (if any was applied)
docker compose exec api uv run alembic downgrade -1

# 3. Restart
docker compose up -d
Alembic downgrade reverses schema changes but cannot restore deleted data. Always back up before upgrading.

​
Checking your current version

# From the CLI
langsight --version

# From the API
curl http://localhost:8000/api/version
The API response also includes the active storage mode and whether Redis is connected.