hlid

README

HLID: Hexadecimal Lexicographically Sortable Identifier

Features

HLID strikes a good balance between security, efficiency, and usability:

• 128 bits: fits inside PostgreSQL's UUID type.
• Thanks to the 48 bit timestamp with 100 microsecond resolution, HLIDs are lexicographically sortable. This makes them efficient for database indexing. The timestamp won't overflow until 2861-12-16.
• 80 bits of cryptographically secure randomness makes HLIDs usable for secure tokens. You need to generate 155,885,281,596 HLIDs with the same timestamp to have a 1% chance of collision.
• HLIDs do not contain dashes. This makes HLIDs easier to copy.
• Hexadecimal encoding makes it possible to use HLIDs in PostgreSQL UUID queries without conversions.

Why not use ...?

• AUTO_INCREMENT/SERIAL
  • Predictable
  • Leaks number of rows
• UUIDv4:
  • Not lexicographically sortable
  • 6 bits "wasted" for version
  • Annoying dashes
• UUIDv7:
  • Lower resolution
  • 6 bits "wasted" for version
  • Annoying dashes
  • Not cryptographically secure depending on the implementation
• ULID:
  • Lower resolution
  • Text format not compatible with PostgreSQL's UUID type
  • Not cryptographically secure depending on the implementation
• KSUID:
  • 20 bytes; not compatible with PostgreSQL's UUID type

Installation

go get github.com/GitRowin/hlid-go

Usage

fmt.Println(hlid.New()) // Example output: 0fca27f9c9315480074ec17d90c3bd52

Documentation

Index

• type ID
  • func New() ID
  • func NewWithTime(t time.Time) ID
  • func (id ID) MarshalBinary() (b []byte, err error)
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) MarshalText() (b []byte, err error)
  • func (id *ID) Scan(value any) error
  • func (id ID) String() string
  • func (id *ID) UnmarshalBinary(b []byte) error
  • func (id *ID) UnmarshalJSON(b []byte) error
  • func (id *ID) UnmarshalText(b []byte) error
  • func (id ID) Value() (driver.Value, error)

Types

type ID

type ID [16]byte

func New

func New() ID

func NewWithTime

func NewWithTime(t time.Time) ID

func (ID) MarshalBinary

func (id ID) MarshalBinary() (b []byte, err error)

func (ID) MarshalJSON

func (id ID) MarshalJSON() ([]byte, error)

func (ID) MarshalText

func (id ID) MarshalText() (b []byte, err error)

func (*ID) Scan

func (id *ID) Scan(value any) error

func (ID) String

func (id ID) String() string

func (*ID) UnmarshalBinary

func (id *ID) UnmarshalBinary(b []byte) error

func (*ID) UnmarshalJSON

func (id *ID) UnmarshalJSON(b []byte) error

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(b []byte) error

func (ID) Value

func (id ID) Value() (driver.Value, error)