supabase-postgres-best-practices

Visão Geral

O que é supabase-postgres-best-practices?

Supabase Postgres Best Practices é uma habilidade curada para ajudar desenvolvedores e engenheiros de banco de dados a otimizar a performance do Postgres. Mantida pela Supabase, esta habilidade oferece regras práticas e exemplos para escrever consultas SQL eficientes, projetar esquemas robustos, gerenciar conexões e implementar as melhores práticas de segurança. Abrange oito categorias críticas, incluindo performance de consultas, gerenciamento de conexões, segurança (incluindo Row-Level Security), design de esquemas, concorrência, padrões de acesso a dados, monitoramento e recursos avançados do Postgres.

Quem Deve Usar Esta Habilidade?

• Desenvolvedores backend que trabalham com Postgres ou Supabase
• Engenheiros de banco de dados buscando melhorar confiabilidade e velocidade
• Equipes revisando ou refatorando consultas SQL e esquemas de banco
• Qualquer pessoa configurando Postgres para alta concorrência ou ambientes serverless

Problemas Que Resolve

• Identifica e corrige anti-padrões comuns no Postgres
• Fornece reescritas SQL concretas e métricas de performance
• Ajuda a evitar consultas lentas, gargalos de conexão e configurações de segurança incorretas
• Oferece orientações priorizadas para melhorias críticas e incrementais

Como Usar

Passos para Instalação

1. Adicione a habilidade ao seu agente ou projeto:

   npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices
   

2. Comece pela documentação principal:
   • Abra SKILL.md para uma visão geral de todas as melhores práticas e categorias de regras.
   • Revise AGENTS.md para uma lista compilada e navegável de todas as referências.
3. Explore tópicos detalhados:
   • Navegue pela pasta references/ para guias aprofundados sobre temas como busca full-text, indexação JSONB, pooling de conexões e otimização de consultas.
   • Use o arquivo references/_sections.md para entender o impacto e prioridade de cada categoria de regra.
4. Adapte ao seu fluxo de trabalho:
   • Integre regras relevantes e exemplos SQL em suas revisões de código, migrações ou verificações automatizadas.
   • Consulte README.md para instruções de contribuição e validação caso queira estender ou personalizar a habilidade.

Arquivos e Pastas Principais

• SKILL.md: Manifesto principal da habilidade e visão geral (leia primeiro)
• AGENTS.md: Documentação compilada para agentes
• references/: Guias individuais de melhores práticas (ex.: query-missing-indexes.md, conn-pooling.md)
• README.md: Instruções para contribuidores e validação

Exemplos de Uso

• Refatorar consultas lentas usando as regras de performance de consulta
• Projetar novas tabelas com melhores práticas de esquema
• Configurar pooling de conexões para aplicações serverless
• Aplicar Row-Level Security com padrões claros e práticos

Perguntas Frequentes

Quando devo usar supabase-postgres-best-practices?

Use esta habilidade sempre que estiver escrevendo, revisando ou otimizando consultas Postgres, projetando esquemas, configurando conexões ou implementando políticas de segurança. É especialmente útil durante revisões de código, migrações de banco e resolução de problemas de performance.

O que diferencia esta habilidade de guias gerais de Postgres?

Esta habilidade é curada pela Supabase e prioriza regras concretas e práticas com exemplos SQL antes e depois, impacto de performance quantificado e estrutura amigável para agentes. Foi criada para uso prático em projetos reais de Postgres e Supabase.

Como encontro as melhores práticas mais relevantes para meu caso?

Comece pelo SKILL.md para ver todas as categorias e prioridades. Para tópicos específicos, navegue pela pasta references/ ou consulte AGENTS.md para uma lista navegável. Cada referência inclui títulos claros e tags para facilitar a descoberta.

Posso contribuir ou personalizar a habilidade?

Sim. Siga as diretrizes em references/_contributing.md e README.md para adicionar novas melhores práticas ou adaptar as existentes ao seu ambiente. Scripts de validação e build estão incluídos para controle de qualidade.

Onde posso ver exemplos reais de SQL?

Cada referência na pasta references/ inclui padrões SQL incorretos e corretos, com explicações e links para documentação oficial quando relevante.

Para ver a árvore completa de arquivos e todas as referências disponíveis, abra a aba Files no seu agente ou navegador de repositórios.