Background Migrations

Langfuse uses background migrations to perform long-running changes within the storage components when upgrading the application. These may include the addition and backfilling of new columns or the migration of data between storages. Background migrations are executed on startup of the worker container and run in the background until completion or failure.

Next to background migrations, fast migrations are applied directly to the database on startup of the web container.

Monitoring

You can monitor the progress of background migrations within the Langfuse UI. Click on the Langfuse version tag and select “Background Migrations”. You see all migrations that ever ran and their status. You can also monitor the progress of background migrations via the worker container logs.

If migrations are running or have failed, we show a status indicator within the UI to guide users towards the background migrations overview.

Deployment stops

Langfuse does not require deployment stops between minor releases as of now. However, we recommend that you monitor the progress of background migrations after each update to ensure that all migrations have completed successfully before attempting another update. We will highlight within the changelog if a deployment stop becomes required.

Configuration

Background migrations are enabled by default and can be disabled by setting LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS=false. This is not recommended as it may leave the application in an inconsistent state where the UI and API does not reflect the current state of the data correctly.