Before You Upgrade
- Check release notes for breaking changes at github.com/langwatch/langwatch/releases
- Back up your databases: see Backups
- Test in a staging environment before upgrading production
Docker Compose
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 oflatest:
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:Version Compatibility
Getting Help
If you encounter issues during an upgrade:- Check pod logs:
kubectl -n langwatch logs deploy/langwatch-app --tail=100 - Check the Troubleshooting guide
- Open an issue at github.com/langwatch/langwatch/issues
- Contact support