How do I migrate Langfuse from ClickHouse OSS to Cloud or BYOC?
Traces, observations, and scores live in ClickHouse. Moving from self-managed ClickHouse (OSS) to ClickHouse Cloud or BYOC is a ClickHouse deployment-model change, not a Langfuse version upgrade. Run the latest Langfuse OSS release first so everything works as expected, then keep that version unchanged throughout. Leave Postgres, Redis, and blob storage in place so media and event payloads continue to resolve.
Do not use Langfuse blob storage exports as the restore path. Those exports are for analytics, not for recreating a ClickHouse database.
Recommended path
- Run the latest Langfuse OSS release. Upgrade first if you are not already current, then keep that version unchanged during the ClickHouse move. Provision the target Cloud or BYOC service and confirm it meets the ClickHouse version requirements for your Langfuse release.
- Pause ingestion. Scale down the Langfuse web and worker containers, or otherwise stop accepting traces, so no new rows are written during the copy.
- Copy the Langfuse ClickHouse database (schema and data) with a ClickHouse-supported method:
remoteSecure— pull or push tables directly. Typical for smaller or single-node sources.BACKUP/RESTOREvia object storage. Typical for clustered sources; Cloud restores convertReplicatedMergeTreetables toSharedMergeTree.
- Point Langfuse at the new service. Update
CLICKHOUSE_URL,CLICKHOUSE_MIGRATION_URL, credentials, and SSL using the Cloud/BYOC connection settings. Grant the required user permissions on the new service, and keep ClickHouse on UTC. - Resume ingestion and confirm historic traces, observations, and scores in the UI.
Upgrading Langfuse at the same time
Treat the ClickHouse move and a Langfuse major-version upgrade as separate steps.
Zero-downtime cutovers
A live dual-write cutover is theoretically possible but is not the recommended path and has not been validated for Langfuse. Plan for a pause of ingestion. Contact support if you need to discuss a custom approach.
Last edited
