Upgrade from TBMQ CE to TBMQ PE (v2.2.0)
NOTE:
These steps are applicable for 2.2.0 TBMQ CE version. In order to upgrade to TBMQ PE 2.2.0 you need to upgrade to 2.2.0 TBMQ CE first. Notice the Bitnami Images information.
Notice: Third-Party Component Updates in TBMQ PE v2.2.0
We’d like to inform you about several third-party component updates introduced in TBMQ Professional Edition (PE) v2.2.0 compared to the Community Edition (CE). These changes improve performance, stability, and align TBMQ with officially supported open-source technologies.
These updates follow the modernization plan outlined here: Bitnami Image Migration.
What’s Changed
| Component | TBMQ CE v2.2.0 | TBMQ PE v2.2.0 | What Changed & Why |
|---|---|---|---|
| PostgreSQL | postgres:16 |
postgres:17 |
Upgraded to a newer major version with improved performance, reliability, and better resource efficiency. Existing data volumes remain fully compatible. |
| Kafka | bitnamilegacy/kafka:3.7.0 |
apache/kafka:4.0.0 |
Updated according to the plan to migrate from Bitnami to official open-source images. New volumes were introduced and all of them are mapped to new paths required by the Apache Kafka image. |
| Redis → Valkey | bitnamilegacy/redis:7.2.5 |
valkey/valkey:8.0 |
Updated according to the plan to migrate from Bitnami to open-source images. Redis was replaced by Valkey (a community-driven fork of Redis 7). A new volume (tbmq-valkey-data) was introduced and mapped to the appropriate data directory used by the Valkey image. |
Important Notes
Upgrading from TBMQ CE 2.2.0 to TBMQ PE 2.2.0 introduces several component changes that require attention before and during the migration process.
Before starting the upgrade, it is strongly recommended to create full backups of your existing environment.
This includes the PostgreSQL database (for example, using pg_dump), as well as your Kafka and Redis data volumes if you plan to migrate them.
Backups ensure that your environment can be safely restored in case of configuration or compatibility issues during the upgrade.
The PostgreSQL version is upgraded from 16 to 17, providing improved performance, reliability, and resource efficiency.
Although existing data volumes remain compatible, you still need to perform a proper database version upgrade (for example, using pg_upgrade)
to ensure data integrity and full compatibility with the new version.
Both Kafka and Redis have been migrated from Bitnami images to official open-source ones — Apache Kafka and Valkey, respectively. This migration is part of the long-term modernization plan to move away from Bitnami images. Along with this change, Kafka was upgraded from version 3.7.0 to 4.0.0, introducing improvements in performance, scalability, and message handling efficiency. The new images use different internal data directories and volume mappings, so existing Bitnami volumes cannot be reused directly. You must either migrate your Kafka and Redis data manually or start from new, empty volumes.
⚠️ Be cautious: starting from new volumes will remove all data currently stored in Kafka and Redis, including client session states, undelivered and retained messages, and any other persisted broker data.
The standard upgrade script focuses only on updating the PostgreSQL database schema and does not include data migration logic for Kafka or Valkey.
NOTE: You may contact us if you require additional guidance for the migration. While we do not provide direct or fully managed migration assistance, we can offer general recommendations and insights to help facilitate a smoother upgrade experience.
Navigate to the appropriate documentation to proceed with the next upgrade steps by choosing one of the cards on top of the page.
Next steps
-
Getting started guide - This guide provide quick overview of TBMQ.
-
Security guide - Learn how to enable authentication and authorization for MQTT clients.
-
Configuration guide - Learn about TBMQ configuration files and parameters.
-
MQTT client type guide - Learn about TBMQ client types.
-
Integration with ThingsBoard - Learn about how to integrate TBMQ with ThingsBoard.