feat(clickhouse): add the ClickHouse destination package

.github/workflows/ci.yml

@@ -186,3 +186,53 @@ jobs:
 
       - name: Build
         run: pnpm --filter "@workos/sync-mysql..." build
+
+  clickhouse:
+    name: ClickHouse Node ${{ matrix.node }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
+    env:
+      # There is no embedded ClickHouse, so the whole suite runs against the
+      # container; without this variable the database-backed tests skip.
+      TEST_CLICKHOUSE_URL: http://default@127.0.0.1:8123
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Not a service container: those start before the checkout, and the
+      # server needs the config in test/clickhouse/ — an embedded Keeper for
+      # the KeeperMap bookkeeping tables and `keeper_map_path_prefix`.
+      - name: Start ClickHouse
+        run: |
+          docker run -d --name clickhouse -p 127.0.0.1:8123:8123 \
+            -v "$PWD/packages/sync-clickhouse/test/clickhouse/config.xml:/etc/clickhouse-server/config.d/sync.xml:ro" \
+            -v "$PWD/packages/sync-clickhouse/test/clickhouse/users.xml:/etc/clickhouse-server/users.d/sync.xml:ro" \
+            -e CLICKHOUSE_SKIP_USER_SETUP=1 \
+            --ulimit nofile=262144:262144 \
+            clickhouse/clickhouse-server:26.10
+          for _ in $(seq 1 60); do
+            if curl -fsS http://127.0.0.1:8123/ping >/dev/null 2>&1; then exit 0; fi
+            sleep 1
+          done
+          echo "ClickHouse did not become ready" >&2
+          docker logs clickhouse >&2
+          exit 1
+
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Test
+        run: pnpm --filter @workos/sync-clickhouse test:database
+
+      - name: Build
+        run: pnpm --filter "@workos/sync-clickhouse..." build

.github/workflows/docker.yml

@@ -24,6 +24,7 @@ jobs:
           - postgres
           - mongodb
           - mysql
+          - clickhouse
         runner: [ubuntu-latest, ubuntu-24.04-arm]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/release-please.yml

@@ -39,6 +39,8 @@ jobs:
       sync-mysql--tag_name: ${{ steps.release.outputs['packages/sync-mysql--tag_name'] }}
       sync-mongodb--release_created: ${{ steps.release.outputs['packages/sync-mongodb--release_created'] }}
       sync-mongodb--tag_name: ${{ steps.release.outputs['packages/sync-mongodb--tag_name'] }}
+      sync-clickhouse--release_created: ${{ steps.release.outputs['packages/sync-clickhouse--release_created'] }}
+      sync-clickhouse--tag_name: ${{ steps.release.outputs['packages/sync-clickhouse--tag_name'] }}
     steps:
       # Release PRs and tags come from the SDK Automation Bot, as in workos-node.
       # Events raised with GITHUB_TOKEN start no workflow runs, so a release PR
@@ -108,3 +110,15 @@ jobs:
       tag_name: ${{ needs.release-please.outputs.sync-mongodb--tag_name }}
     secrets:
       PUBLIC_SOCKET_FIREWALL_TOKEN: ${{ secrets.PUBLIC_SOCKET_FIREWALL_TOKEN }}
+
+  publish-sync-clickhouse:
+    needs: [release-please, publish-sync-engine]
+    if: >-
+      ${{ !cancelled()
+          && needs.publish-sync-engine.result != 'failure'
+          && needs.release-please.outputs.sync-clickhouse--release_created == 'true' }}
+    uses: ./.github/workflows/release.yml
+    with:
+      tag_name: ${{ needs.release-please.outputs.sync-clickhouse--tag_name }}
+    secrets:
+      PUBLIC_SOCKET_FIREWALL_TOKEN: ${{ secrets.PUBLIC_SOCKET_FIREWALL_TOKEN }}

.release-please-manifest.json

@@ -2,5 +2,6 @@
   "packages/sync-engine": "0.1.0",
   "packages/sync-postgres": "0.1.0",
   "packages/sync-mongodb": "0.0.0",
-  "packages/sync-mysql": "0.0.0"
+  "packages/sync-mysql": "0.0.0",
+  "packages/sync-clickhouse": "0.0.1"
 }

README.md

@@ -31,15 +31,16 @@ base tables keep them as tombstones for when you want to ask who left.
 One engine, one package per database. Each ships a CLI with the same
 commands and a container image under the same name:
 
-| Destination | Package                                           | Mirror                                                                  |
-| ----------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
-| Postgres    | [`@workos/sync-postgres`](packages/sync-postgres) | A `workos` schema of tables with generated columns and `_live` views    |
-| MongoDB     | [`@workos/sync-mongodb`](packages/sync-mongodb)   | `workos_*` collections in your database, with indexes and `_live` views |
-| MySQL       | [`@workos/sync-mysql`](packages/sync-mysql)       | A `workos` database of tables with generated columns and `_live` views  |
+| Destination | Package                                               | Mirror                                                                                                                                                                        |
+| ----------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Postgres    | [`@workos/sync-postgres`](packages/sync-postgres)     | A `workos` schema of tables with generated columns and `_live` views                                                                                                          |
+| MongoDB     | [`@workos/sync-mongodb`](packages/sync-mongodb)       | `workos_*` collections in your database, with indexes and `_live` views                                                                                                       |
+| MySQL       | [`@workos/sync-mysql`](packages/sync-mysql)           | A `workos` database of tables with generated columns and `_live` views                                                                                                        |
+| ClickHouse  | [`@workos/sync-clickhouse`](packages/sync-clickhouse) | A `workos` database of `ReplacingMergeTree` tables with `_live` views, plus append-only tables for the sign-in log and events; for history that outlives the 90-day retention |
 
 The rest of this page shows Postgres; every command and option below has a
-MongoDB and a MySQL counterpart, and each package's README is the reference
-for it.
+MongoDB, a MySQL and a ClickHouse counterpart, and each package's README is
+the reference for it.
 
 ## Try it in 30 seconds
 

packages/sync-clickhouse/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WorkOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.