Rolling Upgrades

[WangCCA]

Describe your question

Minor version upgrades, such as upgrading from 3.123.1 to 3.137.0.

Multiple langfuse.web and langfuse.worker have been self-deployed

Will there be any problems with rolling upgrades, because updating an image will involve changes to the database schema? All other containers that have not been rolled and updated will report errors. Is there a sequential dependency relationship between web and worker version upgrades?

Can I upgrade any container of the web or worker at will

Langfuse Cloud or Self-Hosted?

Self-Hosted

If Self-Hosted

3.123.1

If Langfuse Cloud

No response

SDK and integration versions

No response

Pre-Submission Checklist

• I have checked for existing issues/discussions and consulted Langfuse AI.

[inkeep-ai-assistant[bot]]

Based on the available documentation, here's what you need to know about rolling upgrades for minor version updates:

Database Migrations During Upgrades

When upgrading Langfuse, database migrations are applied automatically during container startup(1). This means that when you start a new version of the container, it will run any necessary database schema changes before the application becomes available(1).

Rolling Upgrade Considerations

For minor/patch version updates within the same major version (like 3.123.1 to 3.137.0), updates are designed to be non-disruptive(1). The documentation states that "Updates within a major version are designed to be non-disruptive and are automatically applied"(1).

However, the documentation doesn't explicitly address the specific scenario of rolling upgrades with multiple web and worker containers running simultaneously during the upgrade process.

Recommended Approach

For a zero-downtime upgrade, the v2 to v3 migration guide recommends provisioning new instances and moving traffic after validation(2). While this guidance is for major version upgrades, it suggests the safest approach is:

1. Provision new container instances with the updated version
2. Allow migrations to complete on the new instances
3. Shift traffic after validation
4. Stop old containers(2)

Important Note

The documentation emphasizes that you can use langfuse/langfuse:3 and langfuse/langfuse-worker:3 as image tags to automatically use the latest version of a major release(1).

I don't have specific documentation about the sequential dependency between web and worker upgrades during rolling deployments, or whether you can upgrade containers in any order without issues. For production deployments with multiple containers, I recommend reaching out to Langfuse support or creating a GitHub issue to clarify the recommended rolling upgrade procedure for your specific deployment scenario(1).

📚 Sources:

1. Upgrading a Self-Hosted Langfuse Deployment
2. Migrate Langfuse v2 to v3

---

Have another question? Just tag @inkeep.

[WangCCA]

For The documentation emphasizes that you can use langfuse/langfuse:3 and langfuse/langfuse-worker:3 as image tags to automatically use the latest version of a major release。

I understand that it is forward compatible

[Lotte-Verheyden]

@inkeep

[inkeep-ai-assistant[bot]]

I need to clarify an important distinction about forward compatibility in Langfuse upgrades.

Using Version Tags

When you use langfuse/langfuse:3 and langfuse/langfuse-worker:3 as image tags, you automatically get the latest minor/patch version within the v3 major release(1). This means your deployment will pull updates like 3.123.1 → 3.137.0 automatically.

Important Clarification on Compatibility

However, this doesn't mean Langfuse is "forward compatible" in the traditional sense. What the documentation actually states is that "Updates within a major version are designed to be non-disruptive and are automatically applied"(1).

The key points are:

1. Migrations run on startup: When a container starts, all database migrations are automatically applied(1)
2. Non-disruptive design: Minor/patch updates within v3 are designed to be non-disruptive(1)
3. Not backward compatible: Once migrations run, older versions may not work correctly with the updated schema

What This Means for Rolling Upgrades

The documentation doesn't explicitly confirm that you can safely run mixed versions (e.g., some containers on 3.123.1 and others on 3.137.0) simultaneously during a rolling upgrade. The v2→v3 migration guide recommends a zero-downtime approach where you provision new instances and shift traffic after validation(2), suggesting caution when mixing versions.

For production deployments with multiple containers, I recommend contacting Langfuse support or creating a GitHub issue to confirm the specific rolling upgrade procedure and whether running mixed minor versions simultaneously is supported(1).

📚 Sources:

1. Upgrading a Self-Hosted Langfuse Deployment
2. Migrate Langfuse v2 to v3

---

Have another question? Just tag @inkeep.