Langfuse backup and restore: what your team must protect
If your team runs self-hosted Langfuse and an incident removes or corrupts data, what you can recover depends on the backups your own team has configured for each data store. The stores to protect are ClickHouse, which holds the trace, observation and score data; PostgreSQL, which holds transactional records such as users, organizations, projects and configuration; and S3-compatible blob storage, which holds raw event uploads and media. Redis or Valkey is part of the stack for caching and queueing. Treat it as cache-like and do not plan a backup target for it.
The self-hosted operator owns these backups. Langfuse does not run a backup service inside your deployment, and the Langfuse backup strategies guide, which this section draws on, describes options for each store rather than a single built-in procedure. Your team needs to decide who sets the schedules, how long backups are kept, where copies are stored, how they are encrypted, and who runs the restore tests. Those decisions should be written down before a go-live date, not after the first incident.
For ClickHouse, the Langfuse guide documents volume snapshots on Kubernetes, including the ZooKeeper volumes if your cluster uses them, along with Velero cluster backups and ClickHouse BACKUP and RESTORE to S3. Confirm which method your deployment uses and whether it captures every volume the cluster depends on. Also decide how ClickHouse and PostgreSQL backups will line up in time. A ClickHouse restore from one moment and a PostgreSQL restore from another can leave traces pointing at projects or keys that no longer exist.
For PostgreSQL, the guide recommends a managed database service. If you run PostgreSQL yourself, it shows pg_dump CronJobs or volume snapshots as options. Ask which mode gives the recovery point you need, how long a restore takes at your data volume, and whether dumps are tested in a separate environment. For blob storage, the guide says SeaweedFS or MinIO backups matter only when you are not using cloud object storage such as Amazon S3, Azure Blob Storage or Google Cloud Storage. If you run SeaweedFS or MinIO, it needs its own backup plan. If you use a cloud bucket, confirm with the provider which versioning, replication and retention settings apply.
Scheduled exports to blob storage are not a restore path for ClickHouse. The Langfuse ClickHouse migration FAQ warns that blob storage exports are intended for analytics. Write a restore runbook that names each store, its backup method, its owner and the order of restoration, then run a full restore into a separate environment on a fixed schedule. A backup that has never been restored is not yet evidence that your data can be recovered.
Backup options for each data store and when each fits
This table compares the backup options for each self-hosted Langfuse data store and the situations where each one fits. Read each row as a pairing of store and option, then check the trade-off before you choose. The main takeaway is that ClickHouse and PostgreSQL need backups you have restored and tested, while blob storage protection depends on whether you run cloud object storage.
| Store | Option | When it fits | Trade-off |
|---|---|---|---|
| ClickHouse | Volume snapshots, including ZooKeeper volumes on Kubernetes | Kubernetes deployments where your storage class supports snapshots and you want infrastructure-level copies | Consistency across volumes depends on your storage platform, so confirm it and test a restore |
| ClickHouse | BACKUP and RESTORE to S3 | Teams that want ClickHouse-native backups stored in object storage and restored into a cluster | Needs a bucket, credentials, a scheduled job and a restore runbook you have rehearsed |
| ClickHouse | Velero cluster backups | Kubernetes estates where Velero already protects namespaces and persistent volumes | Captures Kubernetes objects and volumes together, so ClickHouse restore steps still need testing |
| PostgreSQL | Managed database service backups | Cloud-hosted PostgreSQL where the provider offers automated backups and point-in-time recovery | Retention and restore scope depend on the provider, so confirm them in writing before go-live |
| PostgreSQL | pg_dump CronJobs | Smaller self-hosted instances where scheduled logical dumps are simple to run and restore | Logical dumps capture data only at the time of the dump and can restore slowly on large databases |
| PostgreSQL | Volume snapshots | Self-hosted PostgreSQL on Kubernetes or virtual machines with storage that supports snapshots | Snapshot consistency depends on your storage platform and database settings, so test restores |
| Blob storage | Cloud object storage native protection | Deployments on Amazon S3, Azure Blob Storage or Google Cloud Storage | Versioning and replication options vary by provider, so confirm the settings for the Langfuse bucket |
| Blob storage | SeaweedFS or MinIO backups | Self-hosted S3-compatible storage that is not a cloud object store | You back up the storage layer yourself, including buckets, metadata and access keys |
How to back up ClickHouse for Langfuse
The two routes that Langfuse documents for self-hosted ClickHouse are volume snapshots and ClickHouse BACKUP and RESTORE to S3. Volume snapshots are taken at the storage layer, usually through the Kubernetes VolumeSnapshot API, so they copy what the volumes hold without asking ClickHouse to produce a backup. The BACKUP command runs inside the database and writes a backup to an S3 target that RESTORE can read back. The guide also documents Velero cluster backups, which capture Kubernetes objects and volumes together. Choose between these by asking which route your platform team can operate, which one you can restore into a clean environment within the recovery window you have agreed, and where the copy will physically sit. Whichever route you choose, a backup you have never restored is not yet one you can rely on.
Kubernetes snapshots must include the ClickHouse ZooKeeper volumes, and Langfuse's guide calls this out explicitly. In a replicated ClickHouse setup, ZooKeeper holds coordination metadata for replicated tables, so the data volumes and the coordination state need to describe the same cluster at one moment. Restoring only the data volumes can leave a cluster that starts with metadata that no longer matches its parts. In practice, list every PersistentVolumeClaim in the ClickHouse namespace from your Helm release, confirm which ones belong to ZooKeeper, and snapshot the full set as one group. Ask the platform team whether the StorageClass supports VolumeSnapshot and whether the snapshot class keeps content after a snapshot object is deleted, because a deleted snapshot is a lost recovery point.
Several consistency questions depend on the exact ClickHouse version, so confirm them against that version's documentation before you rely on either route. Ask whether snapshots taken during active ingestion are crash-consistent, and whether ClickHouse must flush or pause writes first. For BACKUP, confirm which table engines and objects it covers in that version, whether the RESTORE syntax and settings match what you tested, and how it handles tables that are still receiving inserts. Langfuse's v4 upgrade guide requires ClickHouse 25.12 or later, so a version older than that may also block your next upgrade. Record the ClickHouse version, the backup timestamp and the Langfuse release together, because a restore only makes sense against a compatible combination of the three.
The backup target must be separate from the source cluster. A snapshot stored in the same cloud account, under the same credentials and in the same failure domain, can disappear together with the cluster it protects. For the S3 route, use a bucket in a separate account or, at minimum, separate credentials, enable versioning, and consider object lock if your policy requires immutable copies. Set the retention period from your recovery objectives, and check whether any default in the tooling meets them. Blob storage exports made for analytics are not a restore path for ClickHouse, and Langfuse warns against using them that way. Finally, schedule a restore into an isolated namespace or cluster on a regular basis and record how long it took, so the recovery plan rests on a tested result.
When SeaweedFS or MinIO blob storage needs its own backups
The Langfuse backup guide treats SeaweedFS or MinIO backups as relevant only when a deployment does not use cloud object storage such as Amazon S3, Azure Blob Storage or Google Cloud Storage. The cards below help you decide which case applies to your environment and what to confirm about the blob store and its backup target.
Cloud object storage deployments
If Langfuse writes blob data to Amazon S3, Azure Blob Storage or Google Cloud Storage, the Langfuse backup guide does not call for a separate SeaweedFS or MinIO backup. Your effort shifts to the ClickHouse and PostgreSQL backups and to the protection settings the provider offers on the bucket. Confirm which bucket and account Langfuse uses in your environment, and record which provider-side protections are in place before you finalize the backup plan.
Self-run SeaweedFS or MinIO
When the S3-compatible blob store runs in your own infrastructure, its contents become part of your recovery scope. Langfuse stores blob data outside its databases, so a restore of ClickHouse and PostgreSQL alone may not return the deployment to a complete state. Identify each bucket the deployment uses, estimate how its size will grow with your trace volume, and confirm whether a backup job or a replicated copy covers it. Ask your platform team to show that evidence before go-live.
Bucket versioning and replication
Object versioning and cross-site replication are the two bucket settings to confirm on a self-run store. Versioning keeps earlier object states when an object is overwritten or deleted, and replication copies objects to a second location. Ask the storage team whether each setting is enabled on the Langfuse buckets, how long old versions are kept, and whether a deletion on the primary also removes the replica. Treat either setting as a complement to a separate backup and verify it in a restore test.
Ownership of the backup target
Someone must own the destination where blob backups are written, including its credentials, retention period and restore runbook. Keep that destination outside the failure domain of the SeaweedFS or MinIO cluster it protects, so one outage or one misconfigured account cannot remove both the live data and its copy. Name the owner in the Langfuse backup plan, record who can read and delete backup objects, and confirm that this owner can run a restore without depending on the application team.
Why blob storage exports cannot restore ClickHouse
Langfuse's guidance is direct: blob storage exports are intended for analytics and should not be used as the restore path for a ClickHouse database. For a self-hosted deployment, this means a bucket full of exported files cannot stand in for the ClickHouse backup you schedule. Plan ClickHouse recovery around volume snapshots or ClickHouse BACKUP and RESTORE to S3, as described in Langfuse's backup guidance, and treat exports as a separate copy with its own purpose and owner.
An analytics copy exists to answer questions. Teams load it into a warehouse, query it with other tools, or keep it for long-term review. A restorable database backup has a different job: it must bring back the database itself, including its table structure, the data in a form ClickHouse can read, and the state that the running Langfuse Web and Worker containers depend on. Ask your team whether an export preserves enough schema and metadata to rebuild the tables in an empty ClickHouse instance, and whether anyone has ever run that rebuild end to end.
The difference becomes concrete during an incident. If ClickHouse is lost or corrupted, the question is how quickly observations can return to a consistent state that Langfuse can use. Restoring from exported files means recreating tables, reimporting data and reconciling the result with what PostgreSQL still holds. That work is not part of a planned restore procedure, and it is easy to underestimate under pressure. Set the recovery point and recovery time your organization needs before choosing a method, then test the chosen restore path in a non-production environment on a schedule.
Scheduled export is a separate capability. Langfuse can export observations and scores to object storage on a schedule for long-term retention or analysis. This section does not describe how to configure it; that is covered in the scheduled export topic. The point here is to keep the two jobs apart in your runbook: exports serve retention and analysis, and the ClickHouse backup job serves recovery. Before relying on either, confirm with the Langfuse documentation for your version which formats and ClickHouse versions are supported.
Set up and test Langfuse backups in order
This sequence takes each self-hosted Langfuse data store from an unknown backup state to a restore you have run and verified. Each step ends with a check, and the restore test into a separate environment is the proof that the backups work.
Inventory data stores and assign owners
List every stateful component in your Langfuse deployment: PostgreSQL, ClickHouse including its ZooKeeper volumes where present, S3-compatible blob storage, and Redis or Valkey. Confirm with your platform team which of these hold data you must keep, and name an owner for each store who approves its retention window and restore target. Done when you have a written inventory showing the owner and recovery expectation for each store, reviewed by the people who will sign off the restore test.
Choose a backup method for each store
Match one method to each store before configuring anything. For PostgreSQL, Langfuse recommends a managed database service where you can use one. For self-hosted instances, the Langfuse backup guide shows pg_dump CronJobs or volume snapshots. For ClickHouse on Kubernetes, the guide documents volume snapshots, including the ZooKeeper volumes, along with Velero cluster backups and ClickHouse BACKUP and RESTORE to S3. Check: a short decision record per store that names the method, the restore tool and the person who runs it.
Configure backup targets outside the source cluster
Create destinations for backup output in storage that sits apart from the cluster and cloud account holding live data, so a single failure or compromised credential cannot remove both. Give the backup jobs write access and a separate restore identity read access. Keep application pods away from delete rights on the targets. Confirm each target falls under the same region, encryption and retention rules that apply to the source. Check: a test write from each backup job succeeds, and a read from the restore identity succeeds.
Schedule PostgreSQL and ClickHouse backups
Enable the recurring jobs for each store using the method chosen earlier. For PostgreSQL, that means the managed service backup settings or a pg_dump CronJob with its database credentials kept in your secrets manager. For ClickHouse, schedule the snapshot or the BACKUP command to S3. Run each job once by hand before relying on the schedule, and configure alerts for failed runs. Check: each job completes, writes its output to the external target, and the alert fires during a deliberately failed test run.
Protect blob storage according to its role
Confirm which buckets your Langfuse deployment writes to and what each one holds, then assign each bucket to an owner. If you run SeaweedFS or MinIO because you use no cloud object storage such as Amazon S3, Azure Blob Storage or Google Cloud Storage, give that service its own backup job that follows the same external target rules. If you use cloud object storage, confirm the versioning or replication settings with your provider and record them. Blob exports are for analytics, so Langfuse warns against using them as the restore path for ClickHouse. Check: the bucket inventory and protection settings are recorded against each owner.
Restore into a separate environment
Restore the latest PostgreSQL and ClickHouse backups into an isolated environment, such as a separate namespace or cluster, so the restore cannot write back to production. Deploy the same Langfuse version as production, then start Langfuse Web and Langfuse Worker against the restored stores. Record the trace counts for a sample project and date range from production before the restore, so the restored figures have something to match. Check: both containers start and connect to the restored data stores without errors.
Verify application access and trace counts
Test the restored environment the way users and integrations reach it. Sign in through the same SSO path, open the known project, confirm that project API keys authenticate, and compare trace counts with the values recorded before the restore. Log the backup timestamp, the restore steps, any mismatches and the person who signed off. A restore test that passes is the proof of the backup, because a completed backup job alone only shows that a file was written. Repeat the test on a set schedule.
Securing backup copies of trace and prompt data
Backups of a self-hosted Langfuse instance hold the same traces and prompts as the live system, so they inherit the same privacy obligations. The cards below cover the places where backup copies sit outside the normal application boundary: storage targets, credentials, access paths, retention and the people who can reach them.
Treat backups as personal data stores
ClickHouse snapshots, BACKUP exports and PostgreSQL dumps can contain full trace inputs, outputs, user identifiers and prompt text, including anything your masking did not catch before ingestion. Classify backup targets with the same data category as production, and record which stores and buckets hold copies. Ask your privacy and legal teams to confirm this classification before the first backup job runs.
Encrypt backup targets at rest
Confirm how each backup destination encrypts data at rest: the S3 bucket or other object store, any intermediate volume snapshot, and any dump files written to a shared path. Decide who holds the encryption keys and whether they are separate from the keys protecting the live data stores. Verify the settings in your own cloud or data center account, because the encryption options depend on the storage product you choose.
Restrict access to backup buckets
Limit read, write and delete permissions on backup buckets to the backup job identity and a small restore group. Block public access, disable listing for principals that do not need it, and log object reads and deletions. Confirm that application service accounts used for Langfuse runtime cannot list or fetch backup objects, since a compromised web container should not be able to read historical traces.
Scope credentials used for S3 backups
The ClickHouse BACKUP and RESTORE path to S3 needs credentials with access to the backup prefix. Use a dedicated identity scoped to that prefix, prefer short-lived credentials where your platform supports them, and store the secret in your secrets manager instead of in a values file or CronJob manifest. Plan rotation and document which job uses which credential so a revoked key does not silently stop backups.
Align backup retention with deletion policies
Retention rules applied in Langfuse remove data from the live instance, but backup copies keep it until they expire. If a project's retention window is shorter than your backup retention, deleted traces can remain recoverable for longer than your policy states. Set backup retention deliberately, document the maximum period a deleted record can persist in backups, and confirm how a restore interacts with data that was deleted after the backup was taken.
Separate backup and application administrators
The people who run Langfuse upgrades and configuration should not also be the only people who can read, restore or delete backup copies. Assign backup administration to a separate role with its own approval path for restores, and log every restore into a non-production environment. Review this split during access reviews, and confirm that the same people are not holding both the backup and the production encryption keys.
Testing restores and running backups over time
Taking a backup is only the first step. Backup schedules, retention windows, alerting on failed jobs and periodic restore drills are operational duties that continue for as long as the Langfuse deployment runs, so they need a named owner before go-live. In most organizations that is the platform or database team, with the security or compliance lead approving retention periods. Write down the schedule for each data store separately, because ClickHouse, PostgreSQL and any self-managed blob storage will not share a timetable. Ask your infrastructure team to confirm which of these duties their existing backup tooling already covers and which must be added for Langfuse.
A restore drill is the only evidence that a backup can actually be used. Run one on a recurring basis, restoring into a separate environment rather than over the live deployment. A useful drill restores the ClickHouse data, the PostgreSQL metadata and any blob objects that the restored records reference, then starts Langfuse Web and Langfuse Worker against them. Confirm that the UI loads, that a known project's traces and prompts are present, and that new trace ingestion is processed by the worker. Stores captured at different times can disagree, so check that restored PostgreSQL records and ClickHouse observations line up. Record how long the restore took and compare that figure with the recovery time your organization has agreed to.
Failed backup jobs are silent unless someone is alerted to them. Route failures from every backup job into the monitoring system your on-call team already watches, whether that is a failed pg_dump CronJob, a volume snapshot that never reached a ready state, or a ClickHouse BACKUP command that returned an error. Set retention on each destination according to the decisions made for project data, and apply lifecycle rules to any S3 bucket that receives ClickHouse backups so old copies are removed on a known schedule. Backup retention is a separate decision from the in-application data retention policy, which requires an Enterprise license key. Confirm backup retention periods with legal and security before you set them.
Major upgrades are the moment when a fresh backup matters most. Moving from v3 to v4 changes the ClickHouse data model to an observations-first design, so a backup taken immediately before the upgrade is the clean rollback point if the migration fails partway. Take a new backup of every data store just before you start, separate from the scheduled runs, and confirm restore compatibility with the Langfuse v3 to v4 migration guide first. The guide requires ClickHouse 25.12 or later (26.4 is recommended), PostgreSQL 15 or later and Redis 7.0 or later. If you run the Helm chart with bundled data stores, the chart must be upgraded from v1 to v2 before Langfuse moves to v4. Check each restore against both the source versions and the target versions.
Plan disk space for the upgrade as well as for the backup. The v3 to v4 guide advises about 3x ClickHouse disk headroom when backfilling historic data, so a backup that fits on disk today may leave no room for the migration itself. Keep backup copies off the ClickHouse volume being migrated. Before production, rehearse the upgrade by restoring the fresh backup into a staging environment at the target versions, running the migration there, timing it and checking that traces and prompts remain readable afterward. Minor updates within a major version also apply database migrations at startup, so take a backup before those as well.
Langfuse backup questions buyers ask before hiring help
What does Langfuse backup and restore work cost, and what drives it?
Cost depends on the written scope, which DeployOpen agrees before work starts. The main drivers are the number of data stores in scope (ClickHouse, PostgreSQL, and any self-run blob storage), whether storage is cloud object storage or self-run SeaweedFS or MinIO, whether ClickHouse runs on Kubernetes with volume snapshots or on another platform, whether PostgreSQL is managed or self-run, and how far restore testing goes. Setup work is one-time. Scheduled backup jobs, monitoring and repeated restore drills recur, so ask the quote to separate those lines. DeployOpen does not publish a price list. Ask for a quote that itemizes each data store, the restore test scope and any ongoing support or drill cadence.
How long does a Langfuse backup setup take to complete?
Duration follows from the scope, so confirm the timeline in the written proposal rather than relying on a general estimate. The factors that set it are the number of data stores, whether ClickHouse snapshots need ZooKeeper volumes included, whether cluster-level tooling such as Velero is part of the design, how quickly your cloud accounts, backup buckets and cluster access are approved, and whether a full restore drill is in scope. Access delays on the client side often extend the schedule more than the technical work does. Ask for the dependencies and client milestones listed as separate items in the proposal so you can see which ones your team controls.
What does DeployOpen need from our team to back up Langfuse?
The work needs four things from your side. First, access to the Kubernetes clusters or hosts running ClickHouse, PostgreSQL and Langfuse, with the permissions needed to create snapshots, CronJobs and backup configuration. Second, access to the cloud accounts that hold snapshots and object storage, plus the backup targets themselves, such as S3 buckets and their retention and encryption settings. Third, a named owner who can approve design decisions, schedule maintenance windows for restore tests and accept the results. Fourth, a place to run a test restore that is separate from production. Confirm each of these with your team before the scope is signed.
Can our own team set up Langfuse backups without a partner?
Yes. The Langfuse backup guide documents the methods your team would use: volume snapshots for self-hosted ClickHouse on Kubernetes, including ZooKeeper volumes, ClickHouse BACKUP and RESTORE to S3, Velero for cluster backups, and pg_dump CronJobs or volume snapshots for self-hosted PostgreSQL. For PostgreSQL, Langfuse recommends a managed database service where possible. The part teams most often skip is the restore drill. A backup that has never been restored into a separate environment has not been proven, so your team should plan that test, record the results and repeat it after changes to the platform.
Is the Langfuse Enterprise license required for backups?
Confirm this with Langfuse before you buy. The Langfuse license key documentation lists the self-hosted features that require an Enterprise license key: project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking, UI customization, organization creators, the org management API with SCIM, and the instance management API. Backups are not on that list in the information available for this page, so the backup methods described in the Langfuse backup guide do not depend on that key as far as the documentation shows. The core Langfuse codebase is MIT licensed, and the enterprise directories fall under a separate license. Ask your Langfuse contact to confirm the position in writing for your version.
Can Langfuse blob storage exports serve as a restore path?
No. Langfuse warns that blob storage exports are for analytics and should not be used as the restore path for a ClickHouse database. An export is a copy of data in a format meant for analysis, so it does not reproduce the database state, schema and migration history that a restore needs. The restore path for ClickHouse is a volume snapshot or a BACKUP and RESTORE to S3, tested in a separate environment. Exports can still be part of your retention and analytics plan, but they should sit alongside the database backup, not replace it. Document this distinction in your runbook so responders do not reach for the export during an incident.
Do SeaweedFS or MinIO blob stores need their own backups?
Only when your deployment does not use cloud object storage. The Langfuse backup guide says SeaweedFS or MinIO backups matter for deployments that are not using services such as Amazon S3, Azure Blob Storage or Google Cloud Storage. If you run SeaweedFS or MinIO yourself, plan a backup for its data, its volumes and its configuration, and test a restore of it along with ClickHouse and PostgreSQL. If you use a cloud object store, confirm with your provider which durability, versioning and replication settings apply to your buckets, and document who can change them. Either way, ask the quote to state which blob storage option it assumes.
What should a Langfuse restore drill check before we trust it?
A restore drill should prove that the backups can rebuild a working Langfuse instance in an isolated environment. Restore ClickHouse and PostgreSQL from the backup set, start Langfuse Web and Langfuse Worker against them, and confirm that the application starts and reads its data. Check that trace and observation counts in ClickHouse match the expected range for the backup point, that projects, users and prompts in PostgreSQL are present, and that blob references resolve if you store media or large payloads there. Record the time each step took, the backup version used and any manual steps. Repeat the drill after major changes and before major upgrades.
How DeployOpen scopes and delivers Langfuse backup and restore
DeployOpen plans and builds backup and restore for each self-hosted Langfuse data store inside your own infrastructure, from ClickHouse and PostgreSQL to any SeaweedFS or MinIO blob storage you run. Engagements are fixed-scope, so backup targets, schedules, restore steps and evidence are agreed in writing before work starts. Restores are tested before handover, and the handover includes a runbook your team can follow.
How we scope
- Inventory every Langfuse data store, including ClickHouse, PostgreSQL and any self-managed blob storage.
- Confirm whether blob storage is cloud object storage, which determines whether SeaweedFS or MinIO backups apply.
- Agree recovery objectives, retention, backup locations and restore test scope in the written scope before work starts.
How we build
- Configure ClickHouse backups with volume snapshots or BACKUP and RESTORE to S3, including ZooKeeper volumes on Kubernetes.
- Set up PostgreSQL dumps on a schedule with pg_dump CronJobs or volume snapshots, or confirm a managed service's backups.
- Where needed, add SeaweedFS or MinIO backups and keep backup credentials and encryption keys inside your infrastructure.
How we hand over
- Test a full restore of each data store into an isolated environment and record what it took.
- Document the backup schedules, restore runbook and ownership of each data store in a handover your team can run.
- Explain that blob storage exports are for analytics and are not a restore path for ClickHouse data.
How we support
- Ongoing backup monitoring, restore tests and upgrade-related checks are available as a retainer.
- Revisit backup scope when you upgrade Langfuse across major versions, since data model changes affect ClickHouse.
- Support restore rehearsals after infrastructure changes, such as new storage classes or a changed cluster layout.
