Imported from promovaweb/specsfy (
specialists/specsfy-specialist-postgres/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-specialist-postgres. Copyright stays with the author.
PostgreSQL
Quando usar
- Acionar para desenhar schema, escrever ou revisar SQL, escolher índice,
analisar plano (
EXPLAIN), diagnosticar lock/deadlock, planejar migration ou dimensionar backup/restore em Postgres. - Acionar também quando um ORM (Eloquent, Prisma, Drizzle) gerar SQL ineficiente e a causa raiz for modelagem ou índice, não a API do ORM.
- Não acionar para escolhas específicas de Supabase (RLS, Auth, Realtime,
Edge Functions): usar
$specsfy-specialist-supabase, que aplica Postgres por baixo com essas camadas adicionais. - Combinar com
$specsfy-specialist-laravelquando o ponto de entrada for Eloquent e com$specsfy-specialist-observabilityquando o gargalo abranger além do banco (aplicação, rede, cache).
No Specsfy
-
Fonte de entrada por fase
- Em
specsfy-02-backlog, leia o item emspecs/backlog/e registre ali as decisões e sinais do especialista, além das dúvidas abertas. - Em
specsfy-03-specifyespecsfy-04-validate, use a spec aberta e devolva a conclusão à seção trabalhada pela fase. - Em
specsfy-05-tasks, ajude a sugerir e sincronizar especialistas e modos entre o cabeçalho, a seção 8 e as tarefas. Só essa fase escreve a seção 14. - Em
specsfy-06-implement, limite-se à tarefa indicada e ao passo carregado.
Nas fases com spec, leia a spec aberta indicada pela skill chamadora ou localizada por
specsfy status. Consulte a linha| Especialistas |, a subseção#### Especialistasem### 8. Plano técnicoe a seção pertinente à fase. Leia também.specsfy/STACK.md,.specsfy/RULES.mde, por tratar schema e dado persistido,.specsfy/DATABASE.md. - Em
-
Siga o modo indicado na spec ou na tarefa, no formato
Especialista: $specsfy-specialist-postgres. Sem indicação, confirme pelo "Quando usar" acima se o banco é Postgres e qual versão está instalada. -
Devolva a conclusão e as dúvidas abertas no destino indicado no item 1, no próprio backlog, na spec ou na tarefa da fase.
-
Não mude o estado da spec nem marque gate: isso pertence a
$specsfy-03-specify,$specsfy-04-validate,$specsfy-05-taskse$specsfy-06-implement. -
Quando a fase trabalhar o plano técnico ou o modelo de dados na spec, leve schema, índice e plano real para a subseção
Migrationsda seção 8 e para### 9. Modelo de dados, e mantenha.specsfy/DATABASE.mdsincronizado pela skill$specsfy-setupno mododatabase.
Fluxo
- Descobrir versão do Postgres, extensões instaladas, volume atual, crescimento esperado, workload (OLTP, analítico, misto) e quem é o owner dos dados antes de recomendar.
- Modelar invariantes com tipos precisos,
NOT NULL,CHECK,UNIQUE, chaves estrangeiras e normalização adequada ao caso de uso. - Escrever a consulta mais simples que expressa a regra e medir o plano
real com
EXPLAIN (ANALYZE, BUFFERS)sobre dados representativos, nunca sobre uma tabela vazia ou de desenvolvimento. - Selecionar índice pelo workload observado (predicados do
WHERE,ORDER BY,JOIN), nunca por "essa coluna é consultada" isoladamente. - Analisar isolation level, duração de transação, ordem de aquisição de locks e concorrência esperada sob a carga real.
- Planejar a migration com compatibilidade entre a versão antiga e nova da aplicação durante o deploy, com um caminho de rollback testável.
- Marcar a execução como
[MIGRATION], apontar o arquivo versionado, aplicar em uma base de teste e consultar o histórico do migrador antes de concluir. - Validar backup, restore, monitoramento e capacidade no ambiente alvo antes de declarar a mudança pronta para produção.
Padrões
- Preferir constraint do banco (
NOT NULL,CHECK,UNIQUE, FK,EXCLUDE) para toda invariante que sempre deve valer: validação só na aplicação permite dado inconsistente por qualquer segundo caminho de escrita. - Evitar
SELECT *em código de produção, tipos imprecisos (textpara enum fechado,floatpara dinheiro) e índice redundante que duplica outro já existente com prefixo igual. - Nunca adicionar índice sem ler padrão de escrita, tamanho da tabela, seletividade do predicado e o plano antes/depois: índice mal escolhido piora escrita sem acelerar leitura.
- Manter transação curta (evitar I/O externo, espera de usuário ou chamada de rede dentro dela) e ordem de aquisição de locks consistente entre todos os caminhos de código para evitar deadlock.
- Rodar
EXPLAIN (ANALYZE, BUFFERS)somente em ambiente onde executar a consulta de verdade é seguro (não em produção semROLLBACK/replica). - Aplicar expand/contract em mudança de schema incompatível ou em tabela de alto volume: nunca renomear/remover coluna lida em produção no mesmo passo que a adiciona.
- Conceder o menor privilégio necessário e separar papéis de migration
(DDL), aplicação (DML) e leitura (
SELECTapenas): a aplicação nunca conecta com um role que podeDROP TABLE.
Antipadrões
- Índice criado por "essa coluna aparece no WHERE", ignorando seletividade: em coluna de baixa cardinalidade (booleano, status com poucos valores) o planner frequentemente prefere seq scan e o índice só custa em escrita.
ALTER TABLE ... ADD COLUMN ... NOT NULL DEFAULTem versão antiga do Postgres (< 11) reescrevendo a tabela inteira sob lock. Em versões atuais isso é otimizado paraDEFAULTconstante, masDEFAULTcom função volátil ainda reescreve.- Transação longa mantendo lock enquanto espera resposta de rede ou confirmação do usuário: impede o autovacuum de limpar tuplas mortas e aumenta bloat.
- Paginação por
OFFSETgrande em tabela que cresce: o custo cresce linearmente com o offset; preferir paginação por keyset (WHERE id > :cursor ORDER BY id LIMIT :n). - Backup automatizado nunca restaurado: "temos backup" sem um restore completo testado é uma suposição não verificada, não uma garantia.
Validação
- Testar integridade (constraints violadas geram erro esperado), concorrência (dois writers simultâneos não corrompem invariante) e as queries críticas do caminho quente.
- Comparar
EXPLAIN (ANALYZE, BUFFERS)antes/depois com cardinalidade realista, não com a tabela vazia do ambiente de desenvolvimento. - Estimar o lock e o tempo de rewrite de qualquer DDL contra o tamanho real da tabela em produção antes de agendar a janela de deploy.
- Conferir cada tarefa
[MIGRATION]pelo arquivo, pelo comando de aplicação e pela consulta do histórico do migrador, todos registrados com saída zero. - Provar restore periodicamente a partir do backup real, incluindo o tempo que o processo leva (RTO): backup sem restore testado não é uma garantia de recuperação.
- Não declarar uma mudança "sem impacto de performance" sem o plano comparado; não declarar um schema "íntegro" sem os testes de constraint e concorrência acima.
Skills relacionadas
$specsfy-specialist-modelingpara entidades, relações e ciclo de vida antes dos detalhes específicos do Postgres.$specsfy-specialist-application-securitydefine ameaça, autorização e isolamento que constraints, roles e RLS materializam no banco.$specsfy-specialist-supabasequando o Postgres for gerenciado por Supabase (RLS, Auth, Realtime, pooling específico).$specsfy-specialist-laravelquando o ponto de entrada for Eloquent e a correção precisar refletir em migration/model.$specsfy-specialist-observabilityquando o gargalo não se resolver só com índice/plano (rede, cache, aplicação) e para métricas e alertas de banco em produção (conexões, locks, replicação, lag).$specsfy-specialist-redisquando parte do estado consultado estiver em cache fora do banco: o Postgres continua sendo a fonte de verdade que o Redis nunca substitui.$specsfy-specialist-dockerpara empacotar e operar o servidor Postgres em container (imagem oficial, volume de dados, healthcheck): escolha de schema, índice e plano continuam aqui.$specsfy-specialist-mysqlcobre o outro banco relacional quando o projeto usa MySQL ou Percona: semântica de índice, lock e DDL não é transportável entre os dois.$specsfy-specialist-mongodbcobre o caso de documento quando o dado relacional não serve; aqui permanece a integridade referencial do schema.$specsfy-specialist-n8nquando o Postgres guarda workflow, execução e credencial da instância n8n: o schema, o índice e a poda continuam aqui.
Leia references/standards.md para tipos, índices, concorrência, segurança, migrations, operação e fontes oficiais.
