> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable SmithDB on self-hosted LangSmith

> Run SmithDB alongside ClickHouse on a self-hosted LangSmith Kubernetes installation.

<Note>
  SmithDB is an opt-in datastore for self-hosted LangSmith. ClickHouse is required on LangSmith 0.16 and remains the default on 0.17. Do not disable ClickHouse on any version below 0.17. The minimum LangSmith version depends on your cloud. See [Cloud support](#cloud-support).
</Note>

SmithDB is a columnar datastore built for agent trace data: deeply nested spans, multi-modal content, and spans that stay open for hours. It keeps durable data in object storage with a per-pod disk cache, and serves LangSmith trace ingestion and queries alongside the existing ClickHouse datastore.

<CardGroup cols={2}>
  <Card title="Install SmithDB" icon="download" href="/langsmith/self-host-smithdb-install">
    Stage infrastructure, deploy SmithDB services, enable dual ingestion, and switch queries after validation.
  </Card>

  <Card title="Prepare supporting infrastructure" icon="server" href="/langsmith/self-host-smithdb-infrastructure">
    Provide a dedicated PostgreSQL metastore, object storage, and cache storage.
  </Card>

  <Card title="Configure for scale" icon="chart-bar" href="/langsmith/self-host-smithdb-scale">
    Choose a tested resource tier and size SmithDB workloads.
  </Card>

  <Card title="Configure observability" icon="activity" href="/langsmith/self-host-smithdb-observability">
    Scrape SmithDB metrics and export logs and traces to your stack.
  </Card>

  <Card title="Migrate historical data" icon="transfer" href="/langsmith/self-host-smithdb-migrate">
    Backfill ClickHouse history into SmithDB before query cutover.
  </Card>

  <Card title="Metrics reference" icon="chart-line" href="/langsmith/self-host-smithdb-metrics">
    Metrics to watch on each SmithDB component and how to read them.
  </Card>

  <Card title="Troubleshoot SmithDB" icon="tool" href="/langsmith/self-host-smithdb-troubleshooting">
    Gather context, disable SmithDB, or reset a deployment safely.
  </Card>
</CardGroup>

## Cloud support

You can enable SmithDB on any supported LangSmith Kubernetes installation, whether it is brand new or already serving traffic. [Self-host LangSmith on Kubernetes](/langsmith/kubernetes) covers the base installation; the guides above cover everything SmithDB adds on top of it.

Examples in these guides cover managed Kubernetes on AWS, GCP, and Azure. They do not cover self-managed clusters.

| Cloud | Minimum version |
| - | - |
| AWS (EKS) | LangSmith 0.16, Helm chart `0.16.14` or later |
| GCP (GKE) | LangSmith 0.16, Helm chart `0.16.14` or later |
| Azure (AKS) | LangSmith 0.17 |

## Components

Enabling SmithDB adds the following workloads to your cluster. Three services cache trace data on disk, on a network-attached volume or local SSD; the other two services are small and run on general compute. The two Jobs run to completion rather than as services. See [Cache storage](/langsmith/self-host-smithdb-infrastructure#cache-storage).

| Component | Type | What it does | Disk cache | Scaling |
| - | - | - | - | - |
| Ingestion | Service | Writes incoming traces to object storage | Yes | Horizontal |
| Query | Service | Serves trace reads for the LangSmith UI and API | Yes | Horizontal |
| Compaction worker | Service | Reorganizes stored traces in the background so queries stay fast | Yes | Horizontal |
| Compaction | Service | Schedules the background work that compaction workers carry out | No | Single instance |
| Cluster manager | Service | Coordinates the other SmithDB services | No | Single instance |
| Metastore migration | Job | Prepares the SmithDB metastore during installation | No | Runs once |
| Migration | Job | Backfills ClickHouse history; runs only if you [migrate historical data](/langsmith/self-host-smithdb-migrate) | No | Parallelism |

## Storage requirements

A self-hosted LangSmith installation uses PostgreSQL for operational data, Redis or Valkey for queuing and caching, and optional blob storage. Traces and feedback live in ClickHouse, in SmithDB, or in both while an installation runs dual ingestion. SmithDB adds its own metastore, object store, and cache storage.

On 0.17, a new installation can run SmithDB without ClickHouse; see [Install without ClickHouse](/langsmith/self-host-smithdb-install#install-without-clickhouse). Retiring ClickHouse from an existing installation is a separate procedure; contact LangChain through the [Support Portal](https://support.langchain.com/) before considering it.

For SDK method changes that work with both ClickHouse and SmithDB, see [Migrate to SmithDB-backed SDK methods](/langsmith/smithdb-sdk-migration).

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/self-host-smithdb.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>