uuid7

A Rust implementation of UUID version 7

let uuid = uuid7::uuid7();
println!("{}", uuid); // e.g., "01809424-3e59-7c05-9219-566f82fff672"
println!("{:?}", uuid.as_bytes()); // as 16-byte big-endian array

let uuid_string: String = uuid7::uuid7().to_string();

See RFC 9562.

Field and bit layout

This implementation produces identifiers with the following bit layout:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          unix_ts_ms                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |        counter        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        counter                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                             rand                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Where:

• The 48-bit unix_ts_ms field is dedicated to the Unix timestamp in milliseconds.
• The 4-bit ver field is set at 0111.
• The 42-bit counter field accommodates a counter that ensures the increasing order of IDs generated within a millisecond. The counter is incremented by one for each new ID and is reset to a random number when the unix_ts_ms changes.
• The 2-bit var field is set at 10.
• The remaining 32 rand bits are filled with a cryptographically strong random number.

The 42-bit counter is sufficiently large, so you do not usually need to worry about overflow, but in an extremely rare circumstance where it overflows, this library increments the unix_ts_ms field to continue instant monotonic generation. As a result, the unix_ts_ms may have a greater value than that of the system's real-time clock. (See also Why so large counter? (42bits)).

UUIDv7, by design, relies on the system clock to guarantee the monotonically increasing order of generated IDs. A generator may not be able to produce a monotonic sequence if the system clock goes backwards. This library ignores a clock rollback and reuses the previous unix_ts_ms unless the clock rollback is considered significant (by default, more than ten seconds). If such a significant rollback takes place, this library resets the generator by default and thus breaks the increasing order of generated IDs.

Crate features

Default features:

• std enables, among others, the default timestamp source for V7Generator using std::time. Without std, users must provide their own time source implementing the TimeSource trait.
• global_gen (implies std) provides the process-wide default UUIDv7 generator and enables the primary uuid7() function.
• rand08: See below.

Optional features:

• serde enables serialization/deserialization of Uuid via serde.
• rand010 enables an adapter for rand::RngCore to use rand (v0.10) and any other conforming random number generators with V7Generator.
• uuid (together with global_gen) enables the new_v7() function that returns the popular uuid crate's Uuid objects.

Deprecated optional features:

• rand09 enables an adapter for rand::RngCore to use rand (v0.9) and any other conforming random number generators with V7Generator.
• rand08 enables an adapter for rand::RngCore to use rand (v0.8) and any other conforming random number generators with V7Generator. This feature is deprecated and for backward compatibility only, but it is always enabled and cannot be turned off for historical reasons.

Other functionality

This library also supports the generation of UUID version 4:

let uuid = uuid7::uuid4();
println!("{}", uuid); // e.g., "2ca4b2ce-6c13-40d4-bccf-37d222820f6f"

V7Generator provides an interface that allows finer control over the various aspects of the UUIDv7 generation:

use uuid7::V7Generator;

let mut g = V7Generator::with_rand010(rand::rng());
let custom_unix_ts_ms = 0x0123_4567_8901u64;
let x = g.generate_or_reset_with_ts(custom_unix_ts_ms);
println!("{}", x);

g.set_rollback_allowance(5_000);
let y = g
    .generate_or_abort_with_ts(custom_unix_ts_ms)
    .expect("clock went backwards by more than 5_000 milliseconds");
println!("{}", y);

License

Licensed under the Apache License, Version 2.0.

See also

• Related project: Uuid25: 25-digit case-insensitive UUID encoding