ClickHouse

GitGuardian uses ClickHouse, an open-source column-oriented database, to power features that require fast analytics over large volumes of data (see Features that rely on ClickHouse). PostgreSQL remains the primary datastore for the rest of the application; ClickHouse is only involved for the specific features that need it.

Mandatory from 2027.1

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.

Features that rely on ClickHouse

Available today

Endpoint Protection generates a high volume of data: every machine reports thousands of findings per scan. These features need ClickHouse on your instance:

Feature	What ClickHouse stores
Machine scans with secrets findings	Scan results and findings for every machine, and the analytics in the Endpoints dashboard
AI agents and MCP inventory	MCP tool calls reported by AI Hooks, and complete AI agent sessions
Honeytoken protection on endpoints	Honeytoken coverage across your fleet

Without ClickHouse, these features aren't available on your instance. AI Hooks still block secrets in prompts and tool calls: only the MCP activity and session records need ClickHouse.

Coming next

We're moving more of the application to ClickHouse, so plan for it on every deployment, whether or not you use Endpoint Protection today:

• Richer analytics: in-app analytics computed in ClickHouse, instead of daily runs on dedicated PostgreSQL tables, with deeper analysis of the events GitGuardian collects.
• A more responsive dashboard on large workspaces: high-volume data moves out of PostgreSQL, so pages that display, filter, and pivot large datasets stay fast as your workspace grows.

Impact on sizing

The sizing recommendations are based on your number of active endpoints, since Endpoint Protection is the main ClickHouse workload today. As more features move to ClickHouse, its load will also grow with your overall workspace activity. We'll update the sizing guidance as each feature ships, and call it out in the release notes.

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.