Migracao do PostgreSQL de producao¶

Procedimento histórico de implantação inicial

Produção já opera no cluster. Este roteiro registra a migração da VPS e não deve ser repetido para atualizar uma versão ou corrigir um incidente. Tamanhos, situação de backups e compartilhamentos abaixo descrevem a preparação original e precisam de nova conferência antes de qualquer ação. Para releases atuais, consulte produção.

Este runbook documenta a migração do PostgreSQL 16 da VPS para o namespace flow-prd. O banco medido durante a preparacao ocupava aproximadamente 424 MiB, portanto um PVC de 20 GiB oferece margem inicial ampla.

Nenhum passo de restauracao e executado pelo deploy normal. O objetivo e impedir que um banco vazio receba migrations ou trafego por engano.

Garantias e limitacoes¶

StatefulSet: merchants-db, uma replica;
Service: merchants-db.flow-prd.svc.cluster.local:5432;
PVC: data-merchants-db-0, 20 GiB;
StorageClass: flow-prd-longhorn-retain, tres replicas de bloco;
retencao do PVC e do PV quando o StatefulSet for removido;
PRODUCTION_DATABASE_READY=false bloqueia deploy e rollback da aplicacao;
o cluster nao possui destino de backup Longhorn configurado atualmente;
replica de volume nao e backup e uma instancia nao e HA de PostgreSQL.

Preparacao sem indisponibilidade¶

Manter PRODUCTION_DEPLOY_ENABLED=false.
Manter PRODUCTION_DATABASE_READY=false.
Cadastrar K8S_PRODUCTION_SECRETS com o host interno de producao.
Aplicar deploy/kubernetes/bootstrap/flow-prd-storage-class.yaml com acesso administrativo ao cluster.
Habilitar temporariamente PRODUCTION_DATABASE_BOOTSTRAP_ENABLED=true.
Executar production_database_bootstrap na pipeline da main.
Retornar PRODUCTION_DATABASE_BOOTSTRAP_ENABLED=false.
Confirmar que o PVC esta Bound e o pod merchants-db-0 esta Ready.

Nesse ponto o PostgreSQL novo esta vazio. Nao execute o deploy da aplicacao.

Ensaio de backup e restauracao¶

Antes da janela final, gere um dump custom do banco da VPS e valide que ele pode ser lido pelo pg_restore. Armazene uma copia criptografada fora da VPS e fora do cluster. Registre SHA-256, tamanho, horario UTC e versao do PostgreSQL.

O ensaio pode ser restaurado no banco novo para medir tempo, mas nao deve ser considerado o corte final: a VPS continua recebendo escritas.

Janela de corte¶

Ativar pagina de manutencao ou bloquear novas operacoes de escrita.
Parar os containers de aplicacao e workers da VPS, mantendo apenas o PostgreSQL ativo.
Suspender HML, pois atualmente ele tambem usa o banco da VPS.
Confirmar ausencia de conexoes de escrita.
Gerar um novo dump final em formato custom com --no-owner --no-acl.
Calcular e registrar SHA-256 do dump.
Restaurar no merchants-db-0 usando pg_restore --clean --if-exists.
Comparar schemas, revisao do Alembic e contagens das tabelas criticas entre origem e destino.
Executar production_database_access_check; ele exige platform.merchants e platform.alembic_version restauradas.
Definir PRODUCTION_DATABASE_READY=true somente depois da validacao.
Prosseguir com build, release e deploy mantendo o Ingress desabilitado.
Validar internamente, habilitar o Ingress e somente entao virar Cloudflare.

Validacoes minimas¶

versao PostgreSQL compativel;
platform.alembic_version igual na origem e no destino;
contagem de platform.merchants, usuarios administrativos, configuracao da plataforma, mensagens e tabelas de marketing;
login administrativo;
leitura de lojistas e configuracoes de onboarding;
escrita controlada seguida de remocao do registro de teste;
logs sem erros de autenticacao, permissao ou schema.

Contingencia¶

Nao desligue nem remova o volume da VPS no dia do corte. Em caso de falha antes de aceitar novas escritas no cluster, mantenha PRODUCTION_DATABASE_READY=false e retorne o trafego para a VPS.

Depois que o cluster aceitar escritas, rollback para a VPS exige reconciliar os dados produzidos no intervalo. Por isso o ponto de decisao deve ser registrado e a antiga VPS deve permanecer preservada, mas sem escrita, durante a janela de observacao.