Skip to main content

Before You Upgrade

  1. Check release notes for breaking changes at github.com/langwatch/langwatch/releases
  2. Back up your databases: see Backups
  3. Test in a staging environment before upgrading production

Docker Compose

Database migrations run automatically on startup.

Helm Chart

Pin a Specific Version

Database Migrations

PostgreSQL

Prisma migrations run automatically when the app pod starts. To disable this (e.g., if you run migrations separately):

ClickHouse

Schema migrations are handled by the application on startup. No manual intervention is required.

Rollback

Helm

Docker Compose

Pin image tags to a specific version instead of latest:
Then restart:

Breaking Changes

Dataset Object Storage (Helm)

Datasets moved from PostgreSQL to object storage, with a one-time automatic migration on upgrade. Helm deployments running more than one worker replica with the default local storage must either scale workers to 1 or configure S3-compatible storage before upgrading. See the dataset storage migration guide for the upgrade checklist, storage options, and rollback notes.

v1.x, v2.x to v3: ClickHouse Migration

LangWatch v3 replaces Elasticsearch/OpenSearch with ClickHouse as the primary data store. This is a zero-downtime migration, Elasticsearch and ClickHouse run side-by-side while you migrate historical data. See the full migration guide for step-by-step instructions covering infrastructure setup, data migration, and cleanup.

Helm Chart Pre-1.0.0 to 1.0.0+

If upgrading from a Helm chart version before 1.0.0, the PostgreSQL PVC naming changed. To preserve your data:
Check your existing PVC name:

Version Compatibility

Getting Help

If you encounter issues during an upgrade: