O modo de planejamento do design de esquema Postgres ajuda a definir entidades, restrições, índices e migrações antes da geração de código, reduzindo reescritas depois.
Se você constrói endpoints e modelos antes de a forma do banco ficar clara, geralmente acaba reescrevendo as mesmas funcionalidades duas vezes. O app funciona para uma demo, então chegam dados reais e casos de borda e tudo começa a ficar frágil.
A maioria das reescritas vem de três problemas previsíveis:
Cada um força mudanças que se espalham pelo código, testes e apps clientes.
Planejar seu esquema Postgres significa decidir o contrato de dados primeiro, depois gerar código que corresponda. Na prática, isso parece escrever entidades, relacionamentos e as poucas consultas que importam, depois escolher restrições, índices e uma abordagem de migração antes de qualquer ferramenta scaffolder tabelas e CRUD.
Isso importa ainda mais quando você usa uma plataforma de vibe-coding como Koder.ai, onde você pode gerar muito código rapidamente. Geração rápida é ótima, mas é muito mais confiável quando o esquema está consolidado. Seus modelos e endpoints gerados precisam de menos edições depois.
Aqui está o que normalmente dá errado quando você pula o planejamento:
Um bom plano de esquema é simples: uma descrição em linguagem comum das suas entidades, um rascunho de tabelas e colunas, as restrições e índices principais, e uma estratégia de migração que permita mudar as coisas com segurança conforme o produto cresce.
O planejamento de esquema funciona melhor quando você começa pelo que o app precisa lembrar e pelo que as pessoas precisam poder fazer com esses dados. Escreva o objetivo em 2 a 3 frases simples. Se você não consegue explicar de forma simples, provavelmente criará tabelas extras que não precisa.
Em seguida, foque nas ações que criam ou mudam dados. Essas ações são a fonte real das suas linhas, e revelam o que deve ser validado. Pense em verbos, não em substantivos.
Por exemplo, um app de agendamentos pode precisar criar uma reserva, reagendar, cancelar, reembolsar e enviar mensagens ao cliente. Esses verbos sugerem rapidamente o que precisa ser armazenado (slots de tempo, mudanças de status, valores monetários) antes mesmo de nomear uma tabela.
Capture também suas rotas de leitura, porque leituras orientam estrutura e indexação depois. Liste as telas ou relatórios que as pessoas realmente usarão e como elas fatiam os dados: “Minhas reservas” ordenadas por data e filtradas por status, busca administrativa por nome do cliente ou referência de reserva, receita diária por local e uma visão de auditoria de quem mudou o quê e quando.
Por fim, anote as necessidades não funcionais que mudam escolhas de esquema, como histórico de auditoria, exclusões suaves, separação multi-tenant ou regras de privacidade (por exemplo, limitar quem pode ver dados de contato).
Se você planeja gerar código depois disso, essas anotações viram prompts fortes. Elas descrevem o que é requerido, o que pode mudar e o que precisa ser pesquisável. Se estiver usando Koder.ai, escrever isso antes de gerar qualquer coisa torna o Modo de Planejamento muito mais eficaz porque a plataforma trabalha a partir de requisitos reais em vez de suposições.
Antes de tocar em tabelas, escreva uma descrição simples do que seu app armazena. Comece listando os substantivos que você repete: user, project, message, invoice, subscription, file, comment. Cada substantivo é uma entidade candidata.
Depois adicione uma frase por entidade que responda: o que é e por que existe? Por exemplo: “Um Project é um espaço de trabalho que um usuário cria para agrupar trabalho e convidar outros.” Isso evita tabelas vagues como data, items ou misc.
Posse é a próxima grande decisão, e afeta quase todas as queries que você escreve. Para cada entidade, decida:
Agora decida como você vai identificar registros. UUIDs são ótimos quando registros podem ser criados de muitos lugares (web, mobile, jobs em background) ou quando você não quer IDs previsíveis. IDs bigint são menores e mais rápidos. Se precisar de um identificador legível, mantenha-o separado (por exemplo, um curto project_code único dentro de uma conta) em vez de forçá-lo a ser a chave primária.
Finalmente, escreva relacionamentos em palavras antes de diagramar qualquer coisa: um usuário tem muitos projetos, um projeto tem muitas mensagens, e usuários podem pertencer a muitos projetos. Marque cada ligação como obrigatória ou opcional, como “uma message deve pertencer a um project” vs “uma invoice pode pertencer a um project”. Essas frases viram sua fonte de verdade para geração de código depois.
Quando as entidades estiverem claras em linguagem simples, transforme cada uma em uma tabela com colunas que combinem com fatos reais que você precisa armazenar.
Comece com nomes e tipos que você possa manter. Escolha padrões consistentes: nomes de coluna em snake_case, o mesmo tipo para a mesma ideia e chaves primárias previsíveis. Para timestamps, prefira timestamptz para que fusos horários não te peguem de surpresa mais tarde. Para dinheiro, use numeric(12,2) (ou armazene centavos como inteiro) em vez de floats.
Para campos de status, use um enum do Postgres ou uma coluna text com uma constraint CHECK para controlar os valores permitidos.
Decida o que é obrigatório vs opcional traduzindo regras em NOT NULL. Se um valor deve existir para que a linha faça sentido, torne-o obrigatório. Se for verdadeiramente desconhecido ou não aplicável, permita nulls.
Um conjunto prático de colunas padrão para planejar:
id (uuid ou bigint, escolha uma abordagem e mantenha consistência)created_at e updated_atdeleted_at apenas se realmente precisar de exclusões suaves e restauraçãocreated_by quando precisar de um rastro de auditoria claro de quem fez o quêRelacionamentos muitos-para-muitos quase sempre devem virar tabelas de junção. Por exemplo, se múltiplos usuários podem colaborar em um app, crie app_members com app_id e user_id, depois aplique unicidade no par para que duplicatas não aconteçam.
Pense sobre histórico cedo. Se você sabe que precisará de versionamento, planeje uma tabela imutável como app_snapshots, onde cada linha é uma versão salva ligada a apps por app_id e marcada com created_at.
Restrições são os guardrails do seu esquema. Decida quais regras devem ser verdadeiras independentemente de qual serviço, script ou ferramenta admin toque o banco.
Comece com identidade e relacionamentos. Toda tabela precisa de uma chave primária, e qualquer campo “belongs to” deve ser uma foreign key real, não apenas um inteiro que você espera que corresponda.
Depois adicione unicidade onde duplicatas causariam dano real, como duas contas com o mesmo email ou duas linhas com o mesmo (order_id, product_id).
Restrições de alto valor para planejar cedo:
amount >= 0, status IN ('draft','paid','canceled') ou rating BETWEEN 1 AND 5.O comportamento de cascade é onde o planejamento te economiza trabalho depois. Pergunte o que as pessoas realmente esperam. Se um cliente é deletado, seus pedidos normalmente não deveriam desaparecer. Isso aponta para deletes restritos e preservação de histórico. Para dados dependentes como itens de pedido, cascading do pedido para os itens pode fazer sentido porque itens não têm significado sem o pai.
Quando você gerar modelos e endpoints mais tarde, essas restrições viram requisitos claros: quais erros tratar, quais campos são obrigatórios e quais casos de borda são impossíveis por design.
Índices devem responder a uma pergunta: o que precisa ser rápido para usuários reais.
Comece com as telas e chamadas de API que você espera enviar primeiro. Uma página de lista que filtra por status e ordena pelos mais recentes tem necessidades diferentes de uma página de detalhe que carrega registros relacionados.
Escreva de 5 a 10 padrões de consulta em linguagem simples antes de escolher qualquer índice. Por exemplo: “Mostrar minhas faturas dos últimos 30 dias, filtrar por pago/não pago, ordenar por created_at” ou “Abrir um projeto e listar suas tarefas por due_date.” Isso mantém escolhas de índice ancoradas em uso real.
Um bom conjunto inicial de índices costuma incluir colunas de chave estrangeira usadas em joins, colunas de filtro comuns (como status, user_id, created_at) e um ou dois índices compostos para consultas multi-filtro estáveis, como (account_id, created_at) quando você sempre filtra por account_id e depois ordena por tempo.
A ordem em índices compostos importa. Coloque a coluna que você filtra com mais frequência (e que é mais seletiva) primeiro. Se você filtra por tenant_id em toda requisição, muitas vezes ele pertence ao início de vários índices.
Evite indexar tudo “por precaução”. Cada índice adiciona trabalho em INSERT e UPDATE, e isso pode prejudicar mais que uma query rara levemente mais lenta.
Planeje busca por texto separadamente. Se você só precisa de correspondência simples “contains”, ILIKE pode bastar no começo. Se busca for central, planeje full-text search (tsvector) cedo para não ter que redesenhar depois.
Um esquema não está “pronto” quando você cria as primeiras tabelas. Ele muda toda vez que você adiciona uma feature, corrige um erro ou aprende mais sobre seus dados. Se você decidir sua estratégia de migração desde o início, evita reescritas dolorosas depois da geração de código.
Mantenha uma regra simples: mude o banco em pequenos passos, uma feature por vez. Cada migração deve ser fácil de revisar e segura para rodar em qualquer ambiente.
A maioria das quebras vem de renomear ou remover colunas, ou de mudar tipos. Em vez de fazer tudo de uma vez, planeje um caminho seguro:
Isso leva mais passos, mas é mais rápido na prática porque reduz outages e patches de emergência.
Dados seed fazem parte das migrações também. Decida quais tabelas de referência são “sempre lá” (roles, statuses, countries, tipos de plano) e torne-as previsíveis. Coloque inserts e updates para essas tabelas em migrações dedicadas para que todo desenvolvedor e todo deploy receba os mesmos resultados.
Defina expectativas cedo:
Rollbacks nem sempre são um “down migration” perfeito. Às vezes o melhor rollback é restaurar um backup. Se estiver usando Koder.ai, vale decidir também quando confiar em snapshots e rollback para recuperação rápida, especialmente antes de mudanças arriscadas.
Imagine um pequeno SaaS onde pessoas entram em equipes, criam projetos e acompanham tarefas.
Comece listando as entidades e apenas os campos que você precisa no primeiro dia:
Os relacionamentos são diretos: um team tem muitos projects, um project tem muitas tasks, e usuários entram em teams através de team_members. Tasks pertencem a um project e podem ser atribuídas a um usuário.
Agora adicione algumas restrições que evitam bugs que você normalmente encontra tarde demais:
Índices devem corresponder às telas reais. Por exemplo, se a lista de tasks filtra por project e state e ordena pelos mais recentes, planeje um índice como tasks (project_id, state, created_at DESC). Se “Minhas tarefas” for uma visão chave, um índice como tasks (assignee_user_id, state, due_date) pode ajudar.
Para migrações, mantenha o primeiro conjunto seguro e simples: crie tabelas, chaves primárias, chaves estrangeiras e as constraints únicas centrais. Uma boa mudança de acompanhamento é algo que você adiciona depois que o uso provar que é necessário, como introduzir exclusão suave (deleted_at) em tasks e ajustar índices de “tarefas ativas” para ignorar linhas deletadas.
A maioria das reescritas acontece porque o primeiro esquema falta regras e detalhes de uso real. Uma boa passagem de planejamento não é sobre diagramas perfeitos. É sobre identificar armadilhas cedo.
Um erro comum é manter regras importantes apenas no código da aplicação. Se um valor deve ser único, presente ou dentro de um intervalo, o banco de dados também deve impor isso. Caso contrário, um job em background, um novo endpoint ou uma importação manual pode contornar sua lógica.
Outro erro frequente é tratar índices como um problema tardio. Adicioná-los depois do lançamento frequentemente vira tentativa e erro, e você pode acabar indexando a coisa errada enquanto a query lenta real é um join ou um filtro em um campo de status.
Tabelas muitos-para-muitos também são fonte de bugs silenciosos. Se sua tabela de junção não impede duplicatas, você pode armazenar a mesma relação duas vezes e gastar horas debugando “por que este usuário tem dois papéis?”
Também é fácil criar tabelas primeiro e então perceber que precisa de logs de auditoria, exclusões suaves ou histórico de eventos. Essas adições se espalham para endpoints e relatórios.
Finalmente, colunas JSON são tentadoras para dados “flexíveis”, mas elas removem verificações e tornam indexação mais difícil. JSON é válido para payloads verdadeiramente variáveis, não para campos de negócio centrais.
Antes de gerar código, rode esta lista rápida de correções:
Parei aqui e certifique-se de que o plano é suficientemente completo para gerar código sem surpresas correntes. O objetivo não é perfeição. É pegar as lacunas que causam reescritas depois: relacionamentos faltando, regras pouco claras e índices que não combinam com o uso real do app.
Use isso como um check pré-voo rápido:
amount >= 0 ou statuses permitidos).Um teste rápido de sanidade: imagine que um colega entra amanhã. Ele poderia construir os primeiros endpoints sem perguntar “isso pode ser null?” ou “o que acontece na exclusão?” a cada hora?
Quando o plano estiver claro e os fluxos principais fizerem sentido no papel, transforme-o em algo executável: um esquema real mais migrações.
Comece com uma migração inicial que cria tabelas, tipos (se usar enums) e as constraints essenciais. Mantenha a primeira versão pequena, mas correta. Carregue um pouco de seed data e rode as queries que seu app realmente precisará. Se um fluxo parecer desconfortável, corrija o esquema enquanto o histórico de migrações ainda é curto.
Gere modelos e endpoints somente depois de testar algumas ações ponta a ponta com o esquema no lugar (create, update, list, delete, além de uma ação real de negócio). A geração de código é mais rápida quando tabelas, chaves e nomes estão estáveis o suficiente para que você não renomeie tudo no dia seguinte.
Um loop prático que mantém reescritas baixas:
Decida cedo o que validar no banco vs na camada de API. Coloque regras permanentes no banco (foreign keys, unique constraints, check constraints). Mantenha regras flexíveis na API (feature flags, limites temporários e lógica cross-table complexa que muda com frequência).
Se usar Koder.ai, uma abordagem sensata é concordar sobre entidades e migrações no Modo de Planejamento primeiro, então gerar seu backend Go + PostgreSQL. Quando uma mudança der errado, snapshots e rollback podem ajudar a voltar a uma versão conhecida enquanto você ajusta o plano do esquema.
Planeje o esquema primeiro. Isso estabelece um contrato de dados estável (tabelas, chaves, restrições) para que modelos e endpoints gerados não precisem de renomeações e reescritas constantes depois.
Na prática: escreva suas entidades, relacionamentos e consultas principais, então confirme restrições, índices e migrações antes de gerar código.
Escreva 2–3 frases descrevendo o que o app precisa lembrar e o que os usuários precisam poder fazer.
Depois liste:
Isso dá clareza suficiente para projetar tabelas sem exagerar em diagramas complexos.
Comece listando os substantivos que se repetem (user, project, invoice, task). Para cada um, acrescente uma frase: o que é e por que existe.
Se você não consegue descrever claramente, provavelmente criará tabelas vagas como items ou misc e se arrependerá depois.
Padronize uma estratégia de ID consistente em todo o esquema.
Se precisar de um identificador legível, adicione uma coluna única separada (por exemplo, project_code) em vez de usá-la como chave primária.
Decida por relacionamento com base no que usuários esperam e no que precisa ser preservado.
Padrões comuns:
RESTRICT/NO ACTION quando deletar o pai apagaria registros importantes (por exemplo, customer → orders)CASCADE quando linhas filhas não têm sentido sem o pai (por exemplo, order → line items)Tome essa decisão cedo porque impacta o comportamento da API e casos de borda.
Coloque regras permanentes no banco para forçar todo tipo de gravador (API, scripts, imports, ferramentas admin) a seguir o contrato.
Priorize:
Comece a partir de padrões reais de consulta, não de suposições.
Escreva 5–10 consultas em linguagem simples (filtros + ordenação) e então crie índices para elas:
status, user_id, created_atCrie uma tabela de junção com duas chaves estrangeiras e uma constraint única composta.
Padrão de exemplo:
team_members(team_id, user_id, role, joined_at)UNIQUE (team_id, user_id) para impedir duplicatasIsso evita bugs sutis como “por que este usuário aparece duas vezes?” e mantém as consultas limpas.
Padrões recomendados:
timestamptz para timestamps (menos surpresas com fuso)numeric(12,2) ou armazenar centavos em inteiro para dinheiro (evite floats)CHECKMantenha tipos consistentes entre tabelas (mesmo tipo para o mesmo conceito) para joins e validações previsíveis.
Use migrações pequenas e revisáveis e evite mudanças quebradoras em um único passo.
Caminho seguro:
Também decida previamente como tratar dados seed/reference para que todos os ambientes fiquem iguais.
PRIMARY KEY em cada tabelaFOREIGN KEY para cada coluna “belongs to”UNIQUE onde duplicatas causam problemas reais (email, (team_id, user_id) em tabelas de junção)CHECK para regras simples (valores não-negativos, status permitidos)NOT NULL para campos essenciais para o sentido da linha(account_id, created_at))Evite indexar tudo; cada índice torna INSERTs e UPDATEs mais lentos.