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 MustParse(s string) ID
  • func New() ID
  • func NewWithTime(t time.Time) ID
  • func Parse(s string) (ID, error)
  • func (id ID) MarshalBinary() ([]byte, error)
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) MarshalText() ([]byte, 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 MustParse

func MustParse(s string) ID

func New

func New() ID

func NewWithTime

func NewWithTime(t time.Time) ID

func Parse

func Parse(s string) (ID, error)

func (ID) MarshalBinary

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

func (ID) MarshalJSON

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

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, 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)