geckoboard / pgulid

Universally Unique Lexicographically Sortable Identifier (ULID) for PostgreSQL

Universally Unique Lexicographically Sortable Identifier

A PostgreSQL (pgcrypto) implementation of alizain/ulid based on OK Log's Go port.

Background

A GUID/UUID can be suboptimal for many use-cases because:

• It isn't the most character efficient way of encoding 128 bits
• UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
• UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
• UUID v4 provides no other information than randomness which can cause fragmentation in many data structures

A ULID however:

• Is compatible with UUID/GUID's
• 1.21e+24 unique ULIDs per millisecond (1,208,925,819,614,629,174,706,176 to be exact)
• Lexicographically sortable
• Canonically encoded as a 26 character string, as opposed to the 36 character UUID
• Uses Crockford's base32 for better efficiency and readability (5 bits per character)
• Case insensitive
• No special characters (URL safe)
• Monotonic sort order (correctly detects and handles the same millisecond)

Usage

SELECT generate_ulid(); -- Output: 01D45VGTV648329YZFE7HYVGWC

Specification

Below is the current specification of ULID as implemented in this repository.

Components

Timestamp

• 48 bits
• UNIX-time in milliseconds
• Won't run out of space till the year 10895 AD

Entropy

• 80 bits

String Representation

 01AN4Z07BY      79KA1307SR9X4MV3
|----------|    |----------------|
 Timestamp           Entropy
  10 chars           16 chars
   48bits             80bits
   base32             base32

pgulid's Issues

Would you accept a PR to generate a ULID in UUID format?

I wrote the following, heavily inspired by what you already wrote:

CREATE FUNCTION public.generate_ulid() RETURNS uuid
    LANGUAGE plpgsql
    AS $$
DECLARE
  timestamp  BYTEA = E'\\000\\000\\000\\000\\000\\000';
  unix_time  BIGINT;
BEGIN
    unix_time = (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT;
    timestamp = SET_BYTE(timestamp, 3, (unix_time >> 40)::BIT(8)::INTEGER);
    timestamp = SET_BYTE(timestamp, 2, (unix_time >> 32)::BIT(8)::INTEGER);
    timestamp = SET_BYTE(timestamp, 1, (unix_time >> 24)::BIT(8)::INTEGER);
    timestamp = SET_BYTE(timestamp, 0, (unix_time >> 16)::BIT(8)::INTEGER);
    timestamp = SET_BYTE(timestamp, 5, (unix_time >> 8)::BIT(8)::INTEGER);
    timestamp = SET_BYTE(timestamp, 4, unix_time::BIT(8)::INTEGER);
    RETURN CAST(substring(CAST((timestamp || gen_random_bytes(10)) AS text) from 3) AS uuid);
END
$$;

It generates a ULID, but in the UUID format. The order of the bytes is a bit unintuitive due to the UUID format/endianness.

This function makes it easier to use the uuid PostGres type to hold ULIDs. This makes for smaller, faster indexes (c.f. indexing on text).

Adding a ULID type for easier use

Howdy thanks for creating this really useful function! To use this more easily, I ended up adding a new domain type for the text result of this function so it can be used more like the uuid type that its replacing. The one extra SQL statement I added:

create domain ulid as text 
default generate_ulid() 
not null 
constraint ulid_length_check check(char_length(value) = 26)
constraint ulid_upper_bound check(value<='7ZZZZZZZZZZZZZZZZZZZZZZZZZ');

this add a few standard checks for string length and sets the max value (per the ULID spec) to prevent invalid IDs from sneaking in. It also allows you to use the new ulid type in table creation statements in a clean way:

CREATE TABLE example_table
(
  id                        ulid primary key,
  ...other columns
);

Was gonna open a PR but since it is such a small change thought this might be easier to add to the discussion here.

Add License

Hello 👋🏼, would it be possible to add a LICENSE file to this repository (maybe using the same as is in the original js implementation)?

The code is extremely useful, but for some vendors it cannot be installed as a plugin (i.e., AWS Postgres), meaning we'd need to fork the code into a custom function, but not having a license makes that problematic.

Support monotonicity

Here is the link in the spec: https://github.com/ulid/spec#monotonicity

Without monotonic ULIDs one cannot truly sort by this key in a high-append rate situation.