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

# ClickHouse

> Run managed ClickHouse for analytics, event and metrics workloads.

ClickHouse is a columnar database built for reading one column across billions of rows,
which is the shape of analytics, event and metrics workloads.

Siblings reach the instance at its service name. It is not reachable from outside the
cluster.

## Creating an instance

**Console**

Select **New → Database**, then **ClickHouse**. The form asks for a name, a version, a
database and user, the compute allocation and a disk size.

The database and user default to randomised names derived from the service rather than
a guessable `default`.

**slipway.yaml**

```yaml slipway.yaml theme={"system"}
version: 1

databases:
  - name: analytics
    engine: clickhouse
    version: "25.3"
    diskSizeGB: 100
    cpu: 2
    memory: 4GB
```

| Engine | `engine:` | Versions | Default | Port | Data path | Memory floor |
| - | - | - | - | - | - | - |
| Postgres | `postgres` | 18, 17, 16, 15 | 18 | 5432 | `/var/lib/postgresql` | 512 MiB |
| Redis | `redis` | 8 | 8 | 6379 | `/data` | 512 MiB |
| MySQL | `mysql` | 8.4, 8.0 | 8.4 | 3306 | `/var/lib/mysql` | 1 GiB |
| ClickHouse | `clickhouse` | 25.3, 24.8 | 25.3 | 8123 HTTP, 9000 native | `/var/lib/clickhouse` | 2 GiB |

`latest` is not a valid version. A managed database has to be reproducible, so the tag is
always pinned.

The memory floor is the smallest allocation the engine runs on. If you configure less,
the deploy fails rather than silently raising it.

> [!WARNING]
>
> ClickHouse needs at least 2 GiB, and 4 GiB is a better starting point. Its caches size
> themselves from the machine rather than the container, so a small allocation turns into an
> out-of-memory loop that reads as a broken image. slipway writes a config overlay scaled to
> the allocation you pick and re-renders it on every deploy, so it stays correct after a
> resize.

## Two ports, one instance

ClickHouse answers on two protocols and slipway declares both.

| Port | Protocol | Used by |
| - | - | - |
| 8123 | HTTP | `clickhouse-connect`, `curl`, most BI tools, the JS client |
| 9000 | Native TCP | `clickhouse-client`, `clickhouse-go`, the JDBC driver |

This is one instance with two ports, not two services. A sibling reaches either directly:

```yaml slipway.yaml theme={"system"}
services:
  - name: api
    env:
      CLICKHOUSE_URL: ${service.analytics.url}
      CLICKHOUSE_HTTP: http://analytics:8123
```

`${service.analytics.url}` resolves to the **native** form, because that is what
`clickhouse-connect`, `clickhouse-go` and the JDBC driver parse. Build the HTTP form from
`${service.analytics.host}` as above.

Readiness is gated on 8123. The native port accepts connections slightly before the server
can answer, so HTTP is the honest signal.

## Authentication

Each instance is provisioned with a generated password for its primary user, stored as the
project secret `<SERVICE>_PASSWORD`.

Additional users are managed on the service's **Credentials** tab and are created with SQL
`CREATE USER`, so they live in the instance's own data directory on the disk and survive
restarts.

## External access

Not available. ClickHouse instances are reachable from siblings in their project. To query
one from your machine, open the service's **Shell** and run `clickhouse-client` in the pod.

## Backups

The disk mounts at `/var/lib/clickhouse` and is backed up on a schedule, restorable in
place from the service's **Disks** tab. Retention depends on your plan. See
[Disks](/data/disks).

## Metrics

The service overview shows CPU, memory and active connections, sampled every 30 seconds.
The [Metrics tab](/observability/metrics) charts those over a window you choose, plus disk
usage against the volume's size.

## Pricing

| What | Rate |
| - | - |
| CPU | \$8.76 per vCPU per month |
| Memory | \$4.38 per GiB per month |
| Disk | \$0.25 per GiB per month |
| Volume backups | \$0.05 per GiB per month |
| Object storage | \$0.05 per GiB per month |
| Egress beyond the plan allowance | \$0.01 per GB |

Compute is metered by the second against the allocation a service is configured with, so
a service that sleeps costs nothing while it is asleep. Disk, backups and object storage
are metered on what is provisioned or held, whether or not the service is running.

ClickHouse is priced on the allocation you configure. The disk is billed on its
provisioned size. There is no per-query, per-row or per-scanned-byte charge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.