CosId Universal, flexible, high-performance distributed ID generator

中文文档 | English Document

Warning

5.0.0-rc.x is a release candidate. From RC1 on, the Java API, the cosid.* configuration and the storage formats and protocols are frozen: later 5.x releases only add to them. Production use should still wait for GA; until then, stay on 4.x there.

Every replica of a service needs ids (primary keys, order numbers, event ids) that never collide with those of the other replicas. CosId generates them inside your process, without a network call per id, and does the coordination that keeps them unique.

CosId 5 is a full rewrite with no backward compatibility. In it, uniqueness depends on no clock: a machine slot is leased as a time window, successive holders' windows never overlap, and the store itself keeps that rule. Clock skew, GC pauses and failovers cost availability, never uniqueness. Every strategy runs on one CosIdRuntime, and Spring Boot, cosid-server and plain Java start it the same way. The offline cosid-migration tool moves a 4.x deployment over.

Strategy	Id	Pick it when
snowflake	long, time-ordered (any Layout: ms or s, JS-safe 53 bits)	ids should carry their creation time, with no store call per id
segment	long, dense, increasing per instance	you want short numeric keys; reservations size themselves to a time budget
periodic-segment	per year / month / day (20261027-000042)	business numbers that restart each period
cosid80	80-bit text	you need more than 64 bits
uuidv7	UUIDv7 (RFC 9562), time-ordered	you want standard UUIDs, with no machine, store nor lease
custom	your own long generator	you have one, and want it served like the others

Stores: JDBC (MySQL 8.4+, MariaDB 10.11+, PostgreSQL 15+, SQL Server 2019+, H2), Redis 7.0+, MongoDB 6.0+, ZooKeeper 3.8+, and cosid-server; declared once, mixed freely.

Version compatibility

CosId	Spring Boot	Java	Branch
5.x	4.1.2+	21+	main
4.x	4.x	17+	4.x (maintenance: bug fixes only)
3.x	4.x	17+	3.x
2.x	3.x	17+	2.x
1.x	2.x	8+	1.x

Upgrading from 4.x: the migration guide. 4.x and 5.0 never run in one namespace.

Quick start

dependencies {
    implementation(platform("me.ahoo.cosid:cosid-bom:$cosidVersion"))
    implementation("me.ahoo.cosid:cosid-spring-boot-starter")
    implementation("me.ahoo.cosid:cosid-store-jdbc")   // or cosid-store-redis, -mongo, -zookeeper, -remote
}

cosid:
  namespace: ${spring.application.name}
  stores:
    db:
      type: jdbc              # the application's DataSource
  machine:
    leased:
      store: db               # the machine slot, leased from the store
  generators:
    default:
      strategy: snowflake
    order:
      strategy: segment
      store: db
      codec: [ { radix: { radix: 62 } }, { prefix: "O" } ]

public OrderService(IdGenerator ids, @Qualifier("order") IdGenerator orderIds, CosIdRuntime runtime) {
    long id = ids.generate();                                   // the "default" Snowflake
    String orderNo = runtime.stringGenerator("order").generate();
}

Getting Started covers Maven and plain Java too.

Modules

Artifact	Contents
cosid-core	generators, layouts and codecs, slot leases, CosIdRuntime, @CosId field filling; depends on slf4j-api only
cosid-store-jdbc	JDBC store: MySQL, MariaDB, PostgreSQL, SQL Server, H2, and the JdbcDialect SPI
cosid-store-redis	Redis store (Lettuce); see its durability precondition
cosid-store-mongo	MongoDB store (replica set)
cosid-store-zookeeper	ZooKeeper store (Curator)
cosid-store-remote	the client of cosid-server (JDK HttpClient)
cosid-store-tck	the store contracts and an in-memory store, for tests
cosid-spring-boot-starter	Spring Boot: core + cosid-spring-boot-autoconfigure; add the stores you use
cosid-jackson, cosid-mybatis, cosid-spring-data-jdbc, cosid-activiti, cosid-flowable, cosid-axon	integrations, one per library
cosid-sharding	sharding algorithms: ModCycle, IntervalTimeline, CachedSharding
cosid-bom	the versions of all of the above
cosid-server	the remote store service, a Docker image (server/)
cosid-migration.jar	the offline 4.x → 5.0 tool (migration/)

Documentation

• Why CosId and ID recipes.
• Concepts: layouts and codecs, the machine slot lease, segments, the runtime.
• Choosing a backend: supported versions, measured compatibility, preconditions.
• cosid-server: API, authentication, limits, Docker.
• Configuration reference: every cosid.* property and its default.
• Operations: production checklist, metrics, health, troubleshooting.
• Migrating from 4.x.
• The design: docs/architecture/ (decisions D1–D30).

The examples are runnable applications: segment-jdbc, snowflake-redis and server.

Performance

5.0 must not be slower than 4.x in any scenario: every benchmark runs on the released 4.1.0 and on 5.0, and the comparison is a release gate. Results go to docs/jmh/. The hot path of a segment id is one atomic add; a Snowflake id is a short critical section that never waits under its lock.

Contributing

Bug reports, ideas and pull requests are welcome. Read CONTRIBUTING.md for the development setup, commit conventions, review and release process, and SECURITY.md to report a vulnerability privately. The planned work is in the roadmap.

Community Partners and Sponsors