ClickHouse
GitGuardian uses ClickHouse, an open-source column-oriented database, to power features that require fast analytics over large volumes of data (for example, machine and endpoint secret occurrence analytics). PostgreSQL remains the primary datastore for the rest of the application; ClickHouse is only involved for the specific features that need it.
Starting with release 2027.1.0, ClickHouse and its object storage backend become mandatory for every self-hosted deployment. See the customer notice for what changes and how to prepare.
Deployment model
ClickHouse runs as a dedicated, in-cluster stateful component, and relies on external object storage (S3-compatible, Azure Blob Storage, or Google Cloud Storage) for durable data storage. It is not a fully externally managed database like PostgreSQL or Redis. See ClickHouse storage for details.
Default topology
ClickHouse is deployed as a single node. This is the simplest and lightest-footprint option, and is sufficient for the vast majority of deployments, though it is not highly available: there is no other replica to fail over to.
Supported version
GitGuardian pins the ClickHouse version shipped with each release to the same version running our SaaS offering, and validates it against our test suite before release. Do not attempt to run a different ClickHouse version than the one shipped with your release.
Storage
ClickHouse splits its storage into three parts: local metadata and filesystem cache volumes, and object storage holding the actual table data, where the bulk of the storage footprint lives and where clickhouse-backup writes to when backing up.
See ClickHouse storage for the local volumes and provider-specific object storage configuration, Sizing and hardening for hardware sizing, Backup and restore for the backup runbook, and Monitoring and alerting to catch a failing backup that pod health won't show you.
Required configuration
A production-ready ClickHouse deployment requires all of the following to be configured:
| What to configure | Details | Where |
|---|---|---|
| Compute sizing and hardening | Node & instance resources, scheduling, node stability | Sizing and hardening |
| ClickHouse credentials | Instance password | Prerequisites |
| Object storage configuration | S3 / Azure Blob / GCS backend, disk authentication | Storage → Configuration |
| In-cluster volumes configuration | Metadata & cache volumes, storage class | Storage → Local volumes |
| Backup configuration | Destination bucket, credentials secret, schedule & retention | Backup and restore |
To install ClickHouse, see Install ClickHouse.
