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.