<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# ClickHouse Cloud

## Introduction

[ClickHouse Cloud](https://clickhouse.com/cloud) is ClickHouse's hosted analytics database. The sync engine uses the `@workos/sync-clickhouse` destination to keep WorkOS sign-in and event history alongside users, organizations, and other mirrored objects, so you can query them together.

The [ClickHouse Cloud integration guide](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md) in the sync engine repository covers service selection, database users, network access, connections, and deployment.

## Prepare the service

Create a service near the host that will run the sync, and allow that host through the service's IP access list or private networking. The engine uses the HTTPS interface, not the native ClickHouse protocol. See [Network access](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#network-access) for connectivity requirements.

For production, use a dedicated database user with the permissions listed in the [`@workos/sync-clickhouse` README](https://github.com/workos/sync-engine/blob/main/packages/sync-clickhouse/README.md#command-line). The [Database user guide](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#database-user) explains the verification limits for dedicated users on Cloud.

## Run from your own host

Use the service's HTTPS endpoint with credentials as `DATABASE_URL`. Cloud uses publicly trusted certificates, so no custom CA is needed. See [Choose a connection](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#choose-a-connection) for the URL format and database selection.

Follow [Run the sync from your own host](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#run-the-sync-from-your-own-host) to initialize the mirror, backfill existing objects, and start polling for changes. You can run the sync as a command, container, or library. Sign-in history begins when you start syncing; `backfill` cannot recover past sign-ins.

A continuous `listen` process keeps the service awake and billing compute. Scheduled `tick` runs let it idle between runs, but the next request waits for it to wake. See [Idling](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#idling) before choosing how to run the sync.

## Query the mirror

Use the generated `_live` views, such as `workos.users_live`, for the current state of mirrored objects. They read with `FINAL` and exclude deleted objects. The `workos.auth_attempts` and `workos.events` tables hold sign-in and event history. Include `_env` when filtering or joining data from multiple WorkOS environments.

See [Query it](https://github.com/workos/sync-engine/blob/main/docs/integrations/clickhouse-cloud.md#query-it) for the Cloud SQL console and other clients. The [package README](https://github.com/workos/sync-engine/blob/main/packages/sync-clickhouse/README.md) includes an example of failed sign-ins per organization and is the reference for schema, configuration, and operations.
