Upgrade instructions
Select your deployment type and follow the upgrade guide for your target version
Version history
Section titled Version historySelect 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.
| Target version | Upgrade from | Notes |
|---|---|---|
| 2.4.0PE | 2.3.0PE | See what the 2.4.0PE upgrade does below |
| 2.4.0PE | TBMQ 2.4.0 (CE) | See CE-to-PE migration below |
| 2.3.0PE | 2.2.0PE | |
| 2.3.0PE | TBMQ 2.3.0 (CE) | See CE-to-PE migration below |
| 2.2.0PE | TBMQ 2.2.0 (CE) | See CE-to-PE migration — third-party changes apply |
Upgrading to 2.4.0PE
Section titled Upgrading to 2.4.0PEThe 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, so the change is additive and safe to apply to an existing database.
On Docker and Docker Compose deployments the upgrade script still requires a .tbmq-upgrade.env file in the same directory as docker-compose.yml, as it has since v2.3.0.
The script exits without it, so create an empty one if you do not already have it from a previous upgrade. Kubernetes deployments do not need this file.
The upgrade script stops the tbmq service while the upgrade runs and starts it again afterwards, so expect a brief interruption.
Upgrade from TBMQ to TBMQ PE
Section titled Upgrade from TBMQ to TBMQ PEYou 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.
Third-party component updates (CE v2.2.0 → PE v2.2.0 only)
Section titled Third-party component updates (CE v2.2.0 → PE v2.2.0 only)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.
| Component | TBMQ v2.2.0 | TBMQ PE v2.2.0 | Notes |
|---|---|---|---|
| PostgreSQL | postgres:16 |
postgres:17 |
Improved performance and resource efficiency. Existing data volumes remain compatible. |
| Kafka | bitnamilegacy/kafka:3.7.0 |
apache/kafka:4.0.0 |
Migrated from Bitnami to the official Apache Kafka image. New volume paths are required. |
| Redis → Valkey | bitnamilegacy/redis:7.2.5 |
valkey/valkey:8.0 |
Migrated from Bitnami Redis to Valkey. A new volume tbmq-valkey-data is introduced. |
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.