bancos-sql-guardrails - SKILL.md Agent Skill

name: bancos-sql-guardrails description: Define guardrails para criar, revisar e manter scripts SQL no repositorio `C:\@work\bancos` com compatibilidade `PostgreSQL 9.3` e padrao legado. Use quando a tarefa envolver `function`, `view`, `type`, `trigger`, `RTM`, tabela, coluna, `INSERT`, `UPDATE`, `DELETE` ou qualquer script SQL novo ou alterado no repo Bancos.

Bancos SQL Guardrails

Aplicar esta skill antes de criar, revisar ou alterar scripts SQL no repositorio bancos.

Fluxo

Ler sql-rules.md.
Classificar o artefato: function, view, table, column, type, trigger, rtm, crud.
Confirmar a pasta correta e a forma de versionamento do script.
Validar compatibilidade com PostgreSQL 9.3 e encoding esperado.
Identificar se a mudanca e sensivel e precisa ser sinalizada para aprovacao.
Em ALTER COLUMN TYPE ou ALTER TYPE ... ALTER ATTRIBUTE, testar primeiro em transacao com BEGIN/ROLLBACK para identificar dependencias reais.
Se houver views dependentes, mapear quais sao views-raiz e confirmar a ordem de evolucao do repo antes de decidir entre recriacao manual e queda temporaria no script estrutural.
So depois propor ou aplicar o patch SQL.

Regras principais

Preservar win1252 quando o script exigir esse encoding.
Salvar scripts SQL somente em C:\@work\bancos\desktop\Scripts ou subpastas apropriadas.
Se a function, view, trigger ou relatorio ja existir em desktop\Scripts\functions, views ou relatorios, alterar o arquivo existente em vez de criar um script novo de atualizacao.
Criar script novo apenas para artefato novo ou migracao pontual que nao seja reaplicada automaticamente pela pasta do artefato.
No workspace C:\@work\bancos, as pastas functions, views e relatorios rodam os scripts existentes em toda evolução de banco.
Quando a mudança for em function, view ou relatorio já versionado, atualizar o arquivo existente e não criar um novo apenas para forçar execução.
Script de execucao unica (roda 1x e nunca mais: backfill, correcao de dados, migracao pontual) NAO vai em functions/, views ou relatorios (essas pastas sao reaplicadas a cada evolucao). Vai na raiz desktop\Scripts (rastreado via scriptsversoes, roda 1x) ou, se for correcao historica opcional, num script avulso vinculado a tarefa para o suporte rodar manualmente.
SEMPRE PERGUNTAR ao usuario antes de embutir DML de execucao unica (UPDATE/DELETE/backfill) dentro de um arquivo de functions/ (ou de uma function/trigger): naquele local roda a cada evolucao.
Nao embutir backfill/DML em massa de tabelas transacionais (ex.: financas.baixas, financas.lancamentoscontas, financas.titulos) na evolucao automatica: o UPDATE/DELETE dispara as triggers da tabela e pode falhar por periodo fechado e por efeitos colaterais das triggers. Correcao historica desse tipo deve ficar em script avulso, executado manualmente, com avaliacao de janela e volume.
Nao usar comandos proibidos para desativar verificacao de constraints ou triggers globalmente.
Nao excluir nem renomear colunas.
Nao excluir types nem remover atributos existentes.
Preferir mudancas incrementais, idempotentes e seguras.
Em scripts versionados de C:\@work\bancos\desktop\Scripts, nao usar DO no arquivo quando ele passar por gerador que ja encapsula com DO externo.
Quando usar dollar-quote em function, view (quando aplicavel), bloco anonimo ou trigger helper, usar delimitador nomeado (ex.: $fn_saldo_credito$ ) e evitar $$ generico.
Quando uma function auxiliar for chamada por outra function/trigger no mesmo fluxo, garantir que o arquivo gerado entre antes do consumidor no script.sql; ordem de arquivo em Scripts\functions nao garante ordem de execucao se houver dependencia cruzada.
Se um ALTER falhar por dependencia de view ou rule, confirmar a cadeia real com o objeto no banco alvo e derrubar somente as views-raiz que precisam ser recriadas no mesmo passo.
Para regex em PostgreSQL 9.3, preferir classes explicitas (ex.: [^0-9]) em vez de sequencias com barra invertida (ex.: \D) que podem variar por escape/literal.
Ao estender assinatura de function ja usada pelo ERP, manter compatibilidade (parametro com DEFAULT ou sobrecarga equivalente) para evitar quebra de runtime.
Nao assumir cadastro funcional novo (ex.: nova descricao em forma de pagamento) sem evidencia no banco ou confirmacao do usuario.
Antes de propor UPDATE em campo de valor calculado, confirmar existencia real da coluna no banco (information_schema.columns ou \d) e nao assumir nome por alias de view.
Em consultas na schema util, validar a cadeia real de chaves antes de inferir o join por nome de tabela; por exemplo, util.registroexecucaojobs.job -> util.jobs.job e util.jobs.jobschedule -> util.jobschedule.jobschedule, nao id_job.
Em divergencia de saldo/valor liquido, validar primeiro o estado de triggers relacionadas (pg_trigger.tgenabled) antes de alterar function, view ou codigo Delphi.
Em alteracao de tipo de coluna usada por views, consultar information_schema.view_column_usage e testar o ALTER em transacao antes de editar scripts; nao assumir que a dependencia visivel no erro e a unica.
Quando desktop\Scripts roda antes de views, e aceitavel usar um script estrutural para remover views-raiz dependentes e deixar a pasta views recriar a cadeia na etapa posterior, desde que isso seja documentado no proprio script.
Em ajuste de tamanho de campo textual que trafega por API de banco, validar tambem os types compostos da API e nao apenas a tabela final; em financas, isso inclui revisar tabela fisica, type de entrada da API e views que projetam a coluna.
Se uma evolucao local falhar por ausencia de UNIQUE ou por subquery escalar com mais de uma linha, priorizar a correcao dos dados e constraints no banco alvo antes de alterar o script versionado, desde que o script esteja coerente para outros ambientes.
Para esse tipo de correcao, procurar duplicidades exatas com GROUP BY ... HAVING count(*) > 1 e consolidar a tabela de referencia com a menor alteracao possivel.
Em exclusao de financas.titulos ou outras tabelas muito referenciadas, se a sessao estiver em IO / DataFileRead e nao houver bloqueio, suspeitar primeiro de validacao pesada de FKs/cascatas em tabelas filhas grandes sem indice na coluna FK.
Antes de refatorar a function nesses casos, medir o volume das tabelas filhas e priorizar indices na coluna FK das maiores referencias; um indice parcial ajuda quando a coluna e nullable.

Saida minima

Tipo de artefato.
Pasta correta.
Riscos de compatibilidade ou aprovacao.
Regras obrigatorias que impactam o script.