Upgrade instructions

Select a card above to open the upgrade guide for your deployment type, then follow its steps for the target version. Each guide includes instructions for pulling the new image and running the upgrade script.

The table below lists all supported upgrade paths. Versions must be upgraded sequentially — you cannot skip versions.

The 2.4.0PE upgrade records the new schema version and creates the dropped_msg table and its index, used by dropped message analytics. Nothing else changes: no existing table is altered and no data is migrated.

You can migrate from TBMQ to TBMQ PE of the same version. For example, TBMQ 2.4.0 can be upgraded to TBMQ PE 2.4.0. Cross-version migration (e.g. TBMQ 2.3.0 to TBMQ PE 2.4.0) is not supported — upgrade TBMQ to the target version first, then migrate to TBMQ PE.

The following changes apply only when migrating from TBMQ v2.2.0 to TBMQ PE v2.2.0. They do not apply to v2.3.0 and later.

These updates follow the modernization plan outlined in the Bitnami Image Migration guide.

Before starting, create full backups of your environment — including the PostgreSQL database (for example, using pg_dump) and your Kafka and Redis data volumes if you plan to migrate them.

PostgreSQL is upgraded from 16 to 17. Although existing data volumes remain compatible, you must perform a proper database version upgrade (for example, using pg_upgrade) to ensure data integrity.

Kafka and Redis have been migrated from Bitnami images to official open-source alternatives. The new images use different internal data directories and volume mappings, so existing Bitnami volumes cannot be reused directly. You must either migrate your data manually or start from new, empty volumes.

The standard upgrade script updates only the PostgreSQL database schema and does not include data migration logic for Kafka or Valkey.

The upgrade validates the database before it changes anything, and stops with one of the messages below.

Upgrade failed: database already upgraded to current version.

The schema version recorded in the database already matches the version you are upgrading to — either the upgrade already completed, or an earlier run failed after the version had been recorded. See forcing a re-upgrade below.

Upgrade failed: database version 'X' is not supported for upgrade. Supported versions are: [...]

An upgrade accepts only the versions listed in the message, normally just the one immediately before the target. Upgrade one version at a time along the paths in the version history above.

Upgrade failed: can't upgrade TBMQ <A> database using TBMQ <B>.

The edition you are upgrading with does not match the edition recorded in the database. Use TBMQ to upgrade a TBMQ database and TBMQ PE to upgrade a TBMQ PE database.

To migrate a TBMQ database to TBMQ PE, run the CE-to-PE upgrade described in Upgrade from TBMQ to TBMQ PE — it takes the source edition as an argument, which a plain upgrade does not.

Upgrade failed: transitioning from CE to PE requires the database to first be upgraded to version 'X' using TBMQ CE.

A CE-to-PE migration is only supported at the same version. Upgrade TBMQ to the version reported in the message first, then migrate to TBMQ PE.

Upgrade failed: the database schema version is missing.

The tb_schema_settings table holds no version. Either the upgrade is pointed at the wrong database, or that database was never initialized by a TBMQ installation.

Setting the SKIP_SCHEMA_VERSION_CHECK environment variable to true on the upgrade makes it skip all of the validation above and run regardless. Where that variable goes depends on the deployment — see the guide for your deployment type.