DOCSEARCHbyAlgolia
Submit Docs

xid Go Library

repository·master·Indexed 26 days ago

https://github.com/rs/xid

A globally unique ID generator for Go that produces 12-byte, K-ordered, and sortable IDs. It provides a compact 20-character base32hex string representation and supports extracting embedded metadata such as timestamps, machine identifiers, and process IDs. The library implements database/sql/driver.Valuer and sql.Scanner for SQL database integration and allows machine ID configuration via the XID_MACHINE_ID environment variable.

Tokens
858
Snippets
3
Records
13
Agent score
87%

What's inside xid

  1. Store XIDs in binary format for data size optimization

    master
    The xid package provides subpackage functionality to store XIDs in a binary format (12 bytes) rather than as strings. This is useful for optimizing storage space in databases where storing the raw bytes is more efficient than the string representation.

  3. Configure Machine ID via environment variable

    master
    By default, xid uses a 3-byte machine identifier. You can fine-tune control over the generation by setting the XID_MACHINE_ID environment variable.

  4. Important security and validation notes for xid

    master

    Security Warning

    xid is not cryptographically secure. It depends on system time and a monotonic counter. If your application requires unpredictable IDs (e.g., for security tokens), use a library that relies on cryptographically secure sources like crypto/rand.

    Validation

    To validate an xid string, ensure it is a 20-character long, all lowercase sequence of a through v and 0 through 9. The regex pattern is: [0-9a-v]{20}.

  5. Generate and use xid

    master

    Use xid.New() to generate a new globally unique ID. The ID can be converted to a 20-character base32hex string using the .String() method. Xids are K-ordered, sortable, and contain embedded time information.

    guid := xid.New()

println(guid.String())
// Output: 9m4e2mr0ui3e8a215n4g

  6. Extract embedded information from an xid

    master

    An xid contains embedded metadata that can be extracted using specific methods. This allows you to retrieve the machine identifier, process ID, timestamp, and the internal counter used during generation.

    guid.Machine()
guid.Pid()
guid.Time()
guid.Counter()

  7. Configure the machine ID via environment variable

    master
    By default, xid derives a machine ID from platform-specific values, the hostname, or a random number. You can override this by setting the XID_MACHINE_ID environment variable to a number between 0 and 16777215 (0xFFFFFF). This number is encoded as a 3-byte big-endian value.

  8. Sort a slice of Xids

    master
    To sort a slice of xid.ID in place, use the xid.Sort(ids []ID) function. This performs a comparison based on the underlying byte values, which preserves the K-ordered property of the IDs.

  9. Extract components from an Xid

    master

    Once you have an ID, you can extract its constituent parts:

    • id.Time(): Returns the time.Time embedded in the ID (1-second precision).
    • id.Machine(): Returns the 3-byte machine identifier.
    • id.Pid(): Returns the 2-byte process ID as a uint16.
    • id.Counter(): Returns the 3-byte incrementing counter as an int32.

  10. Use Xid with SQL databases

    master

    The ID type implements database/sql/driver.Valuer and sql.Scanner.

    • When saving to a database, it marshals to its 20-character base32 string representation.
    • When scanning from a database, it supports both string (base32) and []byte (raw 12-byte) formats.

  11. Convert strings or bytes to Xid

    master
    To reconstruct an ID from its string representation (20-character base32 hex) or its raw byte representation (12 bytes), use xid.FromString(s string) or xid.FromBytes(b []byte).

  12. Generate a new Xid

    master
    Use xid.New() to generate a globally unique, K-ordered 12-byte ID. For specific timestamp control, use xid.NewWithTime(t time.Time). The generated ID contains a 4-byte timestamp, a 3-byte machine identifier, a 2-byte process ID, and a 3-byte counter.