Mastering TinyID: A High‑Performance Distributed ID System for Java Backend

TinyID Overview

TinyID is a distributed ID system created by Didi, built on the Leaf segment algorithm and enhanced to support multi‑master database mode and a convenient tinyid-client for client integration. Unlike Leaf, TinyID only supports the segment mode, not the Snowflake mode.

TinyID Features

Globally unique long‑type IDs

Monotonically increasing IDs

HTTP and Java client access methods

Batch ID retrieval

Support for odd‑numbered sequences (1,3,5,…)

Multiple database configurations

Applicable Scenarios : Systems that only need numeric, increasing IDs and can tolerate non‑continuous IDs and occasional ID waste.

Unsuitable Scenarios : Order‑ID use cases where IDs are mostly continuous, as they could be guessed or used to infer order volume.

TinyID Principle

TinyID uses a segment‑based approach: a range of auto‑increment IDs is fetched from the database (e.g., (1,1000] representing 1000 IDs). The service loads the segment into memory and generates IDs locally. When the current segment reaches a usage threshold, the next segment is loaded asynchronously to ensure continuous availability.

The principle diagram:

Database Schema

tiny_id_info

stores segment information for each business type.

CREATE TABLE `tiny_id_info` ( ... ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='id information table';

tiny_id_token

is a permission table indicating which tokens can operate on which business types.

Configuration

Modify offline/application.properties to configure multiple master databases:

datasource.tinyid.primary.driver-class-name=com.mysql.jdbc.Driver
datasource.tinyid.primary.url=jdbc:mysql://127.0.0.1:3306/xin-master?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8
datasource.tinyid.primary.username=junkang
datasource.tinyid.primary.password=junkang
...

datasource.tinyid.secondary.driver-class-name=com.mysql.jdbc.Driver
datasource.tinyid.secondary.url=jdbc:mysql://localhost:3306/db2?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8
datasource.tinyid.secondary.username=root
datasource.tinyid.secondary.password=123456
...

HTTP API

TinyID provides four HTTP endpoints for ID and segment retrieval. Example controller snippet:

@RestController
@RequestMapping("/id/")
public class IdController {
    @Autowired
    private IdGeneratorFactoryServer idGeneratorFactoryServer;
    @RequestMapping("nextId")
    public Response<List<Long>> nextId(String bizType, Integer batchSize, String token) { ... }
    @RequestMapping("nextIdSimple")
    public String nextIdSimple(String bizType, Integer batchSize, String token) { ... }
    @RequestMapping("nextSegmentId")
    public Response<SegmentId> nextSegmentId(String bizType, String token) { ... }
    @RequestMapping("nextSegmentIdSimple")
    public String nextSegmentIdSimple(String bizType, String token) { ... }
}

Sample requests:

GET http://localhost:9999/tinyid/id/nextId?bizType=test&token=0f673adf80504e2eaa552f5d791b644c
Response: {"data":[2],"code":200,"message":""}

GET http://localhost:9999/tinyid/id/nextIdSimple?bizType=test&token=0f673adf80504e2eaa552f5d791b644c
Response: 3

TinyID‑Client Usage

Include the client dependency:

<dependency>
    <groupId>com.xiaoju.uemc.tinyid</groupId>
    <artifactId>tinyid-client</artifactId>
    <version>${tinyid.version}</version>
</dependency>

Configure the server address and token in application.properties:

tinyid.server=127.0.0.1:9999
tinyid.token=0f673adf80504e2eaa552f5d791b644c

Java code example:

// Single ID
Long id = TinyId.nextId("test");
// Batch IDs
List<Long> ids = TinyId.nextId("test", 10);

Conclusion

Both HTTP and client modes are supported, but the tinyid-client is recommended because IDs are generated locally; a larger segment size ( step) yields higher QPS (potentially >10 million). This reduces load on the TinyID server.

Project Repository

GitHub: https://github.com/didi/tinyid