uuidv7

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2026 License: MIT Imports: 10 Imported by: 1

README

go-loghub-uuidv7

ci

Biblioteca Go leve e rápida dedicada ao UUIDv7 (RFC 9562) com três níveis de precisão temporal, nos dois sentidos: gerar o identificador com milissegundos, microssegundos ou nanossegundos embutidos, e converter o UUIDv7 de volta em instante, na mesma precisão.

  • Rápida: geração binária em dezenas de nanossegundos, zero alocações, mais de 11 mil UUIDs/ms por núcleo (em VM modesta).
  • Concorrente: um único Generator criado no boot atende centenas de goroutines sem trava global.
  • Sem dependências: apenas a biblioteca padrão do Go.
  • Multinível: do milissegundo padrão até nanossegundos embutidos.
  • Leitura de tempo segura: um UUID de outra versão é recusado com ErrNotV7, em vez de virar uma data sem sentido.
  • Consultável por intervalo: MinAt, MaxAt e RangeAt dão os UUIDs que delimitam uma janela de tempo, para responder a ela com o índice da própria chave primária, sem coluna nem índice de carimbo.
  • Integrável: análise permissiva de texto, serialização em JSON e integração com database/sql, inclusive em coluna binária de 16 bytes.

Só a versão 7 é tratada. As demais versões da RFC 9562 (1, 2, 3, 4, 5, 6 e 8) estão na biblioteca de origem deste projeto, go-loghub-uuid.

Níveis

Nível Precisão embutida Compatível UUIDv7 Bits aleatórios
Level1 milissegundos (padrão) Sim 74
Level2 + microssegundos em rand_a Sim 62
Level3 + nanossegundos em rand_b Sim 52

Todos preservam versão 7 e variante RFC.

Os microssegundos e os nanossegundos são gravados como contagens decimais de 0 a 999, e não como a fração binária do Método 3 da RFC 9562. Qualquer biblioteca lê o milissegundo destes identificadores; o sub-milissegundo só esta biblioteca, ou uma implementação da especificação, lê corretamente. O motivo está em docs/10-decisoes.md §3.

Gerar

Função O que devolve
Generate(nível) o UUIDv7 binário ([16]byte) do instante atual
GenerateString(nível) o mesmo, já na string canônica
GenerateV7() o UUIDv7 padrão da RFC: Generate(Level1)
GenerateV7Level1..3() os três níveis pelo nome, sem argumento
GenerateAt(nível, instante) um UUIDv7 para um instante que você informa

Todas existem também como métodos do Generator.

Converter em instante

u, _ := uuidv7.FromString("019b76da-a87b-71c8-b150-000000000000") // gravado em Nível 3

t, ok := u.TimestampWithLevel(uuidv7.Level3)
// t = 2026-01-01T00:00:00.123456789Z, ok = true

campos, err := uuidv7.ImportBinary(u)
// campos = {Seconds:1767225600 Milliseconds:123 Microseconds:456 Nanoseconds:789}, err = nil

O nível não pode ser deduzido do UUID: quem lê informa o nível com que a coluna foi gravada. TimestampWithLevel descarta os campos abaixo do milissegundo que não podem ser tempo (fora de 0 a 999), e Import e ImportBinary devolvem os campos crus.

As quatro leituras de tempo (Import, ImportBinary, Timestamp e TimestampWithLevel) recusam qualquer UUID que não seja de versão 7 com a variante da RFC: as duas primeiras com ErrNotV7, as duas últimas com false. A análise de texto (FromString, Parse, Scan, JSON) confere só a forma; para exigir a versão logo na entrada, use u.IsValid().

Consulta por intervalo de tempo

É o motivo prático de usar UUIDv7 como chave primária. O índice da chave já está em ordem cronológica, então uma janela de tempo vira varredura de faixa:

lo, hi := uuidv7.RangeAt(uuidv7.Level2, inicio, fim)

rows, err := db.Query(
	"SELECT id, corpo FROM eventos WHERE id >= $1 AND id < $2 ORDER BY id",
	lo.String(), hi.String(),
)

RangeAt devolve o intervalo semiaberto [inicio, fim). Para as fronteiras separadas, MinAt e MaxAt. As três respeitam o nível: no Nível 2 o campo rand_a carrega os microssegundos reais do instante, e zerá-lo daria uma fronteira errada.

Para gravar a chave de um instante conhecido, ao reprocessar um histórico, GenerateAt(nível, instante) gera com o tempo que você informa, preservando a ordenação da chave.

A fronteira só vale para UUIDs gravados no mesmo nível. Misturar níveis na mesma coluna faz a consulta devolver linhas a menos, sem erro nenhum. Detalhes em docs/04-construcao-por-instante.md §3.

Instalação

go get github.com/patrickbrandao/go-loghub-uuidv7

Uso rápido no Linux

Instalar Go (é necessário Go 1.22 ou superior; confira com go version — se a distribuição empacotar versão inferior, use o instalador oficial):

apt-get update;
apt-get install -y golang-go;

Arquivo go.mod:

module uuid-test

go 1.22

require github.com/patrickbrandao/go-loghub-uuidv7 v0.0.3

O require acima é preenchido automaticamente pelo go get mostrado na seção de compilação; declará-lo à mão é opcional.

Arquivo test-uuid.go:

package main

import (
	"fmt"

	"github.com/patrickbrandao/go-loghub-uuidv7"
)

func main() {
	// Gera um UUIDv7 em string (gerador padrão interno, pronto para uso).
	fmt.Println(uuidv7.GenerateString(uuidv7.Level1))
	// ex.: 019e99e3-42f0-7882-9719-2305ff84949c
}

Compilar:

go mod download;
go build -o test-uuid test-uuid.go;

Compilar (alternativa):

go get github.com/patrickbrandao/go-loghub-uuidv7@latest;
go mod tidy;
go build -o test-uuid test-uuid.go;

Compilar (multi plataforma):

# Windows
GOOS=windows GOARCH=amd64 go build -o test-uuid.exe test-uuid.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o test-uuid test-uuid.go

# Linux (outros processadores)
GOOS=linux GOARCH=arm64 go build -o test-uuid test-uuid.go

Rodar:

./test-uuid;
    # 019e9ace-a992-79d2-9460-e33944a68428

Em serviços de alto volume, crie um gerador no boot e reutilize:

var Gen = uuidv7.NewGenerator()

func newID() string { return Gen.GenerateString(uuidv7.Level3) }

Aviso de segurança

O gerador padrão (NewGenerator, e as funções de pacote Generate, GenerateString, GenerateAt, GenerateV7 e GenerateV7Level1 a GenerateV7Level3) tira entropia do gerador do runtime do Go, uma instância de ChaCha8 por thread semeada pelo sistema operacional. É uma cifra de fluxo, resistente a predição, mas a própria documentação do Go recomenda crypto/rand para uso sensível a segurança. E, independentemente da fonte, todo UUIDv7 expõe o instante de criação por construção.

Não use estes UUIDs como segredo — token de sessão, link privado, chave de recuperação ou senha de uso único. Para identificadores que precisem ser inadivinháveis, monte o gerador com entropia criptográfica:

var Gen = uuidv7.NewCryptoGenerator()

NewGeneratorWithReader aceita qualquer io.Reader seguro para uso concorrente, e NewGeneratorWith aceita uma função que devolve 64 bits.

Como identificador de registro, chave primária ou correlação de log — o uso a que a biblioteca se destina — o gerador padrão é adequado.

Mais

Licença

MIT.

Documentation

Overview

Pacote uuidv7 implementa a geração e a leitura de identificadores UUIDv7 (RFC 9562) com três níveis de precisão temporal.

O UUIDv7 é um identificador de 128 bits ordenável no tempo: os bits mais significativos carregam o instante de criação, de modo que a ordenação lexicográfica das strings coincide com a ordem cronológica.

Esta biblioteca estende o padrão guardando precisão sub-milissegundo dentro dos campos "aleatórios" do UUID, em três níveis: 

Level1: apenas milissegundos (48 bits padrão). rand_a e rand_b
        totalmente aleatórios. Compatível 100% com UUIDv7 comum.

Level2: invade rand_a (12 bits) para guardar os microssegundos
        (0-999) do instante. rand_b continua aleatório.

Level3: invade rand_a para os microssegundos e ocupa os 10 bits
        mais altos de rand_b para os nanossegundos (0-999). Os
        52 bits restantes de rand_b continuam aleatórios.

Em todos os níveis a versão (7) e a variante (RFC) são preservadas, portanto o resultado é sempre um UUIDv7 válido.

O sentido inverso também é coberto: Import, ImportBinary e TimestampWithLevel devolvem o instante gravado, na precisão do nível, e recusam com ErrNotV7 qualquer UUID que não seja de versão 7.

A biblioteca trata somente a versão 7. As demais versões da RFC 9562 não são geradas nem interpretadas.

Concorrência: o tipo Generator é seguro para uso simultâneo por centenas de goroutines. Crie um único Generator no boot da aplicação (ou use as funções de pacote, que usam um gerador padrão interno).

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidLength indica comprimento incompatível com todos os
	// formatos aceitos.
	ErrInvalidLength error = &formatError{"uuidv7: comprimento inválido para string de UUID"}

	// ErrInvalidBrackets indica a forma entre chaves malformada.
	ErrInvalidBrackets error = &formatError{"uuidv7: chaves inválidas em string de UUID"}
)

Erros mais específicos devolvidos por Parse e ParseBytes. Todos embrulham ErrInvalidFormat, portanto errors.Is(err, ErrInvalidFormat) é verdadeiro para qualquer um deles, e quem só trata o sentinela não precisa conhecê-los.

FromString e StringToBinary não os usam: devolvem exatamente ErrInvalidFormat em toda recusa, inclusive para comparação direta com o operador de igualdade. Ver docs/05-conversao-e-analise.md seção 5.

View Source 
var ErrEntropySource = errors.New("uuidv7: falha ao ler da fonte de entropia")

ErrEntropySource indica que a fonte de entropia informada pelo chamador não conseguiu entregar os bytes pedidos.

View Source 
var ErrInvalidFormat = errors.New("uuidv7: string de UUID em formato inválido")

ErrInvalidFormat indica que a string fornecida não está no formato canônico de UUID (8-4-4-4-12 dígitos hexadecimais).

View Source 
var ErrInvalidScanType = errors.New("uuidv7: tipo não suportado na leitura de UUID")

ErrInvalidScanType indica que o valor lido do banco não é conversível para UUID.

View Source 
var ErrNotV7 = errors.New("uuidv7: o UUID não é da versão 7 com a variante da RFC 9562")

ErrNotV7 indica que o UUID lido tem forma válida, mas não é um UUIDv7: a versão é diferente de 7, ou a variante é diferente da RFC 9562 (0b10). As leituras de tempo o devolvem em vez de interpretar como instante bits que não foram gravados como tal.

Não embrulha ErrInvalidFormat: o texto foi aceito, e a recusa é sobre o conteúdo, não sobre a forma. Nil é recusado com este erro, porque não carrega versão nem variante.

Functions

func BinaryToString 

func BinaryToString(u UUID) string

BinaryToString é um apelido explícito para o método String(): converte o binário de 128 bits na string canônica.

func GenerateAtString 

func GenerateAtString(level Level, t time.Time) string

GenerateAtString produz, para o instante informado, um UUIDv7 em string usando o gerador padrão do pacote.

func GenerateString 

func GenerateString(level Level) string

GenerateString produz um UUID em string usando o gerador padrão do pacote.

Example

A forma mais curta: as funções de pacote usam um gerador padrão interno, já pronto e seguro para concorrência. 

s1 := uuidv7.GenerateString(uuidv7.Level1) // só milissegundos (UUIDv7 padrão)
s2 := uuidv7.GenerateString(uuidv7.Level2) // até microssegundos (rand_a)
s3 := uuidv7.GenerateString(uuidv7.Level3) // até nanossegundos (rand_a + rand_b)
fmt.Println(len(s1), len(s2), len(s3))

Output:
36 36 36

func Validate 

func Validate(s string) error

Validate informa se a string é um UUID em algum dos formatos aceitos por Parse, devolvendo apenas o erro.

Types

type BinaryUUID 

type BinaryUUID UUID

BinaryUUID é um UUID que se entrega ao banco de dados como 16 bytes crus, em ordem de rede, em vez da string canônica de 36 caracteres.

Existe porque a integração padrão é assimétrica de propósito: Scan já aceita 16 bytes crus na leitura, mas Value sempre escreve texto, e mudar Value quebraria em silêncio quem já tem texto gravado — dados novos deixariam de casar com os antigos na mesma coluna.

Use quando a coluna for BINARY(16) ou BLOB, o que é o habitual em MySQL, MariaDB e SQLite, onde não existe tipo nativo de UUID e a forma binária economiza mais da metade do espaço por linha, replicado em todo índice secundário que referencie a chave. No PostgreSQL o tipo uuid é nativo e o driver converte o texto, então não há ganho.

A escolha é por conversão no ponto da consulta, sem estado global e sem efeito sobre quem não usa: 

_, err := db.Exec(
    "INSERT INTO eventos (id, corpo) VALUES (?, ?)",
    uuidv7.BinaryUUID(u), corpo,
)

A ordem dos bytes é a de rede, a mesma de MarshalBinary. Algumas receitas de MySQL sugerem rotacionar os campos do identificador para melhorar a localidade do índice; não faça isso aqui. O UUIDv7 já nasce ordenado, e o valor rotacionado não seria lido por nenhuma outra ferramenta.

func (BinaryUUID) MarshalBinary 

func (u BinaryUUID) MarshalBinary() ([]byte, error)

MarshalBinary entrega os 16 bytes crus em ordem de rede.

func (BinaryUUID) MarshalText 

func (u BinaryUUID) MarshalText() ([]byte, error)

MarshalText devolve a forma canônica, como em UUID, para que o tipo participe de encoding/json e encoding/gob como string.

func (*BinaryUUID) Scan 

func (u *BinaryUUID) Scan(src any) error

Scan lê um UUID vindo do banco, implementando sql.Scanner. Delega ao Scan de UUID, portanto aceita as mesmas formas: NULL, texto em qualquer formato de Parse, e 16 bytes crus.

Ler por BinaryUUID não exige que a coluna seja binária: o tipo existe para a escrita, e a leitura continua aceitando as duas formas.

func (BinaryUUID) String 

func (u BinaryUUID) String() string

String devolve a forma canônica, como em UUID. Existe para que um BinaryUUID em mensagem de log ou de erro apareça legível, e não como vetor de bytes.

func (*BinaryUUID) UnmarshalBinary 

func (u *BinaryUUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê exatamente 16 bytes crus em ordem de rede.

func (*BinaryUUID) UnmarshalText 

func (u *BinaryUUID) UnmarshalText(data []byte) error

UnmarshalText lê a forma canônica, aceitando os formatos de Parse.

func (BinaryUUID) Value 

func (u BinaryUUID) Value() (driver.Value, error)

Value entrega os 16 bytes ao banco, implementando driver.Valuer.

Aloca a fatia devolvida, porque driver.Value é uma interface e o driver pode reter o valor depois do retorno. É uma alocação por parâmetro de consulta, não por identificador gerado.

type Generator 

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

Generator é o objeto que produz UUIDs. Deve ser criado uma única vez, no boot da aplicação, e pode ser compartilhado por muitas goroutines.

O gerador padrão tira entropia do gerador do runtime do Go (ChaCha8, uma instância por thread, semeada pelo sistema operacional), que não tem trava compartilhada e permite gerar milhões de IDs por segundo.

O valor zero de Generator NÃO é utilizável: use NewGenerator ou NewGeneratorWith. Por segurança, um Generator sem fonte de entropia (valor zero, ou ponteiro nulo) recorre ao gerador padrão do pacote em vez de entrar em pânico.

func NewCryptoGenerator 

func NewCryptoGenerator() *Generator

NewCryptoGenerator cria um Generator cuja entropia vem inteiramente de crypto/rand, tornando os bits aleatórios imprevisíveis.

É mais lento que NewGenerator, que lê do gerador do runtime. Use este quando o identificador precisar resistir a quem tenta adivinhar o próximo valor. Lembre-se de que, mesmo assim, todo UUIDv7 revela o instante de criação por construção.

Example

NewCryptoGenerator monta um gerador cuja entropia vem inteiramente de crypto/rand, para identificadores que precisem ser inadivinháveis. O gerador padrão é mais rápido, mas a recomendação para segredos continua sendo crypto/rand. 

gen := uuidv7.NewCryptoGenerator()

u := gen.Generate(uuidv7.Level1)
fmt.Println(u.Version(), u.Variant())

Output:
7 2

func NewGenerator 

func NewGenerator() *Generator

NewGenerator cria um Generator rápido e seguro para concorrência.

A entropia em tempo de execução vem das funções de pacote de math/rand/v2, que desde o Go 1.22 leem do gerador do runtime: uma instância de ChaCha8 por thread, semeada pelo sistema operacional na carga do programa. Não há trava compartilhada nem estado a manter, e a leitura é mais barata que a de um pool.

ATENÇÃO — o ChaCha8 é uma cifra de fluxo e resiste a predição, mas a própria documentação do Go recomenda crypto/rand para uso sensível a segurança. Além disso, todo UUIDv7 expõe o instante de criação por construção, independentemente da fonte de entropia. Não use estes identificadores como segredo (token de sessão, link privado, chave de recuperação); para esse fim, use NewCryptoGenerator ou monte o gerador com NewGeneratorWith.

func NewGeneratorWith 

func NewGeneratorWith(source func() uint64) *Generator

NewGeneratorWith cria um Generator usando uma fonte de aleatoriedade personalizada. A função "source" deve devolver 64 bits aleatórios e PRECISA ser segura para uso concorrente (ela será chamada por várias goroutines ao mesmo tempo).

Use isto, por exemplo, para forçar entropia criptográfica (crypto/rand) em todas as gerações, abrindo mão de parte da velocidade em troca de imprevisibilidade total.

A fonte é chamada uma única vez por UUID nos níveis 2 e 3 (onde rand_a carrega o tempo) e duas vezes no nível 1.

Entra em pânico se source for nula: é um erro de configuração, que deve aparecer no boot e não na primeira geração.

func NewGeneratorWithReader 

func NewGeneratorWithReader(reader io.Reader) *Generator

NewGeneratorWithReader cria um Generator que retira entropia de um io.Reader, formato usual das fontes da biblioteca padrão.

O leitor PRECISA ser seguro para uso concorrente, porque será chamado por várias goroutines ao mesmo tempo. crypto/rand.Reader satisfaz esse requisito.

Entra em pânico se reader for nulo, e também se uma leitura falhar durante a geração: uma fonte de entropia quebrada não pode degradar em silêncio para um gerador previsível.

Para a fonte criptográfica padrão, prefira NewCryptoGenerator.

func (*Generator) Generate 

func (g *Generator) Generate(level Level) UUID

Generate produz um UUID binário (128 bits) do nível informado, usando o instante atual (time.Now). Níveis desconhecidos são tratados como Level1 (totalmente padrão).

Layout dos 16 bytes (big-endian): 

bytes 0..5 : unix_ts_ms .......... 48 bits  (milissegundos desde epoch)
byte  6    : 0x7_ | rand_a[11:8] . versão(4) + 4 bits altos de rand_a
byte  7    : rand_a[7:0] ......... 8 bits baixos de rand_a (total 12 bits)
byte  8    : 10_ | rand_b[61:56] . variante(2) + 6 bits altos de rand_b
bytes 9..15: rand_b[55:0] ........ 56 bits restantes de rand_b (total 62 bits)

Onde, conforme o nível: 

rand_a (12 bits) = microssegundos (0-999) nos níveis 2 e 3; aleatório no nível 1.
rand_b[61:52]    = nanossegundos  (0-999) no nível 3; aleatório nos níveis 1 e 2.
demais bits      = aleatórios.

O campo de 48 bits de milissegundos comporta datas até 10889-08-02. Relógios anteriores à época Unix (1970-01-01) degradam para a própria época, em vez de produzirem um timestamp corrompido.

Example

Em serviços de alto volume, crie um único Generator no boot e reutilize-o em todas as goroutines. 

gen := uuidv7.NewGenerator()

u := gen.Generate(uuidv7.Level3) // u é um uuidv7.UUID ([16]byte)
fmt.Println(u.Version(), u.Variant())

Output:
7 2

func (*Generator) GenerateAt 

func (g *Generator) GenerateAt(level Level, t time.Time) UUID

GenerateAt produz um UUIDv7 para um instante informado pelo chamador, em vez do instante atual. É o sentido inverso de Import: ali se lê o tempo de um identificador, aqui se constrói um identificador para um tempo.

Serve para reprocessar um histórico, semear dados de teste e importar registros antigos preservando a ordenação cronológica da chave.

Os campos de tempo são gravados exatamente como em Generate, com a mesma distribuição por nível, e os bits livres recebem entropia deste gerador. Duas chamadas com o mesmo instante devolvem UUIDs DIFERENTES: é um gerador, não um construtor determinístico. Para a forma determinística de um instante, use MinAt e MaxAt.

A unicidade vem inteiramente dos bits livres, que são 74 no Nível 1, 62 no Nível 2 e 52 no Nível 3. Como o instante deixa de vir do relógio, nada impede o chamador de gerar em volume para um único instante, e é só aí que essa margem começa a importar.

Instantes anteriores a 1970-01-01T00:00:00Z degradam para a própria época, como em Generate. Instantes posteriores a 10889-08-02T05:31:50.655999999Z saturam no último instante representável, porque o campo de milissegundos tem 48 bits.

Níveis desconhecidos são tratados como Level1, como em Generate.

func (*Generator) GenerateAtString 

func (g *Generator) GenerateAtString(level Level, t time.Time) string

GenerateAtString produz, para um instante informado, um UUIDv7 já no formato string canônico. Valem as mesmas observações de GenerateAt.

func (*Generator) GenerateString 

func (g *Generator) GenerateString(level Level) string

GenerateString produz um UUID do nível informado já no formato string canônico (8-4-4-4-12, minúsculas).

func (*Generator) GenerateV7 

func (g *Generator) GenerateV7() UUID

GenerateV7 produz um UUID de versão 7 padrão da RFC 9562: carimbo Unix em milissegundos nos 48 bits altos, versão 7, variante RFC e os 74 bits restantes aleatórios. É exatamente Generate(Level1), sob o nome da versão, para que o UUIDv7 comum, sem a extensão de precisão desta biblioteca, possa ser pedido sem mencionar nível. É o mesmo que GenerateV7Level1.

A precisão embutida é a do milissegundo. Para gravar também os microssegundos ou os nanossegundos, use GenerateV7Level2 ou GenerateV7Level3, ou Generate com Level2 ou Level3. Não há forma em texto: use GenerateString(Level1) ou o método String do valor devolvido.

A entropia vem da fonte deste Generator, com o mesmo consumo do Nível 1 (duas palavras de 64 bits), e o caminho é livre de alocações. Vale o aviso de NewGenerator: no gerador padrão a fonte é o ChaCha8 do runtime do Go, e um identificador que precise ser segredo deve vir de NewCryptoGenerator ou de NewGeneratorWithReader.

O apelido não acrescenta custo ao caminho quente: a implementação continua em Generate, e o compilador embute esta chamada. Ver docs/01-escopo-e-layout.md seção 8.

func (*Generator) GenerateV7Level1 

func (g *Generator) GenerateV7Level1() UUID

GenerateV7Level1 produz um UUIDv7 de Nível 1: carimbo Unix em milissegundos e os 74 bits restantes aleatórios, o UUIDv7 padrão da RFC 9562. É exatamente Generate(Level1), e portanto o mesmo que GenerateV7; existe para que os três níveis tenham nome, e o nível escolhido fique legível no ponto da chamada em vez de numa constante.

Consome duas palavras de 64 bits da fonte de entropia, como o Nível 1, e não aloca. Não há forma em texto: use GenerateString(Level1) ou o método String do valor devolvido.

func (*Generator) GenerateV7Level2 

func (g *Generator) GenerateV7Level2() UUID

GenerateV7Level2 produz um UUIDv7 de Nível 2: carimbo Unix em milissegundos e os microssegundos do instante (0 a 999) em rand_a, com os 62 bits de rand_b aleatórios. É exatamente Generate(Level2), sob um nome que diz o nível.

Consome uma única palavra de 64 bits da fonte de entropia, como o Nível 2, e não aloca. Não há forma em texto: use GenerateString(Level2) ou o método String do valor devolvido.

func (*Generator) GenerateV7Level3 

func (g *Generator) GenerateV7Level3() UUID

GenerateV7Level3 produz um UUIDv7 de Nível 3: carimbo Unix em milissegundos, os microssegundos do instante (0 a 999) em rand_a e os nanossegundos (0 a 999) nos 10 bits mais altos de rand_b, com os 52 bits restantes aleatórios. É exatamente Generate(Level3), sob um nome que diz o nível.

Consome uma única palavra de 64 bits da fonte de entropia, como o Nível 3, e não aloca. Não há forma em texto: use GenerateString(Level3) ou o método String do valor devolvido.

type Level 

type Level uint8

Level define quanta precisão temporal é embutida no UUIDv7. 

const (
	// Level1 grava apenas milissegundos (48 bits). rand_a e rand_b
	// são totalmente aleatórios. É o UUIDv7 padrão da RFC 9562.
	Level1 Level = 1

	// Level2 grava milissegundos + microssegundos (0-999) em rand_a.
	Level2 Level = 2

	// Level3 grava milissegundos + microssegundos (em rand_a) +
	// nanossegundos (0-999) nos 10 bits mais altos de rand_b.
	Level3 Level = 3
)

type NullBinaryUUID 

type NullBinaryUUID struct {
	UUID  UUID
	Valid bool // Valid é falso quando a coluna era NULL
}

NullBinaryUUID é o equivalente de NullUUID para coluna binária de 16 bytes que também aceita NULL.

ATENÇÃO — ausência de valor e UUID nulo são coisas diferentes, e confundi-las produz a mesma linha no banco. Com Valid falso, Value devolve NULL; para gravar dezesseis bytes zerados é preciso Valid verdadeiro com UUID igual a Nil. Uma coluna que misture os dois casos não consegue mais distinguir "não havia valor" de "o valor era o UUID nulo".

func (NullBinaryUUID) MarshalBinary 

func (n NullBinaryUUID) MarshalBinary() ([]byte, error)

MarshalBinary grava os 16 bytes, ou nada quando não há valor.

func (NullBinaryUUID) MarshalJSON 

func (n NullBinaryUUID) MarshalJSON() ([]byte, error)

MarshalJSON grava a string canônica, ou null quando não há valor.

func (NullBinaryUUID) MarshalText 

func (n NullBinaryUUID) MarshalText() ([]byte, error)

MarshalText grava a string canônica, ou vazio quando não há valor.

func (*NullBinaryUUID) Scan 

func (n *NullBinaryUUID) Scan(src any) error

Scan implementa sql.Scanner. NULL, string vazia e fatia de bytes vazia produzem valor ausente (Valid falso), sem erro, como em NullUUID.

func (*NullBinaryUUID) UnmarshalBinary 

func (n *NullBinaryUUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê 16 bytes; vazio produz ausência.

func (*NullBinaryUUID) UnmarshalJSON 

func (n *NullBinaryUUID) UnmarshalJSON(data []byte) error

UnmarshalJSON lê uma string JSON ou null.

func (*NullBinaryUUID) UnmarshalText 

func (n *NullBinaryUUID) UnmarshalText(data []byte) error

UnmarshalText lê a string canônica; vazio produz ausência.

func (NullBinaryUUID) Value 

func (n NullBinaryUUID) Value() (driver.Value, error)

Value implementa driver.Valuer: NULL quando não há valor, e os 16 bytes crus quando há.

type NullUUID 

type NullUUID struct {
	UUID  UUID
	Valid bool // Valid é falso quando a coluna era NULL
}

NullUUID representa um UUID que pode ser nulo no banco de dados, no mesmo espírito de sql.NullString.

Example

NullUUID representa uma coluna que aceita NULL e viaja em JSON como a string canônica ou como null. 

type Registro struct {
	ID  uuidv7.UUID     `json:"id"`
	Pai uuidv7.NullUUID `json:"pai"`
}

raiz := Registro{ID: uuidv7.MustParse("0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff")}
dados, _ := json.Marshal(raiz)
fmt.Println(string(dados))

var lido Registro
_ = json.Unmarshal([]byte(`{"id":"0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff","pai":"{0192F7C5-1A2B-7C3D-8E4F-AABBCCDDEEFF}"}`), &lido)
fmt.Println(lido.Pai.Valid, lido.Pai.UUID == lido.ID)

Output:
{"id":"0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff","pai":null}
true true

func (NullUUID) MarshalBinary 

func (n NullUUID) MarshalBinary() ([]byte, error)

MarshalBinary grava os 16 bytes, ou nada quando não há valor.

func (NullUUID) MarshalJSON 

func (n NullUUID) MarshalJSON() ([]byte, error)

MarshalJSON grava a string canônica, ou null quando não há valor.

func (NullUUID) MarshalText 

func (n NullUUID) MarshalText() ([]byte, error)

MarshalText grava a string canônica, ou vazio quando não há valor.

func (*NullUUID) Scan 

func (n *NullUUID) Scan(src any) error

Scan implementa sql.Scanner. NULL, string vazia e fatia de bytes vazia produzem valor ausente (Valid falso), sem erro.

Em caso de erro o identificador não é alterado, mas o booleano cai para falso. É a única exceção à regra de receptor inalterado que vale para os desserializadores (docs/05-conversao-e-analise.md seção 5), e tem motivo próprio: database/sql reaproveita o mesmo destino a cada linha, então um chamador que ignore o erro leria o valor da linha anterior como se fosse o da linha que falhou. Zerar o booleano transforma esse descuido em ausência de valor, e não em dado errado.

func (*NullUUID) UnmarshalBinary 

func (n *NullUUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê 16 bytes; entrada vazia produz valor ausente.

Em caso de erro o receptor não é alterado, pelo mesmo motivo de UnmarshalText.

func (*NullUUID) UnmarshalJSON 

func (n *NullUUID) UnmarshalJSON(data []byte) error

UnmarshalJSON lê uma string JSON em qualquer formato aceito por Parse, ou null.

O caso comum, uma string sem sequências de escape, é lido direto dos bytes, sem alocar. Se a string contiver escapes JSON (por exemplo \u0030 no lugar de 0), a decodificação é delegada ao encoding/json, que os interpreta como faria para o tipo UUID; isso custa uma alocação e só acontece nesse caso raro. Erros de sintaxe JSON viram ErrInvalidFormat.

Em caso de erro o receptor não é alterado.

func (*NullUUID) UnmarshalText 

func (n *NullUUID) UnmarshalText(data []byte) error

UnmarshalText lê a string canônica; entrada vazia produz valor ausente.

Em caso de erro o receptor não é alterado, como em UnmarshalJSON e no tipo simples: o booleano de um valor que já estava presente continua verdadeiro. Ao contrário de Scan, aqui não há destino reaproveitado entre linhas que justifique a exceção.

func (NullUUID) Value 

func (n NullUUID) Value() (driver.Value, error)

Value implementa driver.Valuer.

type Time 

type Time struct {
	// Seconds é o timestamp Unix em segundos desde 1970-01-01 UTC.
	Seconds int64

	// Milliseconds é a fração do segundo: sempre 0..999.
	Milliseconds int

	// Microseconds é lido de rand_a. Vale 0..999 (fração do
	// milissegundo) quando o UUID é de Level2 ou Level3; em UUIDs de
	// Level1 são 12 bits aleatórios, portanto 0..4095.
	Microseconds int

	// Nanoseconds é lido de rand_b[61:52]. Vale 0..999 (fração do
	// microssegundo) quando o UUID é de Level3; em UUIDs de Level1 ou
	// Level2 são 10 bits aleatórios, portanto 0..1023.
	Nanoseconds int
}

Time reúne as propriedades temporais extraídas de um UUIDv7.

Os campos Microseconds e Nanoseconds só têm significado real se o UUID foi gerado com Level2/Level3 (micro) e Level3 (nano). Para UUIDs de Level1 esses campos contêm bits aleatórios — ainda assim, conforme a especificação, a importação os trata como tempo preciso e devolve o valor lido nos respectivos campos sem julgar a origem.

func Import 

func Import(s string) (Time, error)

Import recebe um UUIDv7 em string canônica e devolve suas propriedades de tempo (segundos, milissegundos, microssegundos e nanossegundos).

Retorna exatamente ErrInvalidFormat se a string não for um UUID canônico, e ErrNotV7 se for um UUID canônico de outra versão ou variante. Nos dois casos a estrutura devolvida é zerada.

Example

Import lê os campos de tempo a partir da string canônica e recusa, com ErrNotV7, um UUID bem formado de outra versão: um UUIDv4 não carrega instante, e lê-lo como UUIDv7 devolveria uma data sem sentido. 

t, err := uuidv7.Import("017f22e2-79b0-7cc3-98c4-dc0c0c07398f") // exemplo de UUIDv7 da RFC 9562
fmt.Println(t.Seconds, t.Milliseconds, err)

_, err = uuidv7.Import("919108f7-52d1-4320-9bac-f847db4148a8") // exemplo de UUIDv4 da RFC 9562
fmt.Println(errors.Is(err, uuidv7.ErrNotV7))

Output:
1645557742 0 <nil>
true

func ImportBinary 

func ImportBinary(u UUID) (Time, error)

ImportBinary extrai as propriedades de tempo de um UUIDv7 binário.

Devolve ErrNotV7, com a estrutura zerada, se o UUID não for de versão 7 com a variante da RFC 9562 (ver IsValid).

Dentro do UUIDv7 a leitura é "cega" quanto ao nível: ela sempre interpreta rand_a como microssegundos e os 10 bits altos de rand_b como nanossegundos, considerando dados aleatórios como se fossem o tempo preciso. Para obter um instante que descarte o que não pode ser tempo, use TimestampWithLevel.

Example

ImportBinary lê os campos de tempo de um UUIDv7. A leitura é cega quanto ao nível: rand_a é sempre interpretado como microssegundos e o topo de rand_b como nanossegundos, mesmo que o UUID seja de Nível 1 e esses bits sejam aleatórios. 

// UUIDv7 de Nível 3 montado à mão: 0x0192f7c51a2b ms desde a época,
// 0x1c3 = 451 microssegundos em rand_a e 0x393 = 915 nanossegundos
// nos 10 bits altos de rand_b.
u := uuidv7.MustParse("0192f7c5-1a2b-71c3-b930-0000aabbccdd")

t, err := uuidv7.ImportBinary(u)
if err != nil {
	fmt.Println("erro:", err)
	return
}
fmt.Printf("seg=%d ms=%03d us=%03d ns=%03d\n",
	t.Seconds, t.Milliseconds, t.Microseconds, t.Nanoseconds)

Output:
seg=1730733742 ms=635 us=451 ns=915

type UUID 

type UUID [16]byte

UUID é o valor binário de 128 bits (16 bytes, big-endian / ordem de rede). 

var Nil UUID

Nil é o UUID de valor zero, com os 128 bits em zero. É o valor devolvido junto de todo erro de análise e o que a leitura de banco grava para ausência de valor. Não é um UUIDv7: IsValid devolve falso para ele. Não altere o valor desta variável.

func FromBytes 

func FromBytes(b []byte) (UUID, error)

FromBytes constrói um UUID a partir de exatamente 16 bytes em ordem de rede. Devolve ErrInvalidLength se o tamanho for outro.

func FromString 

func FromString(s string) (UUID, error)

FromString interpreta uma string canônica de UUID e devolve o valor binário de 128 bits. Aceita maiúsculas ou minúsculas. Retorna ErrInvalidFormat se o tamanho, os hifens ou os dígitos forem inválidos.

Em caso de erro o UUID devolvido é sempre o valor zero: nenhum byte parcialmente decodificado vaza para o chamador.

Example

FromString aceita apenas a forma canônica 8-4-4-4-12, em maiúsculas ou minúsculas, e devolve ErrInvalidFormat para qualquer outra coisa. 

u, err := uuidv7.FromString("0192F7C5-1A2B-7C3D-8E4F-AABBCCDDEEFF")
if err != nil {
	fmt.Println("erro:", err)
	return
}
fmt.Println(u.String())

_, err = uuidv7.FromString("0192f7c51a2b7c3d8e4faabbccddeeff")
fmt.Println(err == uuidv7.ErrInvalidFormat) //nolint:errorlint // FromString devolve o sentinela puro; a comparação direta faz parte do contrato

Output:
0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff
true

func Generate 

func Generate(level Level) UUID

Generate produz um UUID binário usando o gerador padrão do pacote.

func GenerateAt 

func GenerateAt(level Level, t time.Time) UUID

GenerateAt produz um UUIDv7 para o instante informado usando o gerador padrão do pacote. Ver o método de mesmo nome em Generator.

Example

GenerateAt constrói um UUIDv7 para um instante que você informa, em vez do instante atual. É o sentido inverso de Import, e serve para reprocessar histórico preservando a ordenação cronológica da chave.

Os bits livres são sorteados: com o gerador padrão, duas chamadas com o mesmo instante devolvem valores diferentes. Aqui a entropia é fixa em zero só para o exemplo ter saída verificável. 

quando := time.Date(2019, 3, 14, 10, 0, 0, 123_456_789, time.UTC)
gen := uuidv7.NewGeneratorWith(func() uint64 { return 0 })

u := gen.GenerateAt(uuidv7.Level3, quando)
fmt.Println(u)

// Os campos de tempo voltam exatos no Nível 3, que grava os três.
t, _ := uuidv7.ImportBinary(u)
fmt.Println(t.Seconds, t.Milliseconds, t.Microseconds, t.Nanoseconds)

Output:
01697ba4-ed7b-71c8-b150-000000000000
1552557600 123 456 789

func GenerateV7 

func GenerateV7() UUID

GenerateV7 produz um UUID de versão 7 padrão (Nível 1) usando o gerador padrão do pacote.

Example

GenerateV7 é o UUIDv7 padrão da RFC 9562 pelo nome da versão, sem a extensão de precisão: exatamente Generate(Level1), com precisão de milissegundo. Existe também como método do Generator. 

u := uuidv7.GenerateV7()
fmt.Println(u.Version(), u.Variant())

Output:
7 2

func GenerateV7Level1 

func GenerateV7Level1() UUID

GenerateV7Level1 produz um UUIDv7 de Nível 1 usando o gerador padrão do pacote. É o mesmo que GenerateV7 e que Generate(Level1).

func GenerateV7Level2 

func GenerateV7Level2() UUID

GenerateV7Level2 produz um UUIDv7 de Nível 2 usando o gerador padrão do pacote. É o mesmo que Generate(Level2).

func GenerateV7Level3 

func GenerateV7Level3() UUID

GenerateV7Level3 produz um UUIDv7 de Nível 3 usando o gerador padrão do pacote. É o mesmo que Generate(Level3).

Example

GenerateV7Level1, GenerateV7Level2 e GenerateV7Level3 são os três níveis pelo nome, sem o argumento de nível: cada um é exatamente Generate com o nível correspondente, e GenerateV7Level1 é o mesmo que GenerateV7. Existem também como métodos do Generator. 

u := uuidv7.GenerateV7Level3() // milissegundos, microssegundos e nanossegundos embutidos
fmt.Println(u.Version(), u.Variant())

Output:
7 2

func MaxAt 

func MaxAt(level Level, t time.Time) UUID

MaxAt devolve o maior UUIDv7 que a biblioteca poderia gerar no instante t, no nível informado — todos os bits livres de entropia em um, com versão 7 e variante RFC preservadas. É o limite superior fechado do instante.

Valem aqui as mesmas observações de MinAt sobre mistura de níveis, resolução da fronteira e saturação nas pontas da faixa representável.

func MinAt 

func MinAt(level Level, t time.Time) UUID

MinAt devolve o menor UUIDv7 que a biblioteca poderia gerar no instante t, no nível informado — todos os bits livres de entropia em zero, com versão 7 e variante RFC preservadas.

Serve de limite inferior em consulta por intervalo usando o índice da própria chave primária, sem coluna nem índice de carimbo temporal: 

SELECT * FROM eventos WHERE id >= ? AND id < ?

ATENÇÃO — a fronteira só vale para UUIDs gravados no MESMO nível. Os bits abaixo do milissegundo significam coisas diferentes em cada nível, então uma fronteira de Nível 3 não delimita corretamente identificadores gravados em Nível 1. Nunca misture níveis na mesma coluna.

A precisão da fronteira é a do nível: no Nível 1 ela delimita o milissegundo inteiro, no Nível 2 o microssegundo e no Nível 3 o nanossegundo. Níveis desconhecidos são tratados como Level1, como em Generate.

Instantes anteriores a 1970-01-01T00:00:00Z devolvem a fronteira da própria época, e instantes posteriores a 10889-08-02T05:31:50.655999999Z devolvem a do último instante representável, porque o campo de milissegundos tem 48 bits. Nas duas pontas a saturação mantém a fronteira monotônica, mas dois instantes distintos fora da faixa passam a devolver o mesmo valor.

Example

MinAt e MaxAt devolvem o menor e o maior UUIDv7 que a biblioteca poderia gerar em um instante, no nível informado. As duas preservam a versão 7 e a variante RFC, e é isso que as torna limites corretos: a fronteira superior do Nível 1 termina em 7fff-bfff, não em ffff-ffff.

No Nível 2 o campo rand_a carrega os microssegundos do instante (456, ou 0x1c8), então ele é igual nas duas fronteiras e só rand_b varia. 

instante := time.Date(2026, 9, 11, 12, 34, 56, 123_456_789, time.UTC)

fmt.Println(uuidv7.MinAt(uuidv7.Level1, instante))
fmt.Println(uuidv7.MaxAt(uuidv7.Level1, instante))
fmt.Println(uuidv7.MinAt(uuidv7.Level2, instante))
fmt.Println(uuidv7.MaxAt(uuidv7.Level2, instante))

Output:
01a09076-bdfb-7000-8000-000000000000
01a09076-bdfb-7fff-bfff-ffffffffffff
01a09076-bdfb-71c8-8000-000000000000
01a09076-bdfb-71c8-bfff-ffffffffffff

func Must 

func Must(u UUID, err error) UUID

Must devolve u, ou entra em pânico se err não for nula. Serve para encadear com funções que devolvem par de valores.

func MustParse 

func MustParse(s string) UUID

MustParse interpreta um UUID em qualquer formato aceito por Parse e entra em pânico se a string for inválida.

Destina-se a constantes do próprio código, como identificadores fixos de teste; nunca use com entrada vinda de fora do programa.

func Parse 

func Parse(s string) (UUID, error)

Parse interpreta um UUID em qualquer um dos quatro formatos usuais: 

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx        canônico, 36 caracteres
urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   URN, 45 caracteres
{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}      entre chaves, 38 caracteres
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx            hexadecimal cru, 32 caracteres

Maiúsculas e minúsculas são aceitas, inclusive no prefixo URN. Em caso de erro o UUID devolvido é sempre Nil.

A análise é só de forma: um UUID de outra versão é aceito, e a recusa fica para as leituras de tempo, com ErrNotV7. Use IsValid para exigir a versão 7 logo após a análise, e FromString quando quiser aceitar somente o formato canônico.

Example

Parse aceita as quatro formas usuais de escrever um UUID; todas produzem o mesmo valor. 

inputs := []string{
	"0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff",
	"{0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff}",
	"urn:uuid:0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff",
	"0192f7c51a2b7c3d8e4faabbccddeeff",
}
for _, in := range inputs {
	u, err := uuidv7.Parse(in)
	if err != nil {
		fmt.Println("erro:", err)
		continue
	}
	fmt.Println(u)
}

Output:
0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff
0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff
0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff
0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff

func ParseBytes 

func ParseBytes(b []byte) (UUID, error)

ParseBytes faz o mesmo que Parse a partir de uma sequência de bytes, sem converter para string e sem alocar.

func RangeAt 

func RangeAt(level Level, from, to time.Time) (lo, hi UUID)

RangeAt devolve as duas fronteiras de um intervalo SEMIABERTO [from, to) no nível informado, prontas para a comparação usual: 

lo, hi := uuidv7.RangeAt(uuidv7.Level2, inicio, fim)
rows, err := db.Query(
    "SELECT * FROM eventos WHERE id >= $1 AND id < $2",
    lo.String(), hi.String(),
)

O limite inferior é MinAt(level, from) e o superior é MinAt(level, to): identificadores gerados no instante to ficam de fora, os gerados em from ficam dentro. Para um intervalo fechado, use MinAt e MaxAt diretamente.

A exclusão vale na resolução do nível. No Nível 1 o intervalo termina no início do milissegundo de to, e portanto exclui esse milissegundo inteiro; no Nível 2 termina no microssegundo de to e no Nível 3 no nanossegundo.

RangeAt não ordena os argumentos: passar to anterior a from devolve um intervalo vazio, que é o que a comparação vai refletir.

Valem aqui as mesmas observações de MinAt sobre mistura de níveis e saturação nas pontas da faixa representável.

Example

RangeAt devolve as duas fronteiras de um intervalo semiaberto, prontas para consultar por faixa usando o índice da própria chave primária: 

SELECT * FROM eventos WHERE id >= $1 AND id < $2 ORDER BY id

A fronteira só vale para identificadores gravados no mesmo nível: os bits abaixo do milissegundo significam coisas diferentes em cada um. 

inicio := time.Date(2026, 9, 11, 12, 34, 56, 123_456_789, time.UTC)
fim := inicio.Add(time.Millisecond)

lo, hi := uuidv7.RangeAt(uuidv7.Level2, inicio, fim)
fmt.Println(lo)
fmt.Println(hi)

Output:
01a09076-bdfb-71c8-8000-000000000000
01a09076-bdfc-71c8-8000-000000000000

func StringToBinary 

func StringToBinary(s string) (UUID, error)

StringToBinary é um apelido explícito para FromString: converte a string canônica no binário de 128 bits.

func (UUID) AppendBinary 

func (u UUID) AppendBinary(dst []byte) ([]byte, error)

AppendBinary escreve os 16 bytes em ordem de rede no fim de dst e devolve o slice estendido, com a assinatura da interface encoding.BinaryAppender, introduzida no Go 1.24 junto da encoding.TextAppender que AppendText satisfaz. O erro devolvido é sempre nulo.

Não aloca quando dst tem capacidade sobrando; passar nil é válido e faz a função alocar os 16 bytes.

Ao contrário do lado do texto, aqui não existe uma segunda forma sem erro. AppendTo existe porque a formatação canônica é um cálculo; os bytes não são: append(dst, u[:]...) é exatamente o corpo deste método, e o chamador que não quer o erro sempre nulo escreve a linha direto. O método existe para satisfazer a interface.

A interface não é referenciada em lugar nenhum do pacote, então o método compila também nas versões anteriores do Go, onde simplesmente não satisfaz interface alguma. Isso mantém o go.mod em 1.22, como em AppendText.

O conteúdo é idêntico ao de MarshalBinary: anexar ou serializar grava os mesmos 16 bytes.

func (UUID) AppendText 

func (u UUID) AppendText(dst []byte) ([]byte, error)

AppendText é AppendTo com a assinatura da interface encoding.TextAppender, introduzida no Go 1.24. O erro devolvido é sempre nulo.

A interface não é referenciada em lugar nenhum do pacote, então o método compila também nas versões anteriores, onde simplesmente não satisfaz interface alguma. Isso mantém o go.mod em 1.22.

func (UUID) AppendTo 

func (u UUID) AppendTo(dst []byte) []byte

AppendTo escreve a forma canônica de 36 bytes no fim de dst e devolve o slice estendido, como fazem as funções Append da biblioteca padrão.

É o caminho mais barato para serializar muitos identificadores: não aloca nada quando dst tem capacidade sobrando, enquanto String paga uma alocação por chamada. Reaproveite o mesmo buffer entre chamadas: 

buf = u.AppendTo(buf[:0])

Passar nil é válido e faz a função alocar os 36 bytes.

func (UUID) Bytes 

func (u UUID) Bytes() []byte

Bytes devolve uma cópia dos 16 bytes em ordem de rede. Alterar o resultado não afeta o UUID de origem.

Equivale a MarshalBinary sem o erro sempre nulo. Dentro do pacote do chamador, u[:] é mais barato e não copia, mas devolve um slice apoiado no próprio valor: use Bytes quando o destino guardar a referência.

Serve também para contornar uma armadilha de formatação: como UUID satisfaz fmt.Stringer, %x sobre um UUID formata a string canônica, não os bytes. fmt.Printf("%x", u.Bytes()) imprime os 32 dígitos esperados.

func (UUID) Compare 

func (u UUID) Compare(other UUID) int

Compare ordena dois UUIDs pela sequência de bytes, devolvendo -1, 0 ou 1. Para UUIDv7 a ordem coincide com a ordem cronológica, na resolução do nível gravado; dentro do mesmo instante embutido a ordem é decidida pelos bits aleatórios.

A assinatura serve diretamente à biblioteca padrão: slices.SortFunc(lista, UUID.Compare) ordena uma lista sem alocar.

Para simples igualdade não é preciso chamar nada: UUID é um vetor de bytes e aceita o operador de igualdade diretamente.

func (UUID) IsValid 

func (u UUID) IsValid() bool

IsValid informa se o UUID é um UUIDv7: número de versão 7 e variante da RFC 9562 (0b10). É a mesma condição que as leituras de tempo exigem, e um UUID que falhe aqui é recusado por Import e ImportBinary com ErrNotV7 e por Timestamp e TimestampWithLevel com falso.

A verificação é de forma, não de origem: não há como saber se o UUID foi gerado por esta biblioteca, nem em qual nível. Nil é recusado, porque não carrega versão nem variante; use IsZero para reconhecê-lo.

func (UUID) IsZero 

func (u UUID) IsZero() bool

IsZero informa se o UUID é o valor nulo.

func (UUID) MarshalBinary 

func (u UUID) MarshalBinary() ([]byte, error)

MarshalBinary devolve os 16 bytes do UUID em ordem de rede. Implementa encoding.BinaryMarshaler.

func (UUID) MarshalText 

func (u UUID) MarshalText() ([]byte, error)

MarshalText devolve a representação canônica em texto, com 36 bytes. Implementa encoding.TextMarshaler, o que faz encoding/json gravar o UUID como string.

func (*UUID) Scan 

func (u *UUID) Scan(src any) error

Scan lê um UUID vindo do banco de dados, implementando sql.Scanner.

Aceita: 

nil      — grava o UUID nulo
string   — interpretado por Parse, em qualquer formato aceito;
           a string vazia grava o UUID nulo, sem erro
[]byte   — 16 bytes viram o valor binário; vazio grava o UUID nulo;
           outro tamanho é texto

Texto vazio equivale a ausência de valor: colunas de texto cujo valor padrão é a string vazia não devem falhar na leitura.

Como Parse, confere só a forma: um UUID de outra versão é aceito, e a recusa fica para as leituras de tempo. Em caso de erro o receptor não é alterado.

func (UUID) String 

func (u UUID) String() string

String converte o UUID binário (16 bytes) na representação canônica em texto: 32 dígitos hexadecimais minúsculos agrupados como 8-4-4-4-12 e separados por hifens. Exemplo: 

0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff

A implementação escreve diretamente em um buffer de 36 bytes, sem alocações intermediárias, para ser barata em caminhos quentes.

Atenção: por UUID satisfazer fmt.Stringer, os verbos %x e %X do pacote fmt formatam esta string — devolvendo 72 caracteres com o hexadecimal do texto — e não os 16 bytes. Para imprimir os bytes, converta antes: fmt.Printf("%x", u[:]).

func (UUID) Timestamp 

func (u UUID) Timestamp() (time.Time, bool)

Timestamp devolve o instante de criação embutido no UUIDv7, em UTC, com resolução de milissegundo. É o mesmo que TimestampWithLevel(Level1).

Devolve falso se o UUID não for de versão 7 com a variante da RFC 9562 (ver IsValid).

Para recuperar também os microssegundos e nanossegundos gravados pelos níveis 2 e 3 desta biblioteca, use TimestampWithLevel.

func (UUID) TimestampWithLevel 

func (u UUID) TimestampWithLevel(level Level) (time.Time, bool)

TimestampWithLevel devolve o instante de criação de um UUIDv7 em UTC, reconstruindo a precisão sub-milissegundo gravada pelo nível informado.

O nível não pode ser deduzido do UUID, por isso precisa ser informado pelo chamador. Se algum campo lido estiver fora da faixa 0 a 999 — o que denuncia bits aleatórios, e não tempo — todos os campos sub-milissegundo são descartados e devolve-se apenas o milissegundo. No nível 3 os dois campos vêm da mesma geração: um rand_a fora da faixa prova que o topo de rand_b também é ruído, mesmo que caiba em 0 a 999 por acaso. No Nível 1 e em níveis desconhecidos devolve apenas o milissegundo.

Devolve falso se o UUID não for de versão 7 com a variante da RFC 9562 (ver IsValid).

Example

TimestampWithLevel reconstrói o instante com a precisão do nível informado. O nível não pode ser deduzido do UUID, por isso o chamador precisa dizê-lo. 

// O mesmo UUID de Nível 3 usado em ExampleImportBinary.
u := uuidv7.MustParse("0192f7c5-1a2b-71c3-b930-0000aabbccdd")

ms, _ := u.Timestamp() // só o milissegundo, como qualquer UUIDv7
l3, _ := u.TimestampWithLevel(uuidv7.Level3)

fmt.Println(ms.Format(time.RFC3339Nano))
fmt.Println(l3.Format(time.RFC3339Nano))

Output:
2024-11-04T15:22:22.635Z
2024-11-04T15:22:22.635451915Z

func (UUID) URN 

func (u UUID) URN() string

URN devolve a representação como URN da RFC 8141, ou seja, a string canônica prefixada por "urn:uuid:". Parse aceita esta forma de volta.

func (*UUID) UnmarshalBinary 

func (u *UUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê exatamente 16 bytes em ordem de rede. Implementa encoding.BinaryUnmarshaler.

Em caso de erro o receptor não é alterado.

func (*UUID) UnmarshalText 

func (u *UUID) UnmarshalText(data []byte) error

UnmarshalText lê a representação em texto, aceitando os mesmos quatro formatos de Parse. Implementa encoding.TextUnmarshaler.

Como Parse, confere só a forma: um UUID de outra versão é aceito. Em caso de erro o receptor não é alterado.

func (UUID) Value 

func (u UUID) Value() (driver.Value, error)

Value entrega o UUID ao banco de dados como a string canônica, implementando driver.Valuer.

O texto é o formato gravado desde a primeira versão e não vai mudar: uma coluna que já recebeu texto e passasse a receber binário ficaria com dois formatos misturados, e nenhuma consulta acharia as linhas antigas. Para gravar em coluna binária de 16 bytes, converta para BinaryUUID no ponto da consulta.

func (UUID) Variant 

func (u UUID) Variant() byte

Variant devolve os 2 bits altos do byte 8. Vale 0b10 (2), a variante da RFC 9562, em todo UUID gerado por esta biblioteca.

func (UUID) Version 

func (u UUID) Version() byte

Version devolve o nibble de versão. Vale 7 em todo UUID gerado por esta biblioteca; um valor diferente indica identificador vindo de fora, que as leituras de tempo recusam com ErrNotV7.

Source Files

View all Source files

Directories

Path Synopsis
skill
examples/01-gerar command
Exemplo 01: gerar UUIDv7 nos três níveis, pelas funções de pacote e por um Generator criado no boot.
 Exemplo 01: gerar UUIDv7 nos três níveis, pelas funções de pacote e por um Generator criado no boot.
examples/02-ler-instante command
Exemplo 02: ler o instante gravado em um UUIDv7, nas duas políticas de leitura, e recusar o que não é UUIDv7.
 Exemplo 02: ler o instante gravado em um UUIDv7, nas duas políticas de leitura, e recusar o que não é UUIDv7.
examples/03-analisar-texto command
Exemplo 03: converter texto em UUID com o analisador estrito e com o permissivo, e tratar cada erro pelo tipo.
 Exemplo 03: converter texto em UUID com o analisador estrito e com o permissivo, e tratar cada erro pelo tipo.
examples/04-consulta-por-intervalo command
Exemplo 04: consultar por intervalo de tempo usando o índice da própria chave primária, com as fronteiras MinAt, MaxAt e RangeAt.
 Exemplo 04: consultar por intervalo de tempo usando o índice da própria chave primária, com as fronteiras MinAt, MaxAt e RangeAt.
examples/05-importar-historico command
Exemplo 05: gerar chaves para registros antigos com o instante original, preservando a ordem cronológica do índice.
 Exemplo 05: gerar chaves para registros antigos com o instante original, preservando a ordem cronológica do índice.
examples/06-json-e-gob command
Exemplo 06: o UUID em JSON, texto, binário e gob, sem código extra, e a coluna anulável (NullUUID) nesses formatos.
 Exemplo 06: o UUID em JSON, texto, binário e gob, sem código extra, e a coluna anulável (NullUUID) nesses formatos.
examples/07-banco-de-dados command
Exemplo 07: como o UUID entra e sai de database/sql, em coluna de texto e em coluna binária de 16 bytes, com e sem NULL.
 Exemplo 07: como o UUID entra e sai de database/sql, em coluna de texto e em coluna binária de 16 bytes, com e sem NULL.
examples/08-entropia command
Exemplo 08: escolher a fonte de entropia: o gerador padrão, o criptográfico, um leitor do chamador e uma função própria; reproduzir identificadores com um leitor determinístico; e o que acontece quando a fonte falha.
 Exemplo 08: escolher a fonte de entropia: o gerador padrão, o criptográfico, um leitor do chamador e uma função própria; reproduzir identificadores com um leitor determinístico; e o que acontece quando a fonte falha.
examples/09-alto-volume command
Exemplo 09: gerar em alto volume com um único Generator compartilhado por muitas goroutines, provar a unicidade, e serializar sem alocar com AppendTo em um buffer reaproveitado.
 Exemplo 09: gerar em alto volume com um único Generator compartilhado por muitas goroutines, provar a unicidade, e serializar sem alocar com AppendTo em um buffer reaproveitado.
Pacote tests contém a suíte de testes funcionais, os benchmarks e utilitários de validação da biblioteca go-loghub-uuidv7.
 Pacote tests contém a suíte de testes funcionais, os benchmarks e utilitários de validação da biblioteca go-loghub-uuidv7.
benchmark-bulk command
Comando benchmark-bulk gera 1.000.000 de UUIDv7 de cada nível e imprime um relatório de tempo e throughput.
 Comando benchmark-bulk gera 1.000.000 de UUIDv7 de cada nível e imprime um relatório de tempo e throughput.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.