PostgreSQL 18: uuidv7 nativo e o fim do index bloat de UUID

Desde o lançamento de setembro de 2025, o banco gera UUID ordenável por tempo com a função uuidv7(), tirando da aplicação um problema que Rails, Laravel↳Laravel17 conteúdosGerenciando Assets com Laravel MixDev (Back & Front) · ago 2019 Laravel: single table inheritanceDev (Back & Front) · set 2020 Como fazer um CRUD no Laravel, do zero – PARTE 1Dev (Back & Front) · jun 2020Ver tudo em Dev (Back & Front) → e Spring carregavam havia anos. A migração de v4 para v7, porém, tem armadilhas em chave estrangeira e em ORM que não sabe da mudança.

O PostgreSQL↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 2019 5 itens legais sobre data types do PostgreSQLData · mar 2019 5 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data → 18, lançado em 25 de setembro de 2025 segundo as release notes oficiais do projeto, incluiu entre suas mudanças de servidor uma função pequena no texto mas grande na prática de quem sofre com chave primária UUID em produção: uuidv7(), geradora de UUIDs versão 7, ordenáveis por tempo. Não é a manchete mais chamativa do release, que também trouxe I/O assíncrono, skip scan em índices B-tree e generated columns virtuais como padrão, mas é a que resolve uma dor recorrente de quem projeta banco de dados junto de Rails, Laravel ou Spring: o index bloat causado por UUID aleatório.

Por que UUID aleatório destrói índice

UUID versão 4, o padrão usado por SecureRandom.uuid no Ruby, Str::uuid() do Laravel ou UUID.randomUUID() do Java, é feito para ser imprevisível: 122 bits de aleatoriedade, sem relação nenhuma entre um valor gerado agora e outro gerado um segundo depois. Isso é ótimo para evitar colisão e para não vazar informação sobre quando um registro foi criado. É péssimo para um índice B-tree.

Um índice B-tree é otimizado para inserção sequencial: cada novo valor cai perto do último, na mesma página de memória, sem precisar reorganizar nada. Com UUID v4, cada inserção cai num ponto aleatório da árvore inteira. O resultado é conhecido de quem já rodou EXPLAIN ANALYZE numa tabela grande com PK UUID: páginas de índice espalhadas, mais page splits, pior taxa de acerto no cache do buffer pool e um índice fisicamente maior do que precisaria ser. Em bases grandes, isso significa mais I/O de disco em toda escrita e leitura via índice, e um VACUUM mais caro para manter tudo isso arrumado.

O que o uuidv7() nativo muda

UUID versão 7, especificado na RFC 9562, resolve isso combinando um timestamp Unix de 48 bits (em milissegundos) nos primeiros bits do UUID com o restante ainda aleatório. Na prática, dois UUIDs v7 gerados em sequência têm bits iniciais parecidos, então caem próximos um do outro dentro da árvore do índice, se comportando como uma sequência quase monotônica, parecida com o que já acontece com uma coluna bigserial, mas sem os riscos de previsibilidade total de um contador incremental.

Antes do PostgreSQL 18, gerar UUID v7 dentro do Postgres dependia de recursos externos ao núcleo do banco, como extensões de terceiros ou geração do valor na própria aplicação antes de inserir. Agora é uma função nativa:

sql

CREATE TABLE orders (
 id uuid PRIMARY KEY DEFAULT uuidv7(),
 customer_id uuid NOT NULL,
 created_at timestamptz NOT NULL DEFAULT now()
);

O efeito é delegar ao banco uma responsabilidade que, historicamente, ficava na aplicação: gerar a chave primária. Isso importa porque ORM que gera UUID no lado da aplicação (por exemplo, para poder usar o valor antes do INSERT, em relacionamentos aninhados) perde justamente essa vantagem de localidade se continuar chamando SecureRandom.uuid ou equivalente. Para aproveitar o uuidv7() de verdade, a geração precisa migrar para o DEFAULT da coluna, o que é uma mudança de padrão de projeto, não só de função.

Rails, Laravel e Spring na prática

Nota da redação: os trechos de código desta seção não foram executados em ambiente real. Valide antes de usar em produção.

De modo geral, ORMs que geram o UUID no lado da aplicação, antes de enviar o valor ao banco, não distinguem entre versões de UUID: para eles, o valor é uma string ou um array de bytes como outro qualquer, independentemente de ser v4 ou v7. É esse padrão comum, gerar a PK em código e passá-la explicitamente no INSERT, que faz o índice não colher o ganho de localidade do uuidv7(), já que o valor gerado na aplicação sobrepõe o DEFAULT da coluna. Rails, Laravel e Spring, cada um a seu modo, oferecem configuração para gerar a chave no aplicativo ou delegar ao banco; o comportamento padrão exato de cada framework e de cada versão vale a pena confirmar na documentação oficial de cada projeto antes de decidir a estratégia de migração.

O caminho mais direto para aproveitar uuidv7() sem reescrever a lógica de negócio é parar de gerar o UUID na aplicação e deixar o DEFAULT uuidv7() da coluna fazer o trabalho, buscando o valor gerado de volta via RETURNING id (recurso que, aliás, o próprio PostgreSQL 18 reforça com o novo suporte a OLD/NEW em cláusulas RETURNING). Esse padrão tende a funcionar bem quando o ORM já espera que o banco possa gerar a PK e popula o objeto depois do INSERT. Quando o mapeamento já gera o UUID em código antes de persistir, é preciso remover essa geração e migrar para o DEFAULT do banco, ou aceitar que a ordenação por tempo continuará vindo da aplicação, não do Postgres, caso a geração em código seja mantida.

As armadilhas da migração de v4 para v7

A armadilha mais comum não é técnica, é de dado legado. Trocar o DEFAULT de uma coluna para uuidv7() só afeta linhas novas; a tabela inteira continua com uma mistura de UUIDs v4 antigos (aleatórios) e v7 novos (ordenáveis), e o índice não reorganiza sozinho os valores antigos. Isso significa que o ganho de localidade é parcial até que os dados antigos sejam naturalmente substituídos ou até uma reindexação completa, que em tabela grande é operação pesada e merece janela de manutenção.

Chave estrangeira é a segunda armadilha. Se orders.customer_id referencia customers.id, e customers.id ainda é gerado como v4 enquanto orders.id já virou v7, não há problema de integridade (o tipo uuid de 16 bytes é o mesmo para as duas versões), mas o ganho de performance fica limitado à tabela que foi migrada. Migrar só a tabela de log ou de eventos, que cresce rápido e sofre mais com bloat, e deixar tabelas de referência mais estáveis como estão, costuma ser um corte pragmático melhor do que tentar migrar tudo de uma vez.

O terceiro ponto é o ORM que não sabe da mudança. Se a aplicação continuar gerando UUID v4 no código mesmo depois de o banco ganhar uuidv7() como DEFAULT, o valor explícito passado no INSERT sobrepõe o default da coluna, e nada muda na prática. É um erro silencioso: a migração de schema roda sem erro, mas o índice continua bloating porque a aplicação nunca parou de gerar o valor antigo.

Quando não vale a pena trocar

UUID v7 expõe, por construção, o momento aproximado de criação do registro nos primeiros bits do valor. Para PK de tabela interna isso raramente é problema, mas para identificador que é exposto publicamente (token de convite, ID de sessão, slug em URL pública) a previsibilidade temporal pode ser informação demais: um invite ID sequencial no tempo permite estimar quantos convites foram gerados entre duas datas, por exemplo. Nesses casos, UUID v4 aleatório continua sendo a escolha mais defensável, e o custo de index bloat é um preço aceitável pela opacidade.

Vale considerar também cenários de escrita distribuída com múltiplos nós gravando na mesma tabela sem relógio bem sincronizado: como a ordenação de v7 depende do timestamp de cada gerador, clock skew entre nós pode gerar uma ordenação apenas aproximada, reduzindo (sem eliminar) o ganho de localidade que motivou a troca. E há o efeito colateral inverso ao problema original: uma PK praticamente monotônica concentra as inserções recentes numa faixa estreita do índice, o que em cenários de escrita extremamente concorrente pode criar contenção na mesma página, o mesmo tipo de hot-spot que sistemas com bigserial já conhecem havia décadas.

A leitura honesta é que uuidv7() não é substituto universal de v4, é mais uma ferramenta no mesmo lugar onde antes só havia extensão externa ou geração manual na aplicação. Para tabela grande, com padrão de escrita append-only e sem necessidade de esconder o momento de criação, o ganho de índice menor e mais compacto compensa. Para identificador público sensível a previsibilidade, v4 continua sendo a escolha certa.

Fonte 1: PostgreSQL 18 Release Notes (documentação oficial) (https://www.postgresql.org/docs/release/18.0/)

PostgreSQL: Release Notes

September 24, 2026: PostgreSQL 19 Beta 4 Released!

Quick Links

Documentation

Manuals

Categorias

Colunistas

Explorar

Newsletter

Ecossistema

PostgreSQL 18 tem uuidv7 nativo para reduzir o index bloat do UUID aleatório

Por que UUID aleatório destrói índice

O que o uuidv7() nativo muda

Rails, Laravel e Spring na prática

As armadilhas da migração de v4 para v7

Quando não vale a pena trocar

Fonte 1: PostgreSQL 18 Release Notes (documentação oficial) (https://www.postgresql.org/docs/release/18.0/)

Java 25 chega com Structured Concurrency na quinta preview e reorganiza o tratamento de falhas concorrentes

Npm cria token que publica pacote só depois de revisão humana

Rails ganha cache de schema em JSON e nova tarefa herb:check para validar views

Node.js 24 chega à fase LTS: o checklist de migração pra quem tem API em produção

JDK 25 LTS traz Scoped Values final e Structured Concurrency em quinta preview

GitHub agora deixa automatizar a autorização SSO de PATs clássicos e chaves SSH

Java 25 LTS chega com Scoped Values e Module Import estáveis: o que revisar no seu serviço

No Instagram

Fios

Por que UUID aleatório destrói índice

O que o uuidv7() nativo muda

Rails, Laravel e Spring na prática

As armadilhas da migração de v4 para v7

Quando não vale a pena trocar

Fonte 1: PostgreSQL 18 Release Notes (documentação oficial) (https://www.postgresql.org/docs/release/18.0/)

Java 25 chega com Structured Concurrency na quinta preview e reorganiza o tratamento de falhas concorrentes

Npm cria token que publica pacote só depois de revisão humana

Rails ganha cache de schema em JSON e nova tarefa herb:check para validar views

Node.js 24 chega à fase LTS: o checklist de migração pra quem tem API em produção

JDK 25 LTS traz Scoped Values final e Structured Concurrency em quinta preview

GitHub agora deixa automatizar a autorização SSO de PATs clássicos e chaves SSH

Java 25 LTS chega com Scoped Values e Module Import estáveis: o que revisar no seu serviço

No Instagram

Fios

Uma curadoria personalizada no seu e-mail