Migrating to 4.0

CosId 4.0 runs on Java 17 or later and Spring Boot 4.x. The complete list of breaking changes, with the replacement for each removed API, is in the migration guide. This page lists the steps most applications need.

Before the upgrade

• Upgrade to the latest 3.4.x first and clear its deprecation warnings. Rolling upgrades are supported from 3.4.x only.
• Rebuild code and libraries compiled against CosId 3.x, including ShardingSphere's CosId algorithms: some IdGeneratorProvider and LazyIdGenerator signatures changed.
• Use the same cosid.machine.guarder.safe-guard-duration on every instance of a namespace.

Rolling upgrade by backend

Backend	What to do
JDBC	Run the ALTER TABLE for the renew_time, watermark and lease_version columns (and stable on tables created before 3.3) before starting 4.0 instances, see JDBC
Redis	Nothing: 4.0 adds a lease hash next to the 3.4 keys
ZooKeeper, MongoDB	Nothing: the 3.4 format is kept
Proxy	Set cosid.proxy.token on the 3.4.x clients first (3.4 sends it, and a server without tokens ignores it); then upgrade the proxy servers with the same token in cosid.proxy.server.auth.tokens; then upgrade the clients. Upgrading the servers first gives 3.4 clients without a token 401, see CosId Proxy

3.4.x and 4.0 instances can share a namespace while the upgrade runs. Rolling Upgrade has the steps in order.

Configuration

• cosid.jdbc.enabled and cosid.actuator.delete.enabled default to false. Spring Data JDBC users must set cosid.jdbc.enabled=true.
• cosid.machine.distributor.provider and cosid.segment.distributor.provider are removed: the type also selects a CosIdStoreProvider by its getType().
• The machine id Redis, ZooKeeper and MongoDB timeouts and cosid.proxy.read-timeout must be positive.
• Typed lookups replace casts: provider.getRequired("order", IdGenerator.class).
• The sharding algorithms moved to me.ahoo.cosid:cosid-sharding, the accessors and @CosId to me.ahoo.cosid:cosid-accessor.

Not every change fails at startup:

• With cosid.jdbc.enabled off, Spring Data JDBC entities are saved without CosId ids: startup only logs an INFO that names those entities.
• A class that moved to a module you did not add fails with ClassNotFoundException or NoClassDefFoundError when it is first loaded.
• A lookup of a string-only generator as IdGenerator fails when it runs, with an IllegalArgumentException naming both types.

The configuration errors do fail at startup, with a message naming the fix; Troubleshooting lists them.