Pular para conteúdo

Pacotes

Manifesto

# sql2devops.yaml  (sql2devops.json também é aceito)
package: CHG-1001        # seu identificador, por exemplo o número do chamado
version: 1               # opcional; definido pelo submit --auto-version
project: financeiro
target: financeiro-db    # um pacote = um banco
description: Tabela de taxas e cálculo de juros
steps:
  - file: 01-tabela-taxas.sql
    type: ddl            # ddl, data, function, procedure, view, trigger, other
    rollback: rollback/01-tabela-taxas.sql
  - file: 02-funcao-juros.sql
    type: function
    rollback: rollback/02-funcao-juros.sql
  - file: 03-taxas-iniciais.sql
    type: data
    timeout: 5m
    rollback: none       # explícito: este passo não pode ser desfeito
on_error: rollback       # ou: stop
variables: [senha_api]
Campo Obrigatório Significado
package sim Identificador, único no projeto
version não Número da versão; uma versão enviada nunca muda
project sim Projeto no repositório de controle
target sim Nome do destino (banco) no project.yaml
steps sim Scripts na ordem de execução
steps[].file sim Caminho do script dentro do pacote
steps[].type não Tipo de mudança, para os relatórios
steps[].rollback sim Script que desfaz o passo, ou none
steps[].timeout não Limite do passo (30s, 5m, 1h)
on_error não rollback (padrão) ou stop
variables não Variáveis usadas nos scripts (veja Variáveis)

Uma pasta com um único .sql e sem manifesto também é um pacote: --project e --target preenchem o manifesto gerado, e um arquivo rollback/<mesmo nome> vira o rollback.

Conferindo

sql2devops package check -d postgres ./CHG-1001

Confere a estrutura, se cada arquivo existe, a codificação dos arquivos (UTF-8, UTF-8 com BOM, UTF-16 e Windows-1252 são detectados), como cada script se divide em lotes, e avisa sobre variáveis usadas e não declaradas.

Enviando

sql2devops package submit ./CHG-1001

O pacote é copiado para o repositório de controle com o hash e um id interno, e um evento submitted é registrado. Pipelines que geram o pacote a cada execução (por exemplo um script idempotente de todo o esquema) usam --auto-version: conteúdo idêntico reaproveita a última versão; qualquer mudança vira a próxima.

Rodando sem o repositório de controle

sql2devops package run -d postgres ./CHG-1001

Útil num banco descartável de teste (por exemplo na CI). Nada é registrado.

Escrevendo bons rollbacks

Quando um passo falha, o rollback dele roda primeiro, depois os dos passos concluídos, do mais novo para o mais antigo. Os rollbacks rodam mesmo depois de timeout ou Ctrl+C. Scripts e rollbacks são responsabilidade de quem escreve: faça rollbacks seguros para rodar quando o passo foi aplicado só em parte (DROP ... IF EXISTS, conferências antes de apagar).

Quando nada do passo que falhou teve efeito (a conexão falhou, ou o primeiro comando falhou no PostgreSQL ou no SQLite, onde cada lote é um comando), o rollback dele é pulado e o relatório diz que o banco ficou inalterado.