Upgrade to v6
Upgrade from v5 to v6.0.0 with database migrations, deployment changes, and historical data guidance.
This guide covers the stable 6.0.0 release. Back up your databases and deployment configuration, and validate the upgrade in a test or pre-production environment before upgrading production.
Before moving to v6, we recommend that you upgrade your existing installation to v5.4.10 first. If you are running v4, upgrade to v5 first. Within v5, you may skip intermediate application versions, but you must review their release notes and apply any required migrations or configuration changes in order. Read the general upgrade guidelines before starting.
Overview
Upgrade status: Additional steps required. v6.0.0 changes the deployment and database schemas.
Release: v6.0.0 on GitHub.
What's new: A redesigned React UI, rebuilt experimentation, a new Insights pipeline, and an optional Control Plane for multi-data-center deployments. The standalone Data Analytics service is retired. Review integrations that use v5 experimentation APIs or the old analytics service.
Control Plane is disabled by default. Standard deployments do not need to add this service when upgrading to v6.
Business database migration
Historical data
In v5, the events table or collection held events used by the old analytics and experimentation flow. The experiments and experiment_metrics tables or collections held experiment definitions and metrics. These records may be needed for historical reporting or a later data migration.
The v6 scripts preserve these records but do not convert them into the new experiment model:
| Database | Existing object | Preserved as |
|---|---|---|
| PostgreSQL | events, experiments, experiment_metrics | events_legacy, experiments_legacy, experiment_metrics_legacy |
| MongoDB | Events, Experiments, ExperimentMetrics | EventsLegacy, ExperimentsLegacy, ExperimentMetricsLegacy |
The archived v5 records are not converted into v6 experiment data, so historical experiment reports are not automatically available in the v6 UI.
Keep the legacy data if you need historical reporting or future migration assistance. Delete it only when you are certain it is no longer required and after verifying that the v6 upgrade is successful.
Database schema changes in v6
The v6 experiments and experiment_metrics tables in PostgreSQL, and the corresponding Experiments and ExperimentMetrics collections in MongoDB, reuse the v5 names but have entirely different structures. They hold new v6 data, not the archived v5 records. Exposure events and metric events also move to separate storage.
| Database | Changes introduced by the 6.0.0 scripts |
|---|---|
| PostgreSQL | Adds committed_version and pending fields to feature flags and segments; creates dc_leases for Control Plane; creates new tables and indexes for experiments, metrics, layers, runs, assignments, exposure and metric events, and MCP authorization. |
| MongoDB | Initializes committedVersion on existing feature flags and segments; adds indexes for data-center leases and the new experiment, event, and MCP authorization collections. The new experiment and metric collections use the v6 structure. |
Choose the script
Check the DbProvider setting used by your FeatBit API and Evaluation Server. Apply one matching database script.
| Configuration | Script from the 6.0.0 tag |
|---|---|
DbProvider=Postgres | PostgreSQL v6.0.0.sql |
DbProvider=MongoDb | MongoDB v6.0.0.js |
Both supplied scripts target a database named featbit. If Postgres__ConnectionString selects another PostgreSQL database or MongoDb__Database is not featbit, tailor the selected script to target that database before running it.
Review the exact scripts and back up the affected databases before running them. Run each applicable script once with an authenticated database client suited to your environment. Record the output and exit status. If a script fails, inspect the partial state before retrying; do not assume that rerunning it is safe.
ClickHouse changes
This section applies only to FeatBit Professional deployments using Kafka & ClickHouse. Follow it in addition to the business database migration selected by DbProvider above.
Configure the API service
v6 adds OLAPProvider to select where the API queries Insights data. If it is unset, Insights uses DbProvider. Set the following values on the API service before starting v6 with ClickHouse:
| Setting | Required value or default |
|---|---|
OLAPProvider | Set to ClickHouse to query Insights from ClickHouse. |
ClickHouse__HttpEndpoint | Required ClickHouse HTTP URL, for example http://clickhouse-server:8123. Use your own reachable endpoint. |
ClickHouse__Database | Defaults to featbit. Set it to the database used by your ClickHouse migration. |
ClickHouse__User | Defaults to default. Set it to your ClickHouse user. |
ClickHouse__Password | Defaults to empty. Set it if your ClickHouse user requires a password. |
For FeatBit Professional, MqProvider should be Kafka on both the API and Evaluation Server: the Evaluation Server publishes Insights events to Kafka, and ClickHouse consumes them from there.
Historical data and schema changes
The old featbit.events table stored analytics events. The v6 script preserves it as featbit.events_legacy when it exists; it does not convert those records into the new v6 event tables. Keep the legacy table if you need historical reporting or future migration assistance. Delete it only when you are certain it is no longer required and after verifying the upgrade.
The script creates separate experiment_exposure_events and experiment_metric_events tables. It detaches the old Kafka ingestion objects and creates a new Kafka queue and materialized views to populate the v6 tables.
Apply the ClickHouse migration
In addition to the matching business-database script, review and run the ClickHouse v6.0.0.sql script once. Back up the affected data and record the script's output and exit status. If it fails, inspect the partial state before retrying.
The supplied script creates objects in the featbit database and targets a default single-node layout with Kafka at kafka:9092, topic featbit-insights, and consumer group ch_group. It rejects some archive collisions and replicated or distributed layouts. Custom database or Kafka settings and ClickHouse clusters need a tailored script; changing the API settings alone does not change the script's targets. Do not run concurrent upgrades, suppress errors, or reset the Kafka consumer offsets.
Remove the legacy Data Analytics service
The v6 experimentation and Insights flow no longer uses da-server (image featbit/featbit-data-analytics-server). Stop this service and remove it from your deployment definition when moving to v6. Review any monitoring or integrations that depend on it.
Remove OLAP__ServiceHost from the API service configuration as well. In earlier versions, this environment variable pointed to the da-server URL; v6 no longer requires it.
Verify the upgrade
- Confirm that the UI, API, and Evaluation Server are running
6.0.0, and inspect their startup logs for database or configuration errors. - Sign in and confirm that existing projects, environments, feature flags, and segments are available with the expected access permissions.
- Connect an SDK using an existing environment key and verify flag evaluation. Make a controlled flag change and confirm that the SDK receives it.
- Create a v6 test experiment, generate exposure and metric events, and confirm that they are persisted in the configured storage and available through Insights after asynchronous processing.
Historical v5 experiment reports are not expected to appear in the v6 UI; their records remain in the legacy tables or collections described above.
Recover from a failed upgrade
If the upgrade fails, retain logs and the failed state for diagnosis. A full return to v5 requires restoring the pre-upgrade database backups together with the matching old images and deployment configuration.