---
title: "Storage Backends"
description: "Choose between PostgreSQL, ClickHouse, and the dual-backend production topology"
---

LangSight uses a **dual-storage architecture** by default: PostgreSQL for metadata and ClickHouse for analytics. Both run via `docker compose up -d`.

> **Note (v0.2.0)**: SQLite has been removed. `docker compose up -d` is now required. Attempting `mode: sqlite` raises a `ConfigError` with migration guidance.

## 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

```yaml
storage:
  mode: dual   # default — no further config needed when using docker compose
```

Start both backends:
```bash
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.

```yaml
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.

```yaml
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:

```bash
uv run alembic upgrade head
```

The migration chain (as of v0.2.0):

| Revision | Description |
|---|---|
| `5a5d53a4c81a` | Initial schema — `api_keys`, `health_results`, `schema_snapshots`, `agent_slos` |
| `e368ec31ce04` | Users and `invite_tokens` |
| `dc0bf058f21c` | Projects and `project_members` |
| `0eaccc40f932` | `model_pricing` with seed data |

ClickHouse schema is managed automatically on startup.
