Distributed Primary Keys in ShardingSphere: Strategies & Custom Implementations

大家好，我是苏三。

Why Use Distributed Primary Keys

In a traditional single‑database single‑table setup, auto‑increment primary keys guarantee uniqueness, but in sharding scenarios each table’s auto‑increment starts at 1, causing overlapping key ranges across databases and tables. To ensure global uniqueness, a distributed ID generator must be introduced and used as the primary key for every record.

Beyond uniqueness, the data type and length of the primary key affect query performance and overall system efficiency, so these factors should be considered when choosing a strategy.

Built‑in Algorithms

Since ShardingSphere 5.X, the framework provides several built‑in primary‑key generation strategies. Earlier versions only offered UUID and Snowflake; newer versions add NanoID, CosId, and CosId‑Snowflake.

UUID

UUID provides globally unique IDs and is easy to use, but it is not recommended as a primary key because its randomness leads to InnoDB page splits, data fragmentation, and slower queries. Moreover, storing UUID as a string consumes more space than numeric types.

UUID’s unordered nature forces InnoDB to locate free space for each new row, causing frequent page splits and fragmentation.

String representation occupies more storage and disrupts index continuity.

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # UUID generation algorithm
          uu-id-gen:
            type: UUID
        tables:
          t_order:  # logical table name
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: uu-id-gen

NanoID

NanoID is a lightweight library that generates 21‑character string IDs. Although shorter than UUID, it shares the same drawbacks and is also not recommended as a primary key.

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # NanoID generation algorithm
          nanoid-gen:
            type: NANOID
        tables:
          t_order:
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: nanoid-gen

Custom Snowflake

Snowflake is a widely used distributed ID algorithm that generates Long values and serves as the default primary‑key strategy in ShardingSphere.

The generated ID consists of a timestamp, a worker‑ID, and a sequence number.

@Override
public synchronized Long generateKey() {
    // ...
    return ((currentMilliseconds - EPOCH) << TIMESTAMP_LEFT_SHIFT_BITS)
           | (getWorkerId() << WORKER_ID_LEFT_SHIFT_BITS)
           | sequence;
}

Three configurable properties control the algorithm: worker-id: unique identifier of the machine (default 0 in single‑node mode). max-vibration-offset: limits the sequence variation within the same millisecond (range [0, 4096)). max-tolerate-time-difference-milliseconds: maximum tolerated clock rollback; if exceeded, an exception is thrown.

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # Snowflake ID generation algorithm
          snowflake-gen:
            type: SNOWFLAKE
            props:
              worker-id: # machine ID
              max-vibration-offset: 1024
              max-tolerate-time-difference-milliseconds: 10
        tables:
          t_order:
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: snowflake-gen

CosId

CosId is a high‑performance distributed ID framework integrated into ShardingSphere. In version 5.2.0 the algorithm is currently unavailable.

CosId provides three algorithms: SnowflakeId, SegmentId, and SegmentChainId (recommended). They differ in performance and storage backend options.

SnowflakeId

: 4.09 M IDs/s, solves clock rollback and machine‑ID allocation. SegmentId: allocates a range of IDs to reduce network I/O; supports DB, Redis, Zookeeper. SegmentChainId: lock‑free enhancement of SegmentId, achieving up to 12.7 M IDs/s.

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # CosId generation algorithm
          cosId-gen:
            type: COSID
            props:
              id-name: share
              as-string: false
        tables:
          t_order:
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: cosId-gen

CosId‑Snowflake

CosId‑Snowflake mirrors the standard Snowflake algorithm, combining timestamp, worker‑ID, and sequence, and also handles clock rollback.

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # CosId‑Snowflake generation algorithm
          cosId-snowflake-gen:
            type: COSID_SNOWFLAKE
            props:
              epoch: 1477929600000
              as-string: false
        tables:
          t_order:
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: cosId-snowflake-gen

Custom Distributed Primary Key

When built‑in strategies do not meet specific business requirements, ShardingSphere allows custom primary‑key generators.

Implement Interface

Implement the KeyGenerateAlgorithm interface and provide the four required methods, especially getType() (algorithm identifier) and generateKey() (core generation logic).

@Data
@Slf4j
public class SequenceAlgorithms implements KeyGenerateAlgorithm {

    @Override
    public String getType() {
        // Return algorithm type identifier
        return "custom";
    }

    @Override
    public Comparable<?> generateKey() {
        return null;
    }

    @Override
    public Properties getProps() {
        return null;
    }

    @Override
    public void init(Properties properties) {
    }
}

SPI Registration

Place a file named org.apache.shardingsphere.sharding.spi.KeyGenerateAlgorithm under resource/META-INF/services and list the fully‑qualified class name of the custom algorithm, one per line. ShardingSphere will load it via SPI at startup.

resource
    |_META-INF
        |_services
            |_org.apache.shardingsphere.sharding.spi.KeyGenerateAlgorithm

Configuration Usage

Configure the custom algorithm in the ShardingSphere YAML/Properties just like built‑in generators, using the type identifier defined in getType().

spring:
  shardingsphere:
    rules:
      sharding:
        key-generators:
          # Custom ID generation strategy
          xiaofu-id-gen:
            type: custom
        tables:
          t_order:
            actual-data-nodes: db$->{0..1}.t_order_${0..2}
            key-generate-strategy:
              column: id
              keyGeneratorName: xiaofu-id-gen

During an insert operation, the custom algorithm is invoked to produce the primary key.

Conclusion

We introduced ShardingSphere’s built‑in primary‑key generation strategies and demonstrated how to create and register custom generators. The choice of strategy should be guided by business requirements such as global uniqueness, performance, availability, and ease of integration.