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.0 upgrade only records the new schema version in the database — no table is created or altered, and no data is migrated.

TBMQ v2.3.0 migrates all third-party components from Bitnami images to official open-source alternatives. These changes improve performance, stability, and remove the dependency on Bitnami’s image catalog.

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.

TBMQ deployments prior to v2.3.0 use Bitnami images for third-party components such as PostgreSQL, Redis, and Kafka. The Bitnami team has announced important upcoming changes to their catalog that affect these images.

• Starting August 28, 2025, the public docker.io/bitnami registry will only provide a small set of “latest” hardened images for development use.
• All versioned images will be moved to a temporary legacy registry: docker.io/bitnamilegacy. These images will remain available but will not receive updates or security patches.
• The long-term supported solution is Bitnami’s new Secure Images (subscription-based).

Recommended: Complete the upgrade to v2.2.0 first (upgrades must be sequential), then continue to v2.3.0, which replaces all Bitnami images with official open-source alternatives. See third-party component updates in v2.3.0 for details.

If you are staying on v2.2.0 for now, update your image references from docker.io/bitnami/... to docker.io/bitnamilegacy/... to avoid disruption after August 28, 2025.

Version 2.0.0 introduces significant improvements, including a migration from PostgreSQL to Redis for storing messages for persistent DEVICE clients. For details, see the architecture documentation.

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.

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.