---
url: /guide/migration/4.0.md
---
# 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](https://github.com/Ahoo-Wang/CosId/blob/main/docs/MIGRATION-4.0.md). 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](../backends/jdbc.md#upgrading-a-3-x-table) |
| 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](../backends/proxy.md#upgrading-from-3-x) |

3.4.x and 4.0 instances can share a namespace while the upgrade runs. [Rolling Upgrade](../operations/rolling-upgrade.md) 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](../operations/troubleshooting.md#startup-errors) lists them.