Versioning and support policy

This chapter describes the Apicurio Registry versioning scheme, support policy, release channels, and guidance for upgrading and handling rollbacks.

Versioning scheme

Apicurio Registry follows Semantic Versioning with a clear distinction between minor and patch releases.

Release type Contents Example

Minor (e.g., 3.3.0 → 3.4.0)

New features, enhancements, and bug fixes

Scheduled development milestones

Patch (e.g., 3.3.0 → 3.3.1)

CVE and security fixes only

Dependency upgrades, security patches

Patch releases do not contain new features or bug fixes. They are limited to changes that address known security vulnerabilities.

Support window

Apicurio Registry maintains the two most recent minor versions with security patches.

When a new minor version is released, the oldest supported minor version reaches end-of-life and no longer receives updates.

Table 1. Example support timeline
Event Supported versions End-of-life

3.3.0 released

3.3.x, 3.2.x

3.1.x and older

3.4.0 released

3.4.x, 3.3.x

3.2.x and older

Release channels

Apicurio Registry provides multiple release channels so that you can choose the update cadence that suits your deployment.

Docker image tags

Tag Description

3.3.0

Pinned to an exact release. Never changes.

3.3

Floating tag that always points to the latest patch in the 3.3.x series (e.g., 3.3.0 → 3.3.1 → 3.3.2).

latest / latest-release

Always points to the most recent stable release across all minor versions.

latest-snapshot

Most recent build from the main branch. Unstable and not recommended for production.

Use the minor-series floating tag (e.g., 3.3) to automatically receive security patches without upgrading to a new minor version.

OLM channels (Kubernetes operator)

If you deploy Apicurio Registry using the Apicurio Registry Operator, each minor version has its own OLM channel:

Channel Description

3.3.x

Receives only patch updates within the 3.3 minor version.

3.x

Rolling channel that always tracks the latest minor version.

Subscribe to a minor-version channel (e.g., 3.3.x) for stability, or to the 3.x rolling channel to always receive the latest features.

Upgrading Apicurio Registry

Apicurio Registry supports forward upgrades. Database schema migrations run automatically on startup and do not require manual intervention.

Always back up your database before upgrading to a new minor version. See Backing up before an upgrade.

Patch upgrades (within a minor version)

Patch upgrades (e.g., 3.3.0 → 3.3.1) are safe and always recommended. They contain only CVE fixes and do not introduce behavioral changes.

Procedure

  1. Back up your database.

  2. Replace the Apicurio Registry container image with the new patch version or use the minor-series floating tag.

  3. Start Apicurio Registry. Any required schema migrations run automatically.

Minor upgrades

Minor upgrades (e.g., 3.3.x → 3.4.0) include new features, enhancements, and bug fixes.

Procedure

  1. Review the release notes for the target version to understand new features and any behavioral changes.

  2. Back up your database.

  3. Replace the Apicurio Registry container image with the new minor version.

  4. Start Apicurio Registry. Database schema migrations run automatically.

  5. Verify that your client applications work correctly with the new version.

Skipping minor versions

Upgrading across multiple minor versions (e.g., 3.2.x → 3.4.x) is supported. Database migrations are cumulative and applied in order on startup.

Review the release notes for all intermediate versions to understand the full set of changes.

Downgrades and rollbacks

Apicurio Registry does not support downgrades.

Database schema migrations are forward-only and irreversible. Starting an older version of Apicurio Registry against a database that has been migrated to a newer schema version will fail.

If you deploy Apicurio Registry using the Apicurio Registry Operator, switching to an older OLM channel is also not supported.

Handling a failed upgrade

If an upgrade introduces issues, restore from the database backup taken before the upgrade:

Procedure

  1. Stop Apicurio Registry.

  2. Restore the database from the backup taken before the upgrade.

  3. Deploy the previous version of Apicurio Registry.

  4. Investigate the issue before attempting the upgrade again.

Do not attempt to manually revert database schema changes.

Backing up before an upgrade

Before any minor version upgrade, create a backup of your Apicurio Registry database.

For PostgreSQL deployments:

pg_dump -h <host> -U <username> -d <database> -F c -f registry-backup-$(date +%Y%m%d).dump

For KafkaSQL deployments, back up both the Kafka topic data and the SQL snapshot database.

Store backups in a secure location and verify that they can be restored before proceeding with the upgrade.

Additional resources