Pular para conteúdo

Conceitos

Pacote

O pacote é a unidade que vai do desenvolvimento à produção: uma pasta com os scripts SQL de um banco e um manifesto (sql2devops.yaml) que diz em que ordem eles rodam e como desfazer cada um. Veja Pacotes.

Quando o pacote é enviado (submit), o Sql2DevOps guarda uma cópia imutável dele no repositório de controle, com o hash SHA-256 do conteúdo e um id interno. Todo ambiente roda essa cópia guardada, nunca a pasta de trabalho. Para mudar um pacote enviado, envia-se uma nova versão.

Repositório de controle

Uma pasta, normalmente um repositório Git, que guarda:

  • projects/<projeto>/project.yaml: os ambientes e as regras do projeto;
  • projects/<projeto>/packages/<pacote>/v<n>/: as cópias enviadas;
  • projects/<projeto>/events/: o histórico, um arquivo JSON por evento;
  • keys/: as chaves públicas que assinam os eventos.

Quando é um repositório Git, cada mudança vira commit e push, com novas tentativas quando duas pipelines fazem push ao mesmo tempo. O Git é usado pelo executável git, então as credenciais que a máquina já tem funcionam.

Eventos e histórico

Cada envio, aprovação, execução, emergência, execução manual e revisão é um evento. Cada evento carrega o hash do anterior (uma cadeia de hashes) e, quando há chave de assinatura, uma assinatura ed25519. O sql2devops verify detecta eventos editados, removidos ou fora de ordem, chaves desconhecidas e cópias de pacote alteradas.

Tabela de histórico

Cada banco de destino ganha uma tabela sql2devops_history: uma testemunha independente do que foi aplicado nele. Antes de cada deploy, os dois registros são comparados:

  • já aplicado → nada roda;
  • divergem (banco restaurado de backup, pacote aplicado por outro caminho) → o deploy para e explica o motivo; --force passa por cima e fica registrado como forçado.

Projetos, ambientes e destinos

Um projeto agrupa pacotes e lista seus ambientes na ordem de promoção (por exemplo DEV → HML → PROD). Cada ambiente tem um ou mais destinos (targets): os bancos onde um pacote pode ser implantado, cada um com seu tipo de banco e a variável de ambiente com a string de conexão.

Promoção e aprovações

Uma versão só chega a um ambiente depois que a mesma versão passou no anterior, então a produção sempre roda exatamente o que foi testado. Cada ambiente escolhe a sua regra:

Aprovação Significado
none implanta assim que o ambiente anterior passou
automatic uma pipeline aprova, com evidência (por exemplo a URL da execução dos testes)
human pessoas nomeadas aprovam; por padrão quem enviou não pode aprovar o próprio pacote

Emergências e pendências

Quando a produção cai, o emergency implanta sem a regra do ambiente, com motivo e, se exigido, chamado. Fica registrado como qualquer execução e deixa pendências: uma revisão por outra pessoa e a mesma versão implantada nos ambientes que foram pulados. O status mostra as pendências até serem resolvidas. Veja Emergências.

Trava

Um deploy por vez em cada banco: sp_getapplock no SQL Server, advisory lock no PostgreSQL. Os outros esperam até --lock-timeout.

Identidades

No GitHub Actions, quem executa é github:<login> (de GITHUB_ACTOR); fora dele, o usuário do sistema operacional. Aprovadores e revisores são listados assim no project.yaml.