uulid

README

UULID Universally Unique Lexicographically Sortable Identifier

This package provides an implementation of the ULID spec compatible with the GUID/UUID format. It is based on the amazing oklog/ulid package, with the following differences:

• Small and simple API
• Encodes to a standard UUID format and can be used as the UUID type in databases
• More safer and strict as it doesn't allow the generation time to travel backwards
• A faster monotonic RNG that don't allocate memory unnecessarily
• Defaults to text instead of binary when using the sql/driver.Valuer interface

Install

This package requires Go modules.

go get github.com/brunotm/uulid

Usage

    id, err := uulid.New()
    if err != nil {
        // handle err
    }
    fmt.Println(id.String()) // Output: 0178a727-335d-db2d-4671-c5c757718d7c

Test

go test ./...

Command line tool

This repo also provides a tool to generate and parse UULIDs at the command line.

go get -v github.com/brunotm/ulid/cmd/uulid

Usage:

Usage of uulid:
  -local
        when parsing, show local time instead of UTC
  -p string
        parse the given uulid

Specification

Timestamp

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

Entropy

• 80 bits
• Monotonicity within the same millisecond

Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Encoding String Representation

This package encodes the ULID into the standard UUID format. (The ULID spec uses Crockford's Base32)

UULID: 0178a73c-3cc0-71ab-74b4-cc6c7190deae

 0178a73c3cc0      71ab74b4cc6c7190deae
|------------|    |--------------------|
   Timestamp             Entropy
    12 chars             20 chars
     48bits               80bits
     base32               base32

Prior Art

• oklog/ulid
• alizain/ulid
• RobThree/NUlid
• imdario/go-ulid

Documentation

Overview

Package uulid provides an UUID compatible ULID

Index

• Constants
• Variables
• func MaxTime() (t time.Time)
• func Time(ms uint64) (t time.Time)
• func Timestamp(t time.Time) (ms uint64)
• type Generator
  • func NewGenerator() (r *Generator, err error)
  • func NewGeneratorWithSeed(seed uint64) (r *Generator)
  • func (r *Generator) New() (id UULID, err error)
• type UULID
  • func New() (id UULID, err error)
  • func Parse(data []byte) (id UULID, err error)
  • func (id UULID) Compare(other UULID) (i int)
  • func (id UULID) Entropy() (data []byte)
  • func (id UULID) MarshalBinary() (data []byte, err error)
  • func (id UULID) MarshalBinaryTo(dst []byte) (err error)
  • func (id UULID) MarshalText() (data []byte, err error)
  • func (id UULID) MarshalTextTo(dst []byte) (err error)
  • func (id *UULID) Scan(src interface{}) (err error)
  • func (id *UULID) SetEntropy(e []byte) (err error)
  • func (id *UULID) SetTime(t time.Time) (err error)
  • func (id *UULID) SetTimestamp(ms uint64) (err error)
  • func (id *UULID) String() (s string)
  • func (id UULID) Time() time.Time
  • func (id UULID) Timestamp() uint64
  • func (id *UULID) UnmarshalBinary(data []byte) (err error)
  • func (id *UULID) UnmarshalText(data []byte) (err error)
  • func (id UULID) Value() (v driver.Value, err error)

Constants

const (
	MaxTimestamp   = 281474976710655
	HexEncodedSize = 36
	BinarySize     = 16
)

Variables

var (

	// ErrBigTime is returned if the given time that is larger than MaxTimestamp.
	ErrBigTime = errors.New("uulid: time greater than supported by the ulid spec")

	// ErrDataSize is returned when parsing an invalid string representation of a UULID.
	ErrDataSize = errors.New("uulid: bad data size when parsing")

	// ErrBufferSize is returned when marshalling an UULID to a buffer < 36 bytes.
	ErrBufferSize = errors.New("uulid: bad buffer size when marshaling")

	// ErrInvalidType is returned when scan receives an invalid type.
	ErrInvalidType = errors.New("uulid: invalid type to unmarshal")

	// ErrMonotonicOverflow is returned if the current 10bit entropy overflows.
	ErrMonotonicOverflow = errors.New("uulid: monotonic overflow")

	// ErrSmallTime is returned if the current epoch time is lower than the previously seen
	// by the Generator.
	ErrSmallTime = errors.New("uulid: time is lower than current generator")
)

Functions

func MaxTime

func MaxTime() (t time.Time)

MaxTime returns the maximum time supported by an UULID

func Time

func Time(ms uint64) (t time.Time)

Time converts Unix milliseconds in the format returned by the Timestamp function to a time.Time.

func Timestamp

func Timestamp(t time.Time) (ms uint64)

Timestamp converts a time.Time to Unix milliseconds. Times from the year 10889 produces undefined results.

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator implements an UUID generator based on the ULID spec. The generated UULID is monotonically increased for calls within the same millisecond.

func NewGenerator

func NewGenerator() (r *Generator, err error)

NewGenerator is like NewGeneratorWithSeed() but uses a secure random seed from crypto/rand.

func NewGeneratorWithSeed

func NewGeneratorWithSeed(seed uint64) (r *Generator)

NewGeneratorWithSeed creates a new UULID generator. It will used the given as the seed for the internal monotonic RNG.

Ensure that a good random seed is used or use NewGenerator() which provides a secure seed from crypto/rand.

func (*Generator) New

func (r *Generator) New() (id UULID, err error)

New creates a UULID with the current system time.

type UULID

type UULID [BinarySize]byte

An UULID is a 16 byte Universally Unique Lexicographically Sortable Identifier

The components are encoded as 16 octets.
Each component is encoded with the MSB first (network byte order).

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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func New

func New() (id UULID, err error)

func Parse

func Parse(data []byte) (id UULID, err error)

Parse parses an encoded UULID, returning an error in case of failure.

ErrDataSize is returned if the length is different from an encoded UULID valid lengths, either 32 or 36 characters.

ErrBigTime is returned if time is greater than MaxTime().

func (UULID) Compare

func (id UULID) Compare(other UULID) (i int)

Compare returns an integer comparing id and other lexicographically. The result will be 0 if id==other, -1 if id < other, and +1 if id > other.

func (UULID) Entropy

func (id UULID) Entropy() (data []byte)

Entropy returns the entropy from the UULID.

func (UULID) MarshalBinary

func (id UULID) MarshalBinary() (data []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface

func (UULID) MarshalBinaryTo

func (id UULID) MarshalBinaryTo(dst []byte) (err error)

MarshalBinaryTo writes the binary encoding of the ULID to the given buffer. ErrBufferSize is returned when the len(dst) != 16.

func (UULID) MarshalText

func (id UULID) MarshalText() (data []byte, err error)

MarshalText implements the encoding.TextMarshaler interface.

func (UULID) MarshalTextTo

func (id UULID) MarshalTextTo(dst []byte) (err error)

MarshalTextTo writes the UULID as a string to the given buffer. ErrBufferSize is returned when the len(dst) != EncodedSize.

func (*UULID) Scan

func (id *UULID) Scan(src interface{}) (err error)

Scan implements the sql.Scanner interface. It supports scanning a string or byte slice.

func (*UULID) SetEntropy

func (id *UULID) SetEntropy(e []byte) (err error)

SetEntropy sets the ULID entropy to the passed byte slice.

func (*UULID) SetTime

func (id *UULID) SetTime(t time.Time) (err error)

SetTime sets the time component of the ULID to the given time.Time.

func (*UULID) SetTimestamp

func (id *UULID) SetTimestamp(ms uint64) (err error)

SetTimestamp sets the time component of the ULID to the given Unix time in milliseconds.

func (*UULID) String

func (id *UULID) String() (s string)

String returns the string encoded UULID

func (UULID) Time

func (id UULID) Time() time.Time

Time returns the UULID time component with a millisecond precision

func (UULID) Timestamp

func (id UULID) Timestamp() uint64

Timestamp return the UULID millisecond unix timestamp

func (*UULID) UnmarshalBinary

func (id *UULID) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*UULID) UnmarshalText

func (id *UULID) UnmarshalText(data []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (UULID) Value

func (id UULID) Value() (v driver.Value, err error)

Value implements the sql/driver.Valuer