specsfy-specialist-postgres
Modelar, consultar, migrar e operar PostgreSQL com integridade, índices, concorrência, segurança, performance e recuperação. Use para schemas, SQL, EXPLAIN, locks, isolation levels, migrations, roles, backup ou tuning em Postgres; não use para outro banco relacional sem confirmar a semântica específica, e não use para RLS/Auth/Realtime de Supabase — combine com `specsfy-specialist-supabase` nesse caso.
How do I install this agent skill?
npx skills add https://github.com/promovaweb/specsfy --skill specsfy-specialist-postgresIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive guidance for PostgreSQL database management. It is primarily instructional and does not contain malicious code or exfiltration patterns. It has a minor vulnerability surface for indirect prompt injection as it processes project-specific specification files without explicit boundary markers or sanitization.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/promovaweb/specsfy/specsfy-specialist-postgres">View specsfy-specialist-postgres on skillZs</a>