v2 sobre pipeline ativo, shadow run, rollback

Selo de estado: Preview (teto atual do produto) · Curso ACD-220 — Pipelines e medalhão Bronze/Silver/Gold · Aula 11 de 12 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai publicar v2 sem desligar agenda; ler o diff — entender o que a publicação faz com a agenda existente, reconhecer uma mudança destrutiva e guardar a definição publicada como evidência.

Vídeo#

Identificador no manifesto: acd-220-11-publicar-versionar-rollback · duração-alvo 8 min · tela do produto: /sources.

Roteiro de gravação (5 capítulos):

#	Minutagem-alvo	Capítulo	Tela do produto
1	0:00–0:45	Abertura: título + selo. Publicar = congelar a definição; a primeira publicação nasce com a agenda desligada.	`/sources/[id]`
2	0:45–2:40	Painel Publicação e agenda: o selo da versão, o selo da agenda, Mudanças não publicadas e as quatro ações separadas.	`/sources/[id]`
3	2:40–4:50	Revisar e publicar: o resumo, "Diferenças em relação à versão publicada" e a frase de efeito sobre a agenda.	`/sources/[id]`
4	4:50–6:30	Mudanças destrutivas: a caixa de confirmação explícita e o que conta como destrutivo.	`/sources/[id]`
5	6:30–8:00	Baixar definição publicada (JSON): o que vem, o que não vem, e por que os bytes são determinísticos. Encerramento com o "faça você mesmo".	`/sources/[id]`

Conteúdo#

Publicar não liga agenda, e republicar não desliga

A primeira publicação cria a versão 1 e deixa a agenda desligada — nada é lido, escrito ou cobrado. Republicar um pipeline que já tem agenda ativa não desliga a agenda em silêncio: a tela diz o efeito antes de você confirmar. O produto nunca desliga sem avisar, e nunca liga por efeito colateral.

O painel Publicação e agenda

Na tela do pipeline, o painel mostra quatro fatos independentes e quatro ações separadas.

Selo	Quando aparece
Versão N publicada	Existe versão registrada
Versão não registrada	Pipeline criado antes da publicação versionada (não se finge uma versão 1 retroativa)
Selo da agenda	Estado real do despacho, não a chave crua do cadastro
Mudanças não publicadas	A definição viva divergiu da última versão publicada

As quatro ações: Baixar definição publicada (JSON) · Revisar e publicar · Ativar agenda / Pausar agenda · Executar agora. Nenhuma acontece por efeito colateral da outra — e Executar agora responde explicitamente: "Execução disparada — ela NÃO liga a agenda."

Ler o diff antes de publicar

Revisar e publicar monta a revisão com cinco dimensões — origem, destino, escrita, agenda e limites — e um bloco "Diferenças em relação à versão publicada". O diff é em pt-BR e nomeia a tabela:

Tabela nova na Bronze: tb_vendas (de vendas).
Tabela tb_vendas: escrita substitui a tabela inteira → incremental por marca d'água.
Tabela tb_vendas: coluna-chave — → atualizado_em.
Tabela tb_clientes: colunas PII — → cpf, email.
Agenda: modo scheduled/daily às 04:00 (retroage 0) → modo scheduled/daily às 09:00 (retroage 7).
Volume estimado: 5 → 12 GB/mês.

Um subconjunto do diff é marcado como destrutivo, com ⚠ e em destaque: mudança de origem de uma tabela, mudança de escrita, tabela que deixou de ser carregada e tabela removida da Bronze ("a tabela já carregada no datalake não é apagada, mas para de ser atualizada"). Quando há qualquer destrutiva, a publicação exige uma caixa de confirmação explícita dizendo quantas mudanças reescrevem ou param de atualizar tabelas já carregadas. Sem marcar, não publica.

E a frase de efeito sobre a agenda, que muda conforme o estado:

Agenda antes	O que a tela diz
Ligada	"A agenda continua LIGADA — publicar não a desliga. A partir da publicação, as execuções agendadas usam a versão nova; execuções em curso terminam na versão que as criou."
Desligada	"A agenda está DESLIGADA — publicar NÃO a liga e NÃO dispara carga. Use 'Ativar agenda' (ou 'Executar agora', se quiser rodar uma vez)."

Há ainda um caso silencioso que vale conhecer: se a definição viva é idêntica à publicada (mesmo checksum), publicar é idempotente — não cria versão nova. O histórico de versões não enche de v2, v3, v4 iguais.

O que a versão congela — e o que não congela

A versão congela a definição: o que ler, transformar e escrever. Ela não congela a credencial — o pipeline aponta para a conexão, então trocar a senha na conexão vale para todas as versões e todos os pipelines que a usam.

Voltar atrás: o que existe hoje

O motor de transformação tem versionamento, execução paralela de conferência (rodar sem publicar) e rollback provados por teste determinístico — é o que permite validar uma transformação nova sem expor ninguém ao resultado dela.

Para a definição do pipeline, seja preciso: o painel de publicação não tem um botão "restaurar versão". Voltar atrás é republicar a definição anterior — e é exatamente por isso que o JSON baixado importa: ele é a referência fiel do que estava publicado em cada versão. Guardar o arquivo de cada versão no repositório do time é a diferença entre "voltar atrás" e "tentar lembrar".

Baixar a definição publicada (JSON)

Com pelo menos uma versão publicada, o painel mostra Baixar definição publicada (JSON). Baixar é leitura: não executa, não publica, não mexe na agenda, custa R$ 0.

O que vem no arquivo: formatVersion (hoje 1); pipeline com id, name, version e publishedAt (UTC); e snapshot com a definição — conector, parâmetros não sensíveis da origem (endereço, banco, porta), prefixo de destino, agenda, limites (GB/mês estimado), tabelas Bronze (origem, destino, escrita full/append, coluna-chave, partição, clusterização, colunas PII marcadas) e transformações Silver/Gold (modo, origem, filtro, dependências) — além de v (versão do snapshot) e checksum.

O que não vem: nenhuma credencial (se um campo sensível for detectado, o download é recusado); nenhum dado (o arquivo descreve o pipeline, não o conteúdo das tabelas); nenhum estado de execução.

Por que ele é útil: as chaves são ordenadas e há um campo por linha, então a mesma definição produz sempre os mesmos bytes — dois arquivos de versões diferentes podem ser comparados com diff ou commitados. O checksum confere que o arquivo não foi alterado depois de baixado. O download fica registrado na auditoria (quem baixou e qual versão), e quem pode baixar é membro do workspace ou acima (viewer não). É também o artefato que o desafio do ICED pede como entrega.

Exemplo: a Comércio Aurora

A v1 de vendas está publicada com agenda ativa, diária às 09:00 UTC. Maria troca a escrita de vendas de Full para Append com atualizado_em e marca clientes.cpf como PII. Em Revisar e publicar o diff mostra três linhas, uma delas com ⚠ (a mudança de escrita é destrutiva). A frase de agenda diz que ela continua ligada. Maria marca a confirmação, publica a v2, baixa vendas-v2-definicao.json, roda diff contra o v1 que já estava no repositório do time — e vê em texto exatamente as três mudanças que a tela mostrou.

Erros comuns

Sintoma	O que conferir	Próxima ação
Publiquei e nada rodou	O estado da agenda	Comportamento esperado — use Ativar agenda ou Executar agora
Publiquei e a agenda sumiu	A frase de efeito mostrada na republicação	Reative em Ativar agenda; o produto nunca desliga sem avisar
Não consigo publicar	A caixa de confirmação de mudanças destrutivas	Leia as linhas com ⚠ e confirme conscientemente
O botão de baixar definição não aparece	Se existe versão publicada	Publique uma vez com Revisar e publicar
"Ação não permitida para o papel viewer"	Seu papel no workspace	Baixar exige `member` ou acima
Publiquei e não criou versão nova	A definição é idêntica à publicada	Esperado: publicar é idempotente quando nada mudou
Troquei a senha e a v1 continua funcionando	A versão congela a definição, não a credencial	É o comportamento desejado
Publicação bloqueada	A validação apontada na revisão	Corrija o item; não invente dependência nem credencial para avançar

O que é Preview aqui

Versionamento, execução paralela de conferência e rollback do motor de transformação são provados por teste determinístico (C04.6 = GA-candidato), e o JSON da definição é byte-determinístico. A publicação real em BigQuery depende de nuvem — Preview, sem SLA e sem tempo de publicação publicado. Nada aqui é "GA".

Faça você mesmo#

No workspace de treino Aurora Varejo, sobre um pipeline de vendas que já tenha a versão 1 publicada.

Na tela do pipeline, leia o painel Publicação e agenda: selo da versão, selo da agenda e a data de publicação.
Use Ativar agenda e confirme que o botão do meio passa a ser Pausar agenda.
Baixe Baixar definição publicada (JSON) da v1 e guarde o arquivo. Abra-o e confirme que não há nenhuma credencial e nenhum dado de tabela.
Altere a definição: troque a escrita de vendas para Append com atualizado_em e marque clientes.cpf como PII. Volte ao painel e confirme o selo Mudanças não publicadas.
Use Revisar e publicar e leia o bloco "Diferenças em relação à versão publicada" inteiro. Anote quais linhas vêm com ⚠.
Leia a frase de efeito sobre a agenda e confirme que ela diz que a agenda continua ligada.
Marque a caixa de confirmação das mudanças destrutivas e publique a v2. Baixe o JSON da v2.
Compare os dois arquivos com diff e confirme que as diferenças em texto são as mesmas que a tela mostrou. Por fim, tente publicar de novo sem mudar nada e observe que não nasce uma v3.

Você terminou quando a v2 está publicada com a agenda ainda ligada, você leu e justificou cada linha com ⚠, tem os JSON da v1 e da v2 lado a lado com um diff legível, e comprovou que publicar sem mudança não cria versão nova.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

C04.6 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".