Noções Básicas de Entrega

8 exemplos para alinhar a frequência de deploy do Node.js com o risco de migração do banco de dados - 6 básicos e 2 intermediários.

Pré-requisitos

CI/CD com verificações de PR distintas e promoção de release (ver Noções Básicas de CI/CD)
Migrações em controle de versão (Prisma, Flyway ou node-pg-migrate)
Ambiente de staging que espelha os tamanhos de pool da produção
Linha de base DORA capturada (ver Métricas DORA para Equipes Node)

Exemplos Básicos

1. Deploys de Node são Rápidos; Bancos de Dados Não São

Camada	Cadência Típica	Gargalo
Imagem da API Node	Múltiplas por dia	Testes, revisão
Imagem do Worker	Diária	Compatibilidade de fila
Migração Postgres	Semanal ou quinzenal	Disciplina de expandir-contrair
Bump de versão principal de lib compartilhada	Mensal	Coordenação inter-serviços

Contêineres Node sem estado são baratos para reimplantar
Mudanças de schema são o freio - planeje migrações antes de prometer pushes diários para produção
Feature flags desacoplam o deploy de código da exposição de comportamento

Relacionado: Métricas DORA para Equipes Node - meça a saúde da entrega

2. Padrão de Migração Expandir-Contrair

Expandir: Adicionar coluna anulável ou nova tabela - fazer deploy da API que escreve em ambos os formatos.

Contrair: Preencher dados; alternar leituras para a nova forma.

Excluir: Remover coluna antiga em um release posterior após o fechamento da janela de rollback.

-- Expandir (deploy 1)
ALTER TABLE orders ADD COLUMN status_v2 TEXT;
 
-- Contrair (deploy 2) - app escreve status_v2, lê com COALESCE
-- Excluir (deploy 3)
ALTER TABLE orders DROP COLUMN status;

Cada etapa de expansão deve ser retrocompatível com a imagem da API anterior
Nunca exclua uma coluna que a release anterior ainda esteja lendo

3. Pipeline de PR vs. Pipeline de Release

Pipeline de PR (a cada push):
  lint → typecheck → unit tests → integration (Testcontainers)
 
Pipeline de release (merge para main):
  build image → scan → deploy staging → smoke → promote manual/auto para prod

O pipeline de PR prova o código; o pipeline de release prova o artefato
Marque imagens com gitSha, não latest
Bloqueie o release se a migração não foi executada em staging

4. Ordem de Deploy de API e Worker

Migração de expansão de schema (staging + prod)
  → deploy API (escreve novos campos, lê fallback)
  → deploy workers (processa novo formato de job)
  → backfill de job (se necessário)
  → deploy API (lê apenas novos campos)
  → migração de contração

Workers atrasados em relação à API são mais seguros do que workers à frente da API em mudanças destrutivas
Pause os workers durante estados intermediários incompatíveis
Documente a ordem em docs/deploy-order.md por serviço

5. Checklist de Risco de Migração

[ ] Retrocompatível com a imagem da API N-1?
[ ] Retrocompatível com a imagem do worker N-1?
[ ] Índice criado CONCURRENTLY (Postgres)?
[ ] Tempo de lock estimado para ALTER?
[ ] Caminho de rollback documentado (forward-fix vs undo)?
[ ] Teste de carga em staging após migração?

ALTER TABLE em tabelas grandes requer janela de manutenção ou ferramenta de schema online
Prisma migrate deploy em CI antes do rollout do k8s

feature branch → PR → main → staging (auto) → production (gated)

Staging usa um subconjunto do volume de dados semelhante à produção, não um DB vazio
Testes de fumaça atingem /health/ready e um caminho crítico de escrita/leitura
Promoção para produção requer ticket de mudança para indústrias regulamentadas

Exemplos Intermediários

7. Acoplando a Entrega ao Orçamento de Erros

Orçamento de erros restante > 50%  → cadência normal de deploy
Orçamento de erros 20-50%           → deploys requerem aprovação do TL
Orçamento de erros < 20%            → congelar deploys de features; apenas correções

O consumo do SLO vincula a velocidade de entrega à confiabilidade (ver SLOs e Orçamentos de Erros)
Equipes Node frequentemente fazem deploy rápido demais para a capacidade de migração do DB - o orçamento protege ambos

8. Notas de Release para Backend

## orders-api v2.14.0 (2026-07-09)
- Migração: 20260709_add_status_v2 (expandir, retrocompatível)
- Ordem de deploy: migrate → API → workers
- Feature flag: new-checkout (desligado por padrão)
- Rollback: reverter para v2.13.2; migração é apenas forward-only

Suporte e PM leem isso; link do Slack #releases
Restrições explícitas de rollback evitam surpresas às 3 da manhã

FAQs

Podemos fazer deploy de Node diariamente com migrações semanais?

Sim. Deploys de código diariamente por trás de flags; mudanças de schema semanalmente em janelas planejadas.

Quem é o responsável pelo timing das migrações?

A equipe de API propõe; DBA/plataforma aprova migrações com risco de lock. Calendário compartilhado.

Monorepos mudam a ordem de deploy?

Sim. Turborepo/Nx com grafo de dependências fazem deploy apenas dos serviços alterados, mas o repositório de migração compartilhado ainda dita a ordem.

Relacionados

Feature Flags - desacopla deploy de exposição
Entrega Canary e Progressiva - promoção segura
Métricas DORA para Equipes Node - métricas de entrega
Noções Básicas de CI/CD - separação de pipelines
Melhores Práticas de Entrega Empresarial - checklist condensado

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Pré-requisitos

CI/CD com verificações de PR distintas e promoção de release (ver Noções Básicas de CI/CD)
Migrações em controle de versão (Prisma, Flyway ou node-pg-migrate)
Ambiente de staging que espelha os tamanhos de pool da produção
Linha de base DORA capturada (ver Métricas DORA para Equipes Node)

Exemplos Básicos

1. Deploys de Node são Rápidos; Bancos de Dados Não São

Camada	Cadência Típica	Gargalo
Imagem da API Node	Múltiplas por dia	Testes, revisão
Imagem do Worker	Diária	Compatibilidade de fila
Migração Postgres	Semanal ou quinzenal	Disciplina de expandir-contrair
Bump de versão principal de lib compartilhada	Mensal	Coordenação inter-serviços

Contêineres Node sem estado são baratos para reimplantar
Mudanças de schema são o freio - planeje migrações antes de prometer pushes diários para produção
Feature flags desacoplam o deploy de código da exposição de comportamento

Relacionado: Métricas DORA para Equipes Node - meça a saúde da entrega

2. Padrão de Migração Expandir-Contrair

Expandir: Adicionar coluna anulável ou nova tabela - fazer deploy da API que escreve em ambos os formatos.

Contrair: Preencher dados; alternar leituras para a nova forma.

Excluir: Remover coluna antiga em um release posterior após o fechamento da janela de rollback.

-- Expandir (deploy 1)
ALTER TABLE orders ADD COLUMN status_v2 TEXT;
 
-- Contrair (deploy 2) - app escreve status_v2, lê com COALESCE
-- Excluir (deploy 3)
ALTER TABLE orders DROP COLUMN status;

Cada etapa de expansão deve ser retrocompatível com a imagem da API anterior
Nunca exclua uma coluna que a release anterior ainda esteja lendo

3. Pipeline de PR vs. Pipeline de Release

Pipeline de PR (a cada push):
  lint → typecheck → unit tests → integration (Testcontainers)
 
Pipeline de release (merge para main):
  build image → scan → deploy staging → smoke → promote manual/auto para prod

O pipeline de PR prova o código; o pipeline de release prova o artefato
Marque imagens com gitSha, não latest
Bloqueie o release se a migração não foi executada em staging

4. Ordem de Deploy de API e Worker

Migração de expansão de schema (staging + prod)
  → deploy API (escreve novos campos, lê fallback)
  → deploy workers (processa novo formato de job)
  → backfill de job (se necessário)
  → deploy API (lê apenas novos campos)
  → migração de contração

Workers atrasados em relação à API são mais seguros do que workers à frente da API em mudanças destrutivas
Pause os workers durante estados intermediários incompatíveis
Documente a ordem em docs/deploy-order.md por serviço

5. Checklist de Risco de Migração

[ ] Retrocompatível com a imagem da API N-1?
[ ] Retrocompatível com a imagem do worker N-1?
[ ] Índice criado CONCURRENTLY (Postgres)?
[ ] Tempo de lock estimado para ALTER?
[ ] Caminho de rollback documentado (forward-fix vs undo)?
[ ] Teste de carga em staging após migração?

ALTER TABLE em tabelas grandes requer janela de manutenção ou ferramenta de schema online
Prisma migrate deploy em CI antes do rollout do k8s

feature branch → PR → main → staging (auto) → production (gated)

Staging usa um subconjunto do volume de dados semelhante à produção, não um DB vazio
Testes de fumaça atingem /health/ready e um caminho crítico de escrita/leitura
Promoção para produção requer ticket de mudança para indústrias regulamentadas

Exemplos Intermediários

7. Acoplando a Entrega ao Orçamento de Erros

Orçamento de erros restante > 50%  → cadência normal de deploy
Orçamento de erros 20-50%           → deploys requerem aprovação do TL
Orçamento de erros < 20%            → congelar deploys de features; apenas correções

O consumo do SLO vincula a velocidade de entrega à confiabilidade (ver SLOs e Orçamentos de Erros)
Equipes Node frequentemente fazem deploy rápido demais para a capacidade de migração do DB - o orçamento protege ambos

8. Notas de Release para Backend

## orders-api v2.14.0 (2026-07-09)
- Migração: 20260709_add_status_v2 (expandir, retrocompatível)
- Ordem de deploy: migrate → API → workers
- Feature flag: new-checkout (desligado por padrão)
- Rollback: reverter para v2.13.2; migração é apenas forward-only

Suporte e PM leem isso; link do Slack #releases
Restrições explícitas de rollback evitam surpresas às 3 da manhã

FAQs

Podemos fazer deploy de Node diariamente com migrações semanais?

Sim. Deploys de código diariamente por trás de flags; mudanças de schema semanalmente em janelas planejadas.

Quem é o responsável pelo timing das migrações?

A equipe de API propõe; DBA/plataforma aprova migrações com risco de lock. Calendário compartilhado.

Monorepos mudam a ordem de deploy?

Sim. Turborepo/Nx com grafo de dependências fazem deploy apenas dos serviços alterados, mas o repositório de migração compartilhado ainda dita a ordem.

Relacionados

Feature Flags - desacopla deploy de exposição
Entrega Canary e Progressiva - promoção segura
Métricas DORA para Equipes Node - métricas de entrega
Noções Básicas de CI/CD - separação de pipelines
Melhores Práticas de Entrega Empresarial - checklist condensado

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Noções Básicas de Entrega

Buscar na documentação

Noções Básicas de Entrega