Why a Langfuse v2 to v3 upgrade changes the architecture
Moving a Postgres-only Langfuse v2 deployment to v3 adds a worker container, ClickHouse, Redis or Valkey, and S3-compatible blob storage to the stack. That makes the move an infrastructure project with a data migration inside it, and it needs a planned parallel rollout in which the new components run beside the existing v2 instance until traffic has moved. Teams that treat it as a container image change usually find the gap when the new containers start without the stores they depend on. In v2, Postgres holds nearly all application data. In v3, trace, observation and score data move into ClickHouse, while queues and caching move to Redis or Valkey, so each store needs its own capacity, backup and access plan before any cutover date is set.
The supported path begins with a Langfuse version later than v2.92.0. The upgrade guide reports that the move works well between v2.92.0 and v3.29.0, so v3.29.0 is the release to run for parallel operation before you move to the latest v3. Confirm the exact version your deployment is running today, since that determines the first step. Take a PostgreSQL backup before you change anything on the running v2 instance, and verify that the backup can be restored in a test environment. Keep the old stack available until the new one has carried production traffic for a period your operations team has agreed on in advance.
Major upgrades follow dedicated migration guides, and this path is covered by the Langfuse v2 to v3 guide. Minor updates within a major version are non-disruptive, and database migrations apply automatically at startup. That behavior is why a v2 to v3 step cannot be handled like a routine patch. The v3 architecture also runs four background migrations in sequence: cost backfill, then traces, observations and scores from Postgres to ClickHouse. These may take multiple hours depending on table size. For zero downtime, the guide recommends provisioning new web and worker containers with LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false until traffic is shifted. Ask your team to measure table sizes early so the migration window can be scheduled with evidence.
Several decisions belong in the plan before any container starts. Choose who owns ClickHouse, Redis or Valkey, and blob storage, and document how each is backed up and restored. Confirm which SDK versions your applications use, because the v3 server does not support SDK v1.x.x, and the Python and JavaScript SDK v2 releases date from December 2023. Size ClickHouse against the scaling guide's minimums of 2 CPU and 8 GiB, and plan for at least 16 GiB of memory for larger deployments. Ask for these items to appear as explicit deliverables in any written scope, with acceptance criteria for the parallel period and the cutover.
What changes between v2 and v3, and what each change means for your team
This table compares each change from the Postgres-only Langfuse v2 architecture to v3, its impact on your infrastructure and applications, and the action it requires. Read it as a checklist, and assign an owner to each row before building the parallel environment. The main takeaway is that v3 adds services, storage and background data work to the upgrade, so infrastructure and SDK tasks should be finished before the cutover window is scheduled.
| Change | Impact | Action needed |
|---|---|---|
| Langfuse worker container | A second application container processes asynchronous events alongside Langfuse Web, so there is another workload to deploy, scale and monitor. | Deploy a worker for each new web environment, set its configuration to match, and scale it on CPU load. |
| Blob storage | An S3-compatible blob store becomes a required dependency that v3 uses alongside the database. | Provision the bucket and access credentials, then add it to your backup and access review scope. |
| ClickHouse for traces, observations and scores | Trace, observation and score data moves to ClickHouse, a new stateful system with its own sizing, backups and retention. | Provision ClickHouse using the scaling guide's minimums as a starting point, and plan its backup and retention policy. |
| Redis or Valkey for queues and caching | Queues and caching move to Redis or Valkey, so an outage there affects background processing. | Provision Redis or Valkey, confirm the supported version in the v3 guide, and set its monitoring and availability plan. |
| SDK v2 or later required | Server v3 does not support SDK v1.x.x, so applications pinned to v1 will not work after cutover. | Inventory every Python and JavaScript SDK pin, upgrade to SDK v2 or later, and test each application in staging. |
| Four background migrations | Cost backfill runs first, then traces, observations and scores move from Postgres to ClickHouse, which can take several hours depending on table size. | Measure source table sizes, schedule a maintenance window, and monitor migration progress before cutover. |
| Version path from v2 | The guide recommends a version later than v2.92.0 and reports the upgrade works well from v2.92.0 to v3.29.0. | Back up Postgres, upgrade to a v2 release later than v2.92.0, and use v3.29.0 for parallel operation before moving to the latest v3. |
What to prepare before you touch the v2 deployment
Five preparation items decide whether a Langfuse v2 to v3 upgrade can be rolled back and whether the data migration follows a known path. Each card covers one item you can verify in your own environment before the parallel deployment starts. Work through them in order, because the backup and the inventory set the scope for the test environment and the sizing.
Verified Postgres backup and restore
Take a Postgres backup of the v2 database and restore it into a separate instance before any upgrade step. The v2 to v3 guide recommends a Postgres backup as the starting point. A backup that has never been restored is an assumption, so confirm that the restored copy starts, the Langfuse data is readable, and your team knows how long the restore takes in your environment. This copy is also your rollback point if the migration fails, because the v3 background migrations move data out of Postgres into ClickHouse.
Inventory of SDK versions
List every application, notebook and service that sends traces, with the SDK package and version each one uses. Langfuse v3 does not support SDK v1.x.x, and the Python SDK v2 and JavaScript SDK v2 were released in December 2023, so any v1 client must be upgraded before or alongside the server change. Record which services send traces through OpenTelemetry instead, since they follow a different path. Confirm an owner, a deployment schedule and whether each client can be changed without a full code release.
Custom integrations and evaluators
Identify every integration that reads from or writes to Langfuse, including scripts that call the public API, exports, dashboards built on direct database queries, evaluators and webhooks. Direct SQL against the Postgres schema is a likely break point, because v3 stores traces, observations and scores in ClickHouse. Test each integration against a v3 staging instance and confirm which team owns each fix. Note any dependency on API behavior you have not tested, since those calls need explicit verification before cutover.
Sizing ClickHouse, Redis or Valkey and blob storage
Size the new v3 components before the migration starts, using the minimum resources in Langfuse's scaling guide as the floor: 2 CPU and 8 GiB for ClickHouse, 1 CPU and 1.5 GiB for Redis or Valkey, and 2 CPU and 4 GiB each for web, worker and PostgreSQL. The guide notes at least 16 GiB of ClickHouse memory for larger deployments. Confirm disk capacity for the migrated history and a blob bucket reachable from both web and worker containers. These minimums set a floor and do not size your ingestion volume.
Test environment that mirrors ingestion
Build a staging stack on the v3 architecture and replay production-like ingestion into it before any change to production. Match trace volume, SDK mix, project count and table sizes first, since the background migrations run for longer on larger tables. The v2 to v3 guide notes that the four background migrations may take multiple hours depending on table size. Use the staging run to time the migration, watch worker CPU and confirm that LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false keeps the new containers from migrating while traffic still runs on v2.
How the parallel rollout keeps v2 serving users until cutover
The parallel rollout keeps Langfuse v2 answering users while a complete v3 stack is built beside it. You provision new langfuse-web and langfuse-worker containers for v3 and set LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false on them, so the containers start without running the four background migrations that copy cost data, traces, observations and scores from PostgreSQL into ClickHouse. The new containers then point at their own PostgreSQL, ClickHouse, Redis or Valkey, and S3-compatible blob storage, leaving the v2 data path untouched. Users move to v3 only after the new stack passes the checks you have defined. Langfuse's guidance points to v3.29.0 for this parallel phase, because the path from v2.92.0 to v3.29.0 is the one documented as working well, with a move to the latest v3 afterward.
The v2 path stays in place so that rollback is fast and predictable. Until cutover, the existing v2 web, worker and PostgreSQL remain running and reachable, so returning users to v2 is a routing change and nothing more. Decide before the window opens what triggers rollback, who makes that call, and how long v2 stays warm. Also decide how to handle traces ingested into v3 during the parallel period, because the v2 PostgreSQL database will not contain them. Confirm in Langfuse's upgrade guide how v2 and v3 data relate during this window, and test the rollback route in staging before you rely on it in production.
Web and worker scale separately because they carry different loads. langfuse-web serves the UI and APIs, while langfuse-worker processes events asynchronously after ingestion. Langfuse recommends scaling worker containers on CPU load, which lets you add processing capacity during a burst of SDK traffic without adding web replicas that users hit directly. Start the parallel stack at or above the documented minimums of 2 CPU and 4 GiB for each web and worker container, then measure under production-like ingestion before you set replica counts for cutover. Ask your platform team to record CPU per worker and request latency per web replica during the parallel run.
Splitting langfuse-web into separate ingestion and user interface deployments matters when heavy ingestion competes with people using the dashboards. Under that load, a burst of trace uploads can consume the web capacity that analysts need for trace search and prompt management, so the UI slows even while the workers keep up. Langfuse recommends the split in this situation, so make the decision from measured data before cutover. Watch ingestion request volume and dashboard response times during the parallel run. If both rise together at peak times, plan the two deployments and their separate ingress routes before cutover, because changing routing inside the cutover window adds risk to the change itself.
Shift traffic only after the checks pass, and keep those checks specific. Confirm that the v3 web containers answer health checks, that a test user can sign in through your identity provider, that an SDK test trace is accepted, stored and visible in the UI, and that worker queues drain. Confirm also that the background migrations you run after cutover finish, since they run in sequence and can take multiple hours depending on table size. Record each check with a named owner and a pass condition agreed in advance, so the cutover decision rests on shared evidence and not on whoever is most confident.
The upgrade sequence, with checks and rollback points at each stage
The sequence runs a verified Postgres backup, a version check, and a parallel v3.29.0 stack that takes traffic only after smoke tests pass, then moves background data migrations and the latest v3 release forward with a rollback option at each stage.
Take and verify a Postgres backup
Your database team takes a full Postgres backup of the v2 database before any other change. They restore it into a separate test instance and confirm that the restored database starts and holds the expected trace, prompt and user records. This backup is the first rollback point and stays available until the upgrade is complete. Keep the v2 web and worker containers running and unchanged. The step is done when the restore test passes and the team has recorded the backup method, location and restore time. Confirm the backup tooling and retention rules with your own database operators, since they depend on your environment.
Confirm the source version is later than v2.92.0
Your platform owner checks the running Langfuse version against the v2 to v3 guide, which recommends starting from a version later than v2.92.0. If the deployment is older, upgrade within v2 first and repeat the backup check afterward. Record the exact image tags and configuration values, including database connection settings and environment variables, so you can reproduce the v2 stack if needed. The step is complete when the version is confirmed in writing and the configuration snapshot is stored with the backup. This check costs nothing to run, and it stops the upgrade before any infrastructure changes.
Deploy the v3.29.0 parallel stack
Your platform team deploys a new Langfuse Web and Langfuse Worker pair at v3.29.0 beside the existing v2 stack, pointed at the same Postgres database. Set LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false on both new containers so that no data moves until you choose to start it. The v2 stack keeps serving users during this stage. The step is done when both v3 containers start, pass their health checks, and show no migration activity in their logs. If the new containers fail, stop them and the v2 stack continues unaffected, which is the rollback point for this stage.
Connect ClickHouse, Redis or Valkey and blob storage
Connect the v3 containers to ClickHouse for traces, observations and scores, to Redis or Valkey for queues and caching, and to S3-compatible blob storage for event uploads. Your infrastructure team sizes and secures each service in the environment you control, using the resource minimums in the scaling guide as a starting point. Confirm network paths, credentials and TLS settings for each connection. The step closes when each service reports a healthy connection from the v3 containers and a test write and read succeeds in each one. If a connection fails, correct it while v2 keeps running.
Run smoke tests on ingestion and the UI
Your QA or platform engineers run a scripted set of tests against the v3 stack before any user reaches it. Send test traces through the public API and, if you use it, the OpenTelemetry endpoint, then confirm they appear in the UI with correct timestamps and metadata. Log in through the UI, open a trace, create and read a prompt, and check that scores can be written. Compare results with the same tests run against v2. The step is done when every test passes and the results are saved. Any failure stops the process, and traffic stays on v2.
Shift traffic to the v3 stack
Move user and SDK traffic to the v3 web endpoint using your load balancer or DNS, in a controlled change window agreed with application owners. Watch error rates, latency and ingestion counts for the first period after the change, and keep the v2 stack ready to receive traffic again. Applications that send traces should be checked against v3 ingestion, since SDK versions must be compatible with the server. The step is done when v3 handles all production traffic without errors that exceed the baseline you recorded. Returning traffic to v2 is the rollback point, and it works only while the v2 stack and the backup remain intact.
Enable and monitor background migrations
Once v3 is serving traffic, set LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS to enabled on the v3 containers. Langfuse v3 runs four migrations in sequence: the cost backfill, then traces, observations and scores from Postgres into ClickHouse. These may take multiple hours depending on table size, so plan the monitoring window with that in mind and ask Langfuse which migration step is running and how long each one has taken in your environment. Watch ClickHouse disk, memory, CPU and Postgres load. The step is complete when all four migrations report finished in the logs. Disabling the flag again pauses further migration work.
Verify migrated data and move to latest v3
Compare record counts and sample traces between Postgres and ClickHouse for each migrated table, and confirm that recent and historic traces open correctly in the UI. Check that prompts, scores and user data match the v2 backup. Record the results and sign them off with the data owner. After verification, update the v3 containers to the latest v3 release by following the upgrade guidance for minor versions, which Langfuse describes as non-disruptive and automatic for database migrations. The step is done when the data check is signed off and the latest v3 is serving traffic. Retain the backup and the v2 stack until the sign-off is recorded.
How the background migrations move history and how to plan for their runtime
The four background migrations copy existing history from PostgreSQL into the v3 data stores, and the history is not fully available in the new architecture until they finish. They run in sequence: the cost backfill first, then traces, observations and scores moved from PostgreSQL to ClickHouse. Langfuse documents that they may take multiple hours depending on table size. Treat the run as a scheduled activity with its own owner and check-in times, not as a step that completes inside a change window. Before the window opens, get row counts for the source tables so you can judge how large the run will be.
During the run, watch three signals. First, worker load: Langfuse recommends scaling worker containers on CPU load, so sustained worker saturation is the first sign to add replicas. Second, ClickHouse disk and memory: the Langfuse scaling guide lists 2 CPU and 8 GiB as minimums for ClickHouse and at least 16 GiB of memory for larger deployments. Compare disk growth against the free space you reserved, and watch for memory-driven restarts. Third, errors in the worker logs. A migration that repeats the same failure is stalled, not slow, and it should trigger investigation rather than waiting.
Decide to pause or resume based on those signals, and write the criteria into the runbook before the run starts. Pause if ClickHouse disk trends toward its limit, if memory pressure causes restarts, or if the same worker error repeats. Resume only after you have added space or capacity and confirmed the cause. Confirm in the Langfuse upgrade guide how an interrupted migration restarts, whether it resumes or re-processes a table, and whether partial history is queryable during the run. During parallel operation, LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false keeps migrations off on the new containers while traffic shifts, so name explicitly which containers are allowed to run them.
These migrations are the v3 side of the data path, and the sibling v3 to v4 upgrade depends on their completion. That guide moves the data model to observations first and advises about 3x ClickHouse disk headroom when backfilling historic data, so size storage for both the v3 migration and any later v4 backfill. Do not start the v4 upgrade while any v3 migration is incomplete or erroring. Record start time, row progress per table, disk and memory readings, and sign-off criteria in one place, so the team that cuts over can confirm that history is complete before traffic depends on it.
Testing and rollback checkpoints before you shift production traffic
Move production traffic only after each test below passes on a v3 staging instance that mirrors your production configuration. The cards run from SDK and ingestion checks through data reconciliation and load, then to the rollback path and the decision that opens it.
SDK compatibility against v3 staging
Point a staging copy of the v3 stack at the same SDK versions your applications run in production. Langfuse v3 does not support SDK v1.x.x, and the Python SDK v2 and JavaScript SDK v2 were released in December 2023, so confirm the exact versions in every service. Check that trace creation, nested observations, score writes and prompt fetches all succeed against the staging web and worker containers before any production application is repointed.
Ingestion tests from each instrumented application
Run each instrumented application against staging and confirm its traces appear in the v3 UI with the expected structure, metadata and user or session identifiers. Include applications that send OpenTelemetry data to the /api/public/otel endpoint, since their attribute mapping can differ from native SDK output. Record which application, SDK version and endpoint each test used so that any failure can be traced to one integration.
Trace and score count reconciliation
After the four background migrations finish, compare trace and score counts for the same time windows in the v2 Postgres database and the v3 ClickHouse tables. Migration duration depends on table size and may run for hours, so schedule this check after the migrations complete rather than during them. Investigate any gap by time range and project before accepting the migrated history, and keep the reconciliation queries in the change record.
Performance under representative load
Replay ingestion volume and query patterns that resemble your busiest production day against the staging deployment, sized with the minimum resources in Langfuse's scaling guide as a floor. Watch worker CPU, ClickHouse memory and query latency in the UI and API. If ingestion saturates the web container, Langfuse recommends separate ingestion and user interface deployments, so record whether that split is needed before cutover.
Rollback plan with the v2 stack retained
Keep the v2 web and worker deployment, its Postgres database and the verified Postgres backup available until your reviewers accept the v3 results. Write down the traffic switch that returns applications to v2, the owner who runs it and the longest acceptable time to do so. Rehearse the rollback on staging so that the team knows which DNS, load balancer or SDK configuration changes are involved.
Go or no-go decision and sign-off
Define go criteria before testing starts: every SDK and application ingestion test passes, reconciled counts match or have documented explanations, load results meet the targets you set, and the rollback has been rehearsed. Any unresolved failure is a no-go. Name the platform owner who makes the call, and add sign-off from the application owners and the data owner, since they carry the consequences of missing or duplicated traces.
What makes a v2 to v3 upgrade longer or more expensive
This table lists the factors that change how much work a Langfuse v2 to v3 upgrade takes, with the reason each one matters and the step that keeps it under control. Read each row against your own deployment to see which drivers apply to you. The main takeaway is that data volume and infrastructure shape are usually the largest unknowns, so measure them before you agree on a scope.
| Driver | Why it matters | How to reduce it |
|---|---|---|
| Historic data volume in Postgres | The v3 background migrations copy traces, observations, scores and costs from Postgres into ClickHouse, so runtime grows with the size of those tables. Langfuse notes the migrations may take multiple hours depending on table size. | Measure row counts and table sizes for each entity before planning. Agree a maintenance window or parallel run sized to those figures, and confirm disk headroom in ClickHouse with Langfuse's upgrade guidance. |
| Number and age of SDK integrations | Langfuse v3 does not support SDK v1.x.x, and Python SDK v2 and JavaScript SDK v2 date from December 2023. Every application that still uses an older SDK needs code changes and testing before cutover. | Inventory every service that sends traces, record its SDK name and version, and group applications by owner. Upgrade SDKs in a staging environment first and confirm trace output matches before production. |
| Custom evaluators and integrations | Evaluators, scripts, dashboards and exports that read from the v2 API or database may depend on the Postgres schema or on behavior that changes in v3. Each one needs to be found, rewritten or re-tested. | List all jobs and tools that call the Langfuse API or query the database directly. Mark which ones read trace data, which write scores, and which depend on the old schema, then test each against a v3 instance. |
| Current infrastructure shape | A Docker Compose deployment on a single VM is a testing layout without high availability, while Kubernetes deployments and bundled data stores each need separate plans. v3 adds a worker, ClickHouse, Redis or Valkey and blob storage, so the new components must be provisioned alongside the old ones. | Document how v2 is deployed, which data stores are bundled and which are external, and whether backups exist for each. Confirm the target layout for ClickHouse, Redis or Valkey and S3-compatible storage before choosing the parallel approach. |
| Number of environments to test | Each environment, including development, staging and production, needs its own v3 stack, data copy and test run. Differences between environments are a common cause of rework. | Keep environments as close to each other as possible in configuration and versions. Test the migration first on a recent copy of production data, then reuse the same runbook in each later environment. |
| Security and access controls to carry over | Single sign-on settings, password sign-in rules, roles, API keys and network restrictions must work the same way in v3. Some governance features, such as project-level RBAC, need an Enterprise license key, so access rules may have to be redesigned if that key is not in place. | Export the current access model and SSO configuration, map each role and login rule to its v3 equivalent, and confirm which features need an Enterprise license key before go-live. Test sign-in for each identity provider in staging. |
| Backup and rollback readiness | Langfuse recommends a Postgres backup before the upgrade. Without a tested restore and a defined rollback path, a failed migration can extend the outage window. | Take and verify a Postgres backup, document how to restore it, and agree the criteria for rolling back to v2 before the upgrade starts. |
Questions buyers ask before they hire help with a Langfuse v2 to v3 upgrade
What drives the cost of a Langfuse v2 to v3 upgrade?
The main drivers are the size of your existing Postgres data, the amount of new infrastructure you must build, and the number of environments that need the change. A Postgres-only v2 deployment must add ClickHouse, Redis or Valkey, S3-compatible blob storage and a worker container, so the infrastructure work is often larger than the application change. Cost also rises with the number of SDK integrations that need updating, the rehearsals you require, and the monitoring and rollback planning you ask for. A fixed-scope quote from DeployOpen covers the agreed environments, deliverables and timeline, written before work starts. Ask every bidder to itemize infrastructure, rehearsals, migration support, cutover, handover and the parts you provide, so the quotes can be compared on the same basis.
How long does a Langfuse v2 to v3 upgrade take?
The duration depends mainly on the size of your trace, observation and score tables in Postgres. Langfuse v3 runs four background migrations in sequence: a cost backfill, then traces, observations and scores moving from Postgres to ClickHouse. The official documentation says these may take multiple hours depending on table size. Background migrations dominate the runtime because they process historic rows, while the application changes are usually short. Parallel operation adds time as well, since new containers run alongside v2 until traffic moves. Measure your own migration time with a rehearsal on a copy of production data, and ask for a schedule that separates infrastructure build, rehearsal, migration, traffic shift and post-cutover checks.
What does the upgrade need from our own team?
The work needs access, a verified Postgres backup, SDK owners and a named approver. Access covers the hosts or Kubernetes cluster, cloud accounts, the Postgres database and the secrets store where Langfuse configuration lives. The official guide recommends a Postgres backup before you start, and you should confirm that the backup restores. You also need your current version to be later than v2.92.0, which the guide recommends before the move. SDK owners must be able to update and redeploy each application that sends traces. Finally, a named person must approve rehearsal results and the cutover window, and someone must watch dashboards and error rates after the switch.
Can our internal team run the upgrade without outside help?
A team with Kubernetes or Docker, Postgres and ClickHouse experience can follow the official migration guide without a partner. The risks sit in three areas. The first is operating ClickHouse and Redis or Valkey, which are new components for most v2 teams. The second is migration timing, because background jobs can run for hours on large tables and can surprise a schedule. The third is coordinating SDK updates across every application in the same window. Common problems include skipped rehearsals, unverified backups and disk use that grows faster than expected. Assess your team against those three areas, and decide whether a partner should cover the whole upgrade, the rehearsal, or the cutover only.
Is the Langfuse v2 to v3 upgrade zero downtime?
The official approach supports a zero-downtime path, but whether your deployment achieves it depends on your configuration and cutover plan. Langfuse recommends provisioning new web and worker containers with LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS set to false until traffic is shifted. The guide notes that the upgrade works well between v2.92.0 and v3.29.0, so v3.29.0 is the version to use for parallel operation before you move to the latest v3. Confirm each step against the guide for your exact versions and data stores. Ask your team to test how SDKs behave during the traffic shift, including retries and any ingestion gaps, and to record what the cutover looks like in a rehearsal.
What happens to SDKs still on version 1.x.x after the upgrade?
Langfuse server v3 does not support SDK v1.x.x, so those SDKs must be updated as part of the upgrade plan. The Python SDK v2 and JavaScript SDK v2 were both released in December 2023, and those are the minimum versions to plan for. Inventory every application that sends traces, including scripts, notebooks, batch jobs and third-party integrations, because each one needs a version check and a test against the v3 server. Test the updated SDKs in a non-production environment before the cutover. If some teams cannot update in time, confirm with Langfuse how they can keep sending traces during the transition, and record the decision in the cutover plan.
How does the v2 to v3 upgrade relate to the v3 to v4 upgrade?
The v2 to v3 upgrade is the foundation for the later v4 move, and the v4 guide adds requirements of its own. The v3 to v4 guide requires ClickHouse 25.12 or later, with 26.4 recommended, PostgreSQL 15 or later and Redis 7.0 or later. It moves to an observations-first ClickHouse data model and advises about 3x ClickHouse disk headroom when backfilling historic data. Helm users with bundled data stores must upgrade the Helm chart from v1 to v2 before upgrading Langfuse to v4. The GitHub releases page lists v4.63.0, published October 16, 2026, so a v2 deployment is two major versions behind. Plan the v4 move as a separate project after v3 background migrations are complete, and budget ClickHouse capacity early.
How DeployOpen scopes, delivers and supports the Langfuse upgrade
DeployOpen plans the move from a Postgres-only Langfuse v2 deployment to the v3 architecture inside your own infrastructure, with ClickHouse, Redis or Valkey and S3-compatible blob storage in place. Engagements are fixed-scope, so the written scope fixes what is migrated, tested and handed over before work starts. Ongoing support is available as a retainer.
How we scope
- The written scope names the v2 source instance, its data volumes and the target v3 release line.
- It states whether parallel operation, cutover and rollback are in or out of the engagement.
- Scoping confirms current SDK versions, since Langfuse v3 does not support SDK v1.x.x.
How we build
- Provision new web and worker containers with LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false set until traffic is shifted.
- Run the parallel stage on v3.29.0, the release the guide names for this step, before moving to latest v3.
- Plan for four sequential background migrations that may run for multiple hours, depending on table size.
How we hand over
- Handover covers the migration runbook, configuration values, and the verification checks run at each stage.
- Postgres backup is confirmed and restore is verified before any data-moving step begins.
- Operators receive written notes on running the Langfuse Web and Worker containers after cutover.
How we support
- Post-cutover monitoring covers worker CPU load and the ingestion path, the scaling points Langfuse documents.
- Ongoing support, upgrades and testing are available as a retainer after the engagement closes.
- Confirm with Langfuse whether a named support engineer or SLA from its Enterprise plan fits your needs.
