Convenções de esquema para um novo banco de dados PostgreSQL: nomes, identificadores, timestamps e texto

Objetivo

Um esquema com aparência consistente, sem identificadores entre aspas, que armazena o tempo sem ambiguidade e dá a todas as tabelas a mesma estrutura básica, de modo que migrations, consultas e código gerado sejam previsíveis.

Pré-requisitos

Uma ferramenta de migration com arquivos versionados, acordo sobre uma única estratégia de id e uma página curta de convenções no repositório, usada como referência na revisão de novas migrations.

Passos

1. Nomes: snake_case em minúsculas para tabelas, colunas, índices e constraints, sem nunca depender de aspas. A documentação afirma que identificadores sem aspas são convertidos para minúsculas, enquanto os que têm aspas diferenciam maiúsculas de minúsculas; assim, um nome com letras maiúsculas obriga todas as consultas a usar aspas para sempre. Respeite o limite de 63 bytes para identificadores, incluindo os nomes de índice gerados automaticamente.
2. Tabelas: singular ou plural, mas escolha apenas um; tabelas de junção recebem o nome dos dois lados (order_item). Nomeie constraints e índices segundo um padrão fixo (orders_customer_id_fkey, orders_created_at_idx), para que mensagens de erro e planos de execução sejam legíveis.
3. Ids: bigint GENERATED ALWAYS AS IDENTITY quando ids sequenciais forem aceitáveis, e uma coluna UUID quando os ids forem gerados por clientes ou não puderem revelar a ordem de criação; não use serial nem int. Uma coluna de chave estrangeira leva o nome da tabela referenciada (customer_id) e recebe um índice.
4. Tempo: timestamptz para todo instante no tempo; a documentação afirma que o valor é armazenado internamente em UTC e exibido no fuso horário da sessão, de modo que quem decide como ele é exibido é o fuso da sessão, e não o código da aplicação. Use timestamp simples apenas para valores de relógio de parede que deliberadamente não têm fuso, e date para datas. Toda tabela recebe created_at timestamptz NOT NULL DEFAULT now() e, onde as linhas são alteradas, updated_at, mantido pela aplicação ou por um trigger.
5. Texto: text, com CHECK (length(x) <= n) quando um limite importar, em vez de varchar(n), e nunca char(n); a documentação afirma que não há diferença de desempenho entre os três e que character(n) costuma ser o mais lento por causa do preenchimento (padding).
6. Nulabilidade e valores padrão: NOT NULL, a menos que "desconhecido" tenha um significado; booleanos como NOT NULL DEFAULT false; vocabulários pequenos e fixos como text com CHECK ou como tabela de consulta (lookup), em vez de um tipo ENUM, que é mais difícil de alterar depois.
7. Valores monetários e quantidades: numeric com escala explícita, nunca float; armazene a moeda junto ao valor.
8. Registre as regras na página de convenções, com uma tabela de exemplo, e inclua "segue as convenções de esquema" na checklist de revisão de migrations.

Resultado esperado

Toda migration produz tabelas com aparência semelhante; consultas e mapeamentos de ORM não precisam de aspas nem de conversões de tipo; valores de tempo são comparados corretamente entre fusos horários.

Limites e base de verificação

As convenções são uma síntese do agente colaborador; os fatos sobre a conversão de identificadores para minúsculas, o armazenamento de timestamptz e os tipos de caracteres vêm da documentação citada. Um esquema existente deve adotá-las aos poucos, em vez de ser renomeado de uma só vez em um único release.

Chaves internas e identificadores públicos

Use bigint GENERATED ALWAYS AS IDENTITY como chave primária e em todas as chaves estrangeiras, e dê às linhas acessadas de fora do sistema um identificador público separado: uma coluna uuid NOT NULL DEFAULT gen_random_uuid() ou um token aleatório, com seu próprio índice único. A chave interna continua com oito bytes e as inserções ocorrem em ordem; o identificador público é impossível de adivinhar e pode ser substituído sem mexer nas referências. Escolha uma chave primária UUID somente quando os clientes precisarem criar linhas sem uma ida ao banco de dados, e nesse caso prefira uma ordenada por tempo (uuidv7(), a partir do PostgreSQL 18) a uma aleatória, já que chaves aleatórias espalham as inserções pelo índice e o fazem crescer mais rápido. Uma chave ordenada por tempo revela a ordem de criação, portanto não substitui o identificador público quando isso for relevante.