UUIDv8

BEAM library for generating UUID versions 1, 4, 6, 7 and 8.

Core Erlang libraries have functions for secure random data, unique integer sequences, and distributed node names.

Showcases the flexibility of the UUID v8 standard:

uuid_v8_random/0 - as per uuid_v4/0 - not good for database index locality, but useful if your disconnected nodes need to generate unique random identifiers

Given these functions are so simple it is possible to just copy/paste the few required into your code rather than including this library.

Versions & Formats

There are 122 bits of usable data with 4 bits specifying the version and 2 the variant.

Which is normally formatted as:

aaaaaaaa-aaaa-vbbb-cccc-dddddddddddd

where v is the version.

This table shows the bit layout output by each UUID generator in the library:

generator	a	v	b	c	d
uuid_v8_random	random	8	random	random	random
uuid_v8_node	time	8	tag	node	sequence
uuid_v8_tag	time	8	tag	sequence	sequence
uuid_v7	time	7	sequence	random	random
uuid_v6	time hi	6	time	sequence	node
uuid_v4	random	4	random	random	random
uuid_v1	time low	1	time	sequence	node

Build

$ rebar3 compile

Test

$ rebar3 eunit

Erlang

Generate a hexadecimal tagged UUID:

UUID = binary:encode_hex(uuidv8:uuid_v8_node(16#81D))

Elixir integration

Generate a hexadecimal UUID from Elixir:

defmodule YourApp.Identifiers do
    import Base, only: [encode16: 1]
    defdelegate uuid_v8_random, to: :uuidv8

    def random_uuidv8_hex, do: encode16(uuid_v8_random())
end

See uuidv8_shim.ex for more delegates.

Gleam integration

Generate a hexadecimal UUID from Gleam:

import gleam/bit_array.{base16_encode}

pub fn random_uuid_v8_hex() -> String {
    base16_encode(uuid_v8_random())
}

@external(erlang, "uuidv8", "uuid_v8_random")
pub fn uuid_v8_random() -> BitArray

See uuidv8_shim.gleam for more externals.

UUID Versions

UUID v1

UUIDv1 is a time-based UUID featuring a 60-bit timestamp represented by Coordinated Universal Time (UTC) as a count of 100-nanosecond intervals since 1582-10-15T00:00:00.00Z. Not recommended, surpassed by UUIDv6.

Contains:

60 bits of timestamp (low bits first, not good for database indexing)
14 bits of monotonic integers
48 bits of node identifier (hash of BEAM node name)

./gen_uuid v1 4 
9cc76c44-0e93-11f1-8001-d6659d452b34
9cc839cb-0e93-11f1-8002-d6659d452b34
9cc83f02-0e93-11f1-8003-d6659d452b34
9cc84400-0e93-11f1-8004-d6659d452b34

UUID v4

UUIDv4 is meant for generating UUIDs from truly random or pseudorandom numbers.

Contains 122 bits of strong random bytes:

$ ./gen_uuid v4 2
9f33f7a7-b066-476c-8b82-6f9968d59e62
c30f8a24-96e7-4a56-8c46-f62488ae81fe

UUID v6

UUIDv6 is a field-compatible version of UUIDv1, reordered for improved DB locality. It is expected that UUIDv6 will primarily be implemented in contexts where UUIDv1 is used. Systems that do not involve legacy UUIDv1 SHOULD use UUIDv7 instead.

Contains:

60 bits of Gregorian monotonic timestamp (in microseconds)
14 bits of monotonic integers
48 bits of node identifier (hash of BEAM node name)

$ ./gen_uuid v6 16384
0e328083-bf10-65ff-8001-d6659d452b34
0e328083-bf11-6901-8002-d6659d452b34
0e328083-bf11-6947-8003-d6659d452b34
0e328083-bf11-69ad-8004-d6659d452b34
...
0e328083-e406-6968-bffd-d6659d452b34
0e328083-e406-6973-bffe-d6659d452b34
0e328083-e406-697e-bfff-d6659d452b34
0e328083-e406-6989-8000-d6659d452b34

UUID v7

UUIDv7 features a time-ordered value field derived from the widely implemented and well-known Unix Epoch timestamp source, the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded. Generally, UUIDv7 has improved entropy characteristics over UUIDv1.

Contains:

48 bits of monotonic UNIX timestamp
12 bits of monotonic unique integers
62 bits of strong random data

$ ./gen_uuid v7 4096
019c67db-6ef1-7001-abf4-7a13df92d388
019c67db-6ef1-7002-a744-5f1591749501
019c67db-6ef1-7003-b986-3d3035f199fa
...
019c67db-f691-7ffe-9335-b46d9c4cb789
019c67db-f691-7fff-af33-7e92e4441864
019c67db-f691-7000-b45c-31a2fce9aa3d

UUID v8

UUIDv8 provides a format for experimental or vendor-specific use cases

UUID v8 random

Contains 122 bits of strong random bytes:

$ ./gen_uuid v8 2          
578b3a94-6484-8f9d-8ae3-5337bd88ebfb
018a4bd7-a5f6-88a1-95c4-1bfdaec4c8a1

UUID v8 tagged

Contains:

48 bits of monotonic UNIX timestamp
12 bits of tag (3 hexadecimal digits)
62 bits of monotonic unique integers

$ ./gen_uuid v8 "0xD0C" 65536
019c6845-ba73-8d0c-b800-000000000025
019c6845-ba73-8d0c-b800-000000000045
019c6845-ba73-8d0c-b800-000000000065
019c6845-ba73-8d0c-b800-000000000085     
...     
019c6845-ba80-8d0c-b800-000000001fa5
019c6845-ba80-8d0c-b800-000000001fc5
019c6845-ba80-8d0c-b800-000000001fe5
019c6845-ba80-8d0c-b800-000000002005
...
019c6849-dd85-8d0c-b800-000000200401
019c6849-dd85-8d0c-b800-000000200421
019c6849-dd85-8d0c-b800-000000200441
019c6849-dd85-8d0c-b800-000000200461

UUID v8 node tagged

Contains:

48 bits of monotonic UNIX timestamp
12 bits of tag (3 hexadecimal digits)
32 bits of node identifier (hash of BEAM node name)
30 bits of monotonic unique integers

$ ./gen_uuid v8node "0xD8D" 65536 | tail
019c7c93-117d-8d8d-817c-a96500000466
019c7c93-117d-8d8d-817c-a96500000486
019c7c93-117d-8d8d-817c-a965000004a6
019c7c93-117d-8d8d-817c-a965000004c6
...
019c7c93-21ec-8d8d-817c-a965001e65a2
019c7c93-21ec-8d8d-817c-a965001e65c2
019c7c93-21ec-8d8d-817c-a965001e65e2
019c7c93-21ec-8d8d-817c-a965001e6602