The highest tagged major version is
README
¶
squuid
Minimal sortable, query-friendly, URL-safe universally unique identifiers for SQL and APIs with an opinionated API and string encoding.
Install
go get -u codeberg.org/0x5a17ed/squuid@latest
Rationale
SQUUID is designed for:
- lexicographically sortable IDs with time-ordered generation,
- compact text transport (26 chars),
- first-class HTTP APIs, SQL and pgx integration.
API Usage
id, err := squuid.New()
if err != nil {
// handle error
}
s := id.String()
parsed, err := squuid.ParseString(s)
if err != nil {
// handle parse error
}
_ = parsed.Equal(id) // true
database/sql Usage
// Configure once at startup.
squuid.SetSQLDialect(squuid.DialectUUID) // canonical text
id, _ := squuid.New()
v, _ := id.Value() // driver.Value for inserts/updates
_ = v
var scanned squuid.SQUUID
_ = scanned.Scan("01020304-0506-0708-090a-0b0c0d0e0f10")
License
0BSD
Documentation
¶
Overview ¶
Package squuid implements SQUUIDs: sortable, query-friendly, URL-safe identifiers designed for use in APIs and databases.
A SQUUID has a canonical textual form based on a customized base32-hex alphabet. The encoding is URL-safe, padding-free, and chosen so that the natural lexicographic order of the string matches the identifier’s chronological order. This makes SQUUIDs pleasant to store, compare, and sort as text while remaining compact and human-friendly.
The package generates new identifiers using a time-ordered scheme by default, so freshly created values sort after older ones. It also provides fast parsing and formatting, implements encoding.TextMarshaler and encoding.TextUnmarshaler for integrating with serializers such as JSON and YAML, and integrates with the database/sql stdlib package and pgx for seamless scanning and valuing.
Index ¶
- Constants
- Variables
- type Dialect
- type NullSQUUID
- type SQUUID
- func (u SQUUID) Bytes() []byte
- func (u SQUUID) Canonical() string
- func (u SQUUID) Compare(v SQUUID) int
- func (u SQUUID) Equal(v SQUUID) bool
- func (u SQUUID) GoString() string
- func (u SQUUID) Hex() string
- func (u SQUUID) IsZero() bool
- func (u SQUUID) MarshalText() ([]byte, error)
- func (u *SQUUID) Scan(src any) (err error)
- func (u SQUUID) String() string
- func (u *SQUUID) UnmarshalText(b []byte) error
- func (u SQUUID) Value() (driver.Value, error)
Constants ¶
const Alphabet = "0123456789ABCDEFGHJKMNPQRSTUWXYZ"
const Size = 16
Variables ¶
var ( ErrBadLength = errors.New("bad length") ErrBadFormat = errors.New("bad format") ErrBadDialect = errors.New("bad dialect") )
var DefaultSQLDialect = DialectUUID
DefaultSQLDialect is used by (SQUUID).Value() for database/sql. Set this once at program startup (or per test).
var Encoding = base32.NewEncoding(Alphabet).WithPadding(base32.NoPadding)
Functions ¶
This section is empty.
Types ¶
type Dialect ¶
type Dialect byte
Dialect controls how SQUUID values are written via driver.Valuer (database/sql).
const ( // DialectUUID writes canonical text; use a column type UUID. DialectUUID Dialect = iota // DialectHex writes the 32-char hex string; use CHAR(32)/TEXT. DialectHex // DialectSQUUID writes the squuid encoded string; use CHAR(26)/TEXT. DialectSQUUID // DialectBlob writes []byte(16); use BINARY(16) (MySQL/MariaDB) or BLOB (SQLite). DialectBlob // DialectUInt128Decimal writes a base-10 string of the unsigned 128-bit value. // Use a DECIMAL(39,0) / NUMERIC(39,0) column (where supported). DialectUInt128Decimal )
func SetSQLDialect ¶
SetSQLDialect is a convenience setter for the default SQL dialect. Returns the old value.
type NullSQUUID ¶
func NullSQUUIDFromSQUUID ¶
func NullSQUUIDFromSQUUID(v SQUUID) NullSQUUID
func (*NullSQUUID) Scan ¶
func (n *NullSQUUID) Scan(src any) (err error)
Scan implements sql.Scanner.
type SQUUID ¶
SQUUID represents a sortable, query-friendly, URL-safe universally unique identifier as a 16-byte array.
func FromBytes ¶
FromBytes converts a 16-byte slice into a SQUUID.
Contract:
- requires len(b) == 16, otherwise returns ErrBadLength
- returns a value copy independent from the caller's slice
func New ¶
New returns a new SQUUID value using a UUIDv7-compatible time and random bits based generator.
func ParseString ¶
ParseString parses a strict 26-character SQUUID text string into a SQUUID.
Contract:
- expects the package alphabet and no padding
- rejects invalid characters
- returns ErrBadLength when decoded byte length is not 16
func (SQUUID) Canonical ¶
Canonical returns the canonical text form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
func (SQUUID) Compare ¶
Compare returns an integer comparing two SQUUIDs lexicographically. The result will be 0 if a == b, -1 if a < b, and +1 if a > b.
func (SQUUID) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (SQUUID) String ¶
String returns a lexicographically sortable string encoded SQUUID (26 characters, non-standard base 32) e.g. 01AN4Z07BY79KA1307SR9X4MV3.
func (*SQUUID) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
Source Files