When PostgreSQL is enough for Lago events and when ClickHouse earns its place
Keep the default PostgreSQL store unless your event volume and query load justify operating a second data system. In a self-hosted Lago deployment, PostgreSQL holds the application data, and ClickHouse is an optional external store for high-volume events that is disabled by default. The volume at which ClickHouse becomes worth its cost is a threshold you must measure in your own environment, because this page does not provide one. Start by counting events per day, peak ingestion rate per minute, and the number and shape of usage queries your billing runs and dashboards issue against the event table.
PostgreSQL remains the right choice when event volume is modest, when billing runs and customer-facing usage views complete within your service windows on the existing database, and when your team already runs PostgreSQL backups, upgrades and high availability. Your operating model does not change, and you avoid a second backup policy, a second upgrade path and a second set of access controls. Confirm with the Lago release you intend to pin that the event store behaves as your load test shows before you commit to the default.
ClickHouse earns its place when measured ingestion or query load pushes PostgreSQL past the latency or maintenance limits you set. Enabling it means provisioning a ClickHouse cluster as an external service, planning its replication and backups separately from PostgreSQL, and scaling the workers that write to it. Before you enable it, ask your team to rehearse a restore, confirm which ClickHouse release line your security patching policy covers, and cost the added staff time against the database load it removes. Treat the switch as a planned migration with a rollback path, not a toggle you flip under pressure.
Which option fits which volume and team profile
PostgreSQL is the natural default when your team wants a single stateful system to back up, patch, monitor and restore. Lago already needs PostgreSQL for application data in its Docker Compose deployment, so keeping usage events in the same store adds no new engine to the estate. This option matters most when your event rate is modest relative to what your PostgreSQL instance can handle, and when the people on call know PostgreSQL well. Measure your own event rate and query pattern before assuming this holds, because the threshold depends on your hardware, retention window and the reports your finance and product teams run.
- Fewer moving parts: One backup routine, one set of credentials and one upgrade path cover billing data and events.
- Known operating model: PostgreSQL supports hot standby, synchronous and asynchronous replication, and logical replication between major versions, which gives your team established runbooks.
- Upgrade flexibility: Logical replication can support major upgrades with only several seconds of downtime, according to the PostgreSQL upgrading documentation.
- Added responsibility: PostgreSQL does not detect a failed primary or promote a standby by itself, so automatic failover needs external tooling you must select, run and test.
- Scaling limit to plan for: As events accumulate, you will need to watch table size, indexing and vacuum behavior and decide when to partition or move events out.
Before committing, check your event volume and reporting queries against a representative copy of your data, and confirm the failover and restore tooling your team will run.
ClickHouse is an analytical database built for large scans and aggregations over event data. This option matters when your organization already runs analytical infrastructure, has people who operate it, and wants usage events queryable at a scale that would strain a transactional store. Enabling ClickHouse in Lago is an external store that is disabled by default, so it is an explicit decision rather than a default. It adds a second stateful system to design, secure and recover, and it changes how you size and deploy workers.
- Analytical query performance: ClickHouse is designed for aggregating large volumes of event rows, which suits heavy usage reporting.
- Replication and recovery: ReplicatedMergeTree tables use ClickHouse Keeper, which the replication guide recommends running as at least three nodes on dedicated hosts in production, and a recovered replica syncs missing data automatically.
- Separate backup discipline: ClickHouse BACKUP and RESTORE cover local disk, S3-compatible and Azure Blob storage, and the documentation notes replication alone does not protect against human error or corruption.
- Access integration: External authenticators include LDAP, Kerberos, X.509 certificates, an HTTP authenticator and JWT, which can align with your existing identity controls.
- Upgrade cadence: Stable releases ship roughly monthly, and you should use a pre-production environment with representative data and read the changelog before each upgrade.
Confirm with your platform team whether the people who already run ClickHouse can take on Lago's event store, and ask Lago for the worker and Helm guidance that applies to your deployment.
Most teams decide by answering two questions: how many events your product generates and how quickly your reports must return, and who will run the second data system after launch. Neither answer comes from a published threshold in this page. You should measure your own event rate, retention period and query pattern over a representative period, then compare those figures against the capacity of a PostgreSQL deployment you have tested. If reports stay responsive and retention is manageable, PostgreSQL usually keeps the estate simpler. If reporting slows, or the business needs long-range analysis across large histories, the ClickHouse path becomes worth the added operations.
- Measure first: Record event ingestion rate, peak bursts, retention length and the most frequent billing and usage queries.
- Test a restore: Restore tests matter for either option, because a backup never test-restored will probably not restore properly when needed.
- Count the operators: Identify who patches, monitors and fails over each store, and whether that work sits with your existing teams.
- Plan the migration path: Ask Lago how events are stored and moved if you start on PostgreSQL and later enable ClickHouse.
- Budget for the second system: Hosting, Keeper nodes, storage and staff time recur, so get them priced in the written scope.
Before you choose, run your measured profile through a proof of concept and write down the operator and restore responsibilities for each option.
PostgreSQL and ClickHouse event storage side by side
This table compares the default PostgreSQL store with the optional ClickHouse event store for Lago, row by row across licensing, added components, replication, backup, upgrades, and authentication. Read each row as a question about your own deployment: the default store adds little to operate, while ClickHouse adds a second database with its own clustering, backup and upgrade routine. The main takeaway is that ClickHouse is an operational commitment you should only take on when event volume justifies it.
| Factor | PostgreSQL (default) | ClickHouse (optional) |
|---|---|---|
| Default status in Lago | Default store in the Docker Compose deployment, used for application data alongside Redis and Gotenberg | Optional external store for high-volume events, disabled by default in Lago's self-hosted setup |
| License | PostgreSQL License, a liberal license similar to BSD or MIT | Apache License 2.0 for the ClickHouse server; ClickHouse Inc. sells ClickHouse Cloud separately |
| Operational components added | No extra component beyond the PostgreSQL database Lago already requires | A separate ClickHouse deployment, and for replicated setups, ClickHouse Keeper nodes |
| Replication model | Hot standby servers with synchronous or asynchronous replication; failover needs external tools | ReplicatedMergeTree tables coordinated by ClickHouse Keeper; recovered replicas resync automatically |
| Keeper and node requirements | Not applicable | Documentation recommends at least three Keeper nodes on dedicated hosts in production, about 4 GB RAM each |
| Backup tooling | Continuous archiving and point-in-time recovery, plus standard dump and restore tools | BACKUP and RESTORE for tables, partitions or databases to local disk, S3-compatible or Azure Blob storage |
| Upgrade cadence and support | Major versions yearly; 18 supported to November 14, 2030, 14 to November 12, 2026 | Stable releases roughly monthly; LTS twice a year, supported one year; check the security policy for supported lines |
| Authentication options | Password, GSSAPI, SSPI, LDAP, RADIUS, certificate, PAM and OAuth | LDAP, Kerberos, SSL X.509, HTTP authenticator and JWT as external authenticators |
| What changes in the Lago deployment | Stays a single database service to back up, patch and monitor | Adds a second data service, worker sizing decisions, and a restore test routine on spare clusters |
What drives the operating cost of each store
Both stores carry recurring operating work, but the work differs. PostgreSQL costs come from high availability tooling, upgrades and staff familiarity, while ClickHouse adds a coordination layer, backups and restore tests on top of the same upgrade discipline.
ClickHouse Keeper nodes
Replicated ClickHouse tables are coordinated by ClickHouse Keeper, and the replication guide recommends at least three Keeper nodes on dedicated hosts in production, with about 4 GB of RAM each. Those hosts are a recurring infrastructure line that PostgreSQL does not need for event storage. Ask your team to price three dedicated hosts, their monitoring and their patching, and confirm whether your event volume requires replication at all.
Backup storage and restore tests
Replication does not protect against human error or corruption, so ClickHouse needs its own backup schedule using BACKUP and RESTORE to local disk, S3-compatible storage or Azure Blob Storage. The documentation warns that a backup never test-restored will probably not restore when needed, so restore tests on spare clusters are a recurring cost. Ask who owns backup storage capacity, retention and the restore drill, and whether the quote includes them.
Upgrade and changelog review effort
ClickHouse stable releases ship roughly monthly, and the production FAQ advises reading the changelog before upgrading because minor backward-incompatible changes can occur. Each upgrade needs a pre-production environment with representative data and queries. PostgreSQL minor releases do not change the storage format, so routine patching is lighter, though major upgrades still need planning. Ask the implementer to state how many upgrade cycles per year the quote covers.
PostgreSQL high availability tooling
PostgreSQL supports hot standbys and synchronous or asynchronous replication, but it does not detect a primary failure or promote a standby on its own. Automatic failover therefore needs external tooling, which you must select, deploy, test and maintain. This cost applies to the PostgreSQL store if you need automatic failover, and it is required whether or not ClickHouse is enabled for events. Confirm which failover tool your team will support before comparing quotes.
Staff skills and on-call coverage
Most platform teams already operate PostgreSQL, so its operating skills are often in place. ClickHouse adds Keeper, replica health, backup and restore procedures and its own upgrade cadence, which may need training or a retained specialist. Ask who on your side will hold these skills, how on-call covers a Keeper or replica incident, and whether the quote includes knowledge transfer and runbooks.
How scaling workers changes when ClickHouse is enabled
Enabling the optional ClickHouse store changes what the API worker and clock worker have to scale against, so the first decision is whether your event volume justifies a second store at all. In Lago's Docker Compose deployment, the API, the API worker, the clock worker, PostgreSQL, Redis and Gotenberg all run as separate services, and ClickHouse is disabled by default. Once events leave PostgreSQL, the API and worker tiers still write application data to PostgreSQL while event reads and aggregations move to ClickHouse, so you need to size both paths. Lago's self-hosting docs point larger deployments to Helm charts and dedicated workers, which is the practical route for separating job types, scaling the API worker independently of the clock worker, and keeping background jobs from competing with request handling. Confirm with Lago which worker queues and processes you should dedicate, and how the Helm chart maps them to your cluster, before you plan replica counts.
Connection management is the part teams most often underestimate. Every additional worker process opens its own connections to PostgreSQL, and that count grows with replicas. PgBouncer is a common option for pooling those connections, but whether it fits depends on your topology, including how Lago's Rails-based components manage transactions and prepared statements. Confirm with Lago and test under load in a pre-production environment before you put a pooler in front of the application database. Keep in mind that a pooler does not replace the database's own availability design.
PostgreSQL does not include software that detects a primary failure and promotes a standby. The PostgreSQL failover documentation says automatic failover needs external tools, so if your application data stays on PostgreSQL in a high-availability setup, you must choose, configure and test that tooling yourself. Read the PostgreSQL high availability documentation for how hot standbys and synchronous replication behave, then decide who owns failover runbooks. Those runbooks matter more once ClickHouse holds the event history, because a failover drill should cover both stores and the workers that depend on them.
Steps to enable the ClickHouse store safely
This sequence moves Lago's optional ClickHouse event store from a measured need to a production cutover, with a tested restore path at each stage. Each step ends with a check you can record before moving on.
Confirm the need with measured event volume
Your platform or data team measures the actual event ingestion rate, event retention period and the query load that the billing workers and reporting place on the current PostgreSQL store. Run this measurement over a representative period, including peak billing cycles, rather than from a single day's figures. Record the results alongside the PostgreSQL sizing you already run. The step is complete when you can show, in writing, that PostgreSQL is struggling on the measured workload and that tuning, indexing or worker scaling has been tried first. If the numbers do not show a gap, stay on PostgreSQL and document why.
Build a pre-production environment with representative data
Your platform team stands up a non-production Lago deployment with ClickHouse enabled and loads a copy or realistic sample of your event data, including the metering queries and invoice runs you depend on. Lago's Docker Compose deployment disables ClickHouse by default, so this environment is where you turn it on and confirm the configuration. The step closes when the same invoices and usage aggregates produced by PostgreSQL match the ClickHouse path for a defined test set. Ask the vendor or your integrator to confirm which Lago configuration keys control the external store in the version you run.
Pin the Lago version before any change
Your release owner selects the last tagged Lago release that you have validated, following Lago's self-hosting guidance to pin a tagged version rather than the latest image tag. Record the exact tag in your configuration repository and in the change record for the cutover. Read the release notes between your current version and the pinned version, including the releases published around the time you plan to deploy. The step is complete when the same tag is deployed to pre-production and production candidates, and no environment pulls a floating image tag.
Read the ClickHouse changelog and pin the server version
Your database owner chooses a ClickHouse release line for production, using the guidance that stable releases suit most production use and that LTS releases ship twice a year with one year of support. Check the ClickHouse security policy to confirm the chosen line is in the supported list at the time of deployment. Read the changelog for every version between your planned version and the latest release, because minor backward-incompatible changes can occur. Pin the exact server version in your deployment manifests. The step closes with a signed-off version record that names the support end date for the chosen line.
Deploy and verify Keeper nodes and replicas
Your platform engineers deploy ClickHouse Keeper, which replaces ZooKeeper for replication coordination, and the ReplicatedMergeTree replicas that hold event tables. The replication guide recommends at least three Keeper nodes on dedicated hosts in production, with about 4 GB of RAM each. Stop one replica during a test window and confirm that writes continue and that the recovered replica syncs missing data without manual steps. The step is complete when the failure test passes and the results are written into the runbook, including who responds to Keeper alerts.
Configure backups and run a restore test
Your database owner configures ClickHouse BACKUP jobs to a target your organization controls, such as local disk, S3-compatible storage or Azure Blob Storage, with full and incremental backups scheduled. Replication alone does not protect against human error or corruption, so the backup job is a separate control. Restore a backup to a spare cluster and compare row counts and sample invoice outputs with the source. The documentation warns that a backup never test-restored will probably not restore properly when needed, so schedule restore tests on a recurring basis. The step closes when a restore has been completed and the result is recorded.
Cut over with a rollback path
Your change lead schedules the cutover with the pinned Lago and ClickHouse versions, the verified replication and the tested restore in place. Define the rollback condition before the change, such as failed invoice reconciliation or sustained query errors, and keep PostgreSQL event data available until the ClickHouse path has run through a full billing cycle. Monitor worker queues and ClickHouse query latency during the first runs. The step is complete when reconciliation reports match the agreed test set and the rollback window has closed without a trigger.
Upgrades, backups and skills for each store
This table compares how each store is upgraded, backed up, monitored and staffed when Lago runs on PostgreSQL alone or with the optional ClickHouse event store. Read each row as a question to answer for your own team before choosing the store. The main takeaway is that the ClickHouse path adds a second database lifecycle with its own release lines, backup tooling and skills.
| Area | PostgreSQL (default store) | ClickHouse (optional event store) |
|---|---|---|
| Release lines | Major versions are supported for 5 years; 14 is supported until November 12, 2026, and 18 until November 14, 2030 | Stable releases ship roughly monthly; LTS releases ship twice a year and are supported for a year, and the security policy lists 26.9, 26.8, 26.7 and 26.3 as supported |
| Minor upgrades | Replace executables and restart; minor releases never change the internal storage format | Follow the changelog before each upgrade because minor backward-incompatible changes can occur; test on representative data first |
| Major upgrades | Use pg_dumpall and restore, pg_upgrade, or logical replication; logical replication works across major versions with several seconds of downtime | Plan version moves against the production FAQ guidance and a pre-production environment with representative data and queries |
| Backup tooling | Continuous archiving and point-in-time recovery are documented; confirm your archive target and retention with your team | BACKUP and RESTORE support full and incremental backups to local disk, S3-compatible storage or Azure Blob Storage |
| Replication versus backup | Hot standbys with synchronous or asynchronous replication; automatic failover needs external tools | ReplicatedMergeTree with ClickHouse Keeper (at least three nodes in production); replication does not protect against human error or corruption |
| Restore testing | Test restores on a spare cluster before relying on the archive | Documentation warns an untested backup will probably not restore properly; run regular restore tests on spare clusters |
| Monitoring needs | Watch replication lag, connection counts and storage growth; confirm connection pooling needs with PgBouncer | Watch Keeper health, replica sync status, merge backlog and disk use; confirm metrics with your deployment |
| Skills the team must hold | Routine PostgreSQL administration, upgrade procedures and failover design | ClickHouse table design, replication and Keeper operation, backup and restore, and upgrade planning, in addition to PostgreSQL skills |
Questions teams ask before enabling ClickHouse for Lago
Is PostgreSQL enough for our Lago usage event volume?
For many deployments, yes: Lago's Docker Compose deployment uses PostgreSQL for application data, and ClickHouse is an optional external store for high-volume events that stays disabled by default. The deciding factor is your event rate, retention window and how fast your billing queries must return, not a fixed threshold. Measure your expected peak events per second and total stored events in a pre-production environment with representative data before deciding. If that test shows PostgreSQL meeting your billing run and dashboard latency, the extra store adds cost without benefit. Confirm the sizing guidance for your release in the Lago self-hosting documentation.
How much effort and time does adding ClickHouse take?
The effort is the work of standing up a second stateful data store next to PostgreSQL, wiring Lago to it, and proving it under load. Cost drivers include the hosting footprint for ClickHouse nodes, the ClickHouse Keeper nodes that replicated setups need, storage for retained events, and the time to run a pre-production load test. ClickHouse's replication guide recommends at least three Keeper nodes on dedicated hosts in production, with about 4 GB of RAM each, so a highly available layout is a meaningful infrastructure addition. No DeployOpen timeline is stated here; a fixed-scope written agreement sets the schedule and deliverables for your environment.
What skills does a ClickHouse event store require from our team?
Your team needs working knowledge of three areas: operating PostgreSQL alongside Lago's Docker or Helm deployment, running ClickHouse clusters with ReplicatedMergeTree tables and ClickHouse Keeper, and designing backup and restore jobs. Engineers also need to read release notes, since the ClickHouse production guidance recommends reading the changelog before upgrades because minor backward-incompatible changes can occur. Platform and database skills are usually the gap, not Lago configuration itself. Ask your team to name the owner of each store before the project starts, so no event data depends on one person's knowledge.
Can our in-house team run ClickHouse for Lago without outside help?
It depends on whether you already operate stateful data platforms. A team that runs PostgreSQL high availability, monitors replication lag and rehearses restores can extend those habits to ClickHouse. A team without that experience should weigh the risk of an event store nobody can troubleshoot during a billing run. DeployOpen plans, implements, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms in your own infrastructure, and most engagements are fixed-scope with scope and deliverables agreed in writing before work starts. Ongoing support is available as a retainer.
What should a quote for a ClickHouse event store include?
A useful quote separates one-time work from recurring work. One-time items include architecture and sizing, the Lago configuration change, the ClickHouse and Keeper deployment, a pre-production load test with representative events, and the first backup and restore test. Recurring items include infrastructure for every node, retained storage, version upgrades, monitoring and support. Ask for the assumed event volume, retention period, number of replicas and the restore test scope in writing. DeployOpen does not publish a price list, so a quote follows from the written scope for your environment.
How do upgrades and version pinning change with ClickHouse enabled?
Enabling ClickHouse adds a second release stream to track. Lago's self-hosting docs recommend pinning the last tagged version rather than the latest image tag, and ClickHouse releases ship roughly monthly, with LTS lines twice a year. ClickHouse's security policy lists 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and all other versions as unsupported, so you must choose a supported line deliberately. Plan each upgrade in a pre-production environment with representative data, and confirm the compatibility of the Lago release with the ClickHouse version you pin.
How do backups and restore tests differ between PostgreSQL and ClickHouse?
Both need backups and restore tests, but the tooling differs. PostgreSQL offers continuous archiving and point-in-time recovery for application data, while ClickHouse BACKUP and RESTORE supports full and incremental backups of tables, partitions or databases to local disk, S3-compatible storage or Azure Blob Storage. ClickHouse's backup documentation notes that replication alone does not protect against human error or corruption, and warns that a backup never test-restored will probably not restore properly. Schedule restore tests on a spare cluster for both stores, and confirm that a restored event store matches Lago's billing results.
What to confirm with Lago and your own environment
The first thing to confirm is how the event store behaves in the exact Lago version you pin. The self-hosting docs recommend pinning the last tagged release rather than the latest image tag, and the ClickHouse store is optional and disabled by default, so the deployment you test must enable it explicitly. Read the release notes between your pinned tag and the version you plan to run, paying attention to anything that touches event ingestion, aggregation or the ClickHouse integration. Ask DeployOpen or Lago to confirm in writing which event-store paths the pinned version supports, and whether moving between stores requires data migration.
Next, confirm the ClickHouse release line you would run. The ClickHouse security policy lists 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and the production FAQ asks you to read the changelog before upgrading because minor backward-incompatible changes can occur. Choose between the stable line and an LTS line based on your own upgrade cadence, and check that the Lago version you pin is validated against it. Also confirm where ClickHouse Keeper would run, since the replication guide recommends at least three Keeper nodes on dedicated hosts in production.
Finally, measure your own event rate, retention period and recovery targets. This page does not supply volume thresholds or performance benchmarks, so there is no published number at which PostgreSQL stops being sufficient. Establish a realistic peak event rate from your own traffic, decide how long raw events must stay queryable, and define a recovery point and recovery time objective for billing data. Then run a load test in a pre-production environment with representative data, and restore a backup to a spare cluster, since the ClickHouse backup documentation warns that a backup never test-restored will probably not restore properly when needed.
How DeployOpen scopes and runs Lago event storage
DeployOpen plans, implements, hardens and documents self-hosted Lago inside your own cloud account, data center or air-gapped network. For the event store decision, we start from your volumes, query patterns and recovery expectations, then build and hand over whichever storage layout the written scope agrees on.
How we scope
- Written scope records which event store (PostgreSQL only or PostgreSQL with optional ClickHouse) the engagement covers and why.
- Scope lists the Lago services in the deployment: front end, API, API worker, clock worker, PostgreSQL, Redis and Gotenberg.
- Engagements are fixed-scope, so deliverables, environments and timelines for the storage work are agreed in writing before work starts.
How we build
- Deployment is pinned to a tagged Lago version chosen with you, not the latest image tag, with the upgrade path documented.
- Worker scaling, database connection handling and any ClickHouse replicas are configured in your environment and load-tested with representative events.
- Backup and restore for PostgreSQL and any ClickHouse tables is built and exercised on a spare environment before go-live.
How we hand over
- Handover includes runbooks for scaling workers, rotating credentials and changing the event store configuration.
- Documentation records the chosen storage design, its operating cost drivers and the restore test results your team can repeat.
- Your staff are walked through upgrade steps, including reading each release changelog before moving to a newer Lago version.
How we support
- Ongoing support, upgrades and recurring restore testing are available as a retainer after handover.
- Retainer scope can cover monitoring of event volumes, storage growth and database version support windows.
- Confirm response expectations, upgrade cadence and included testing in the written retainer before signing.
