0009 - D1 Schema Remote Drift Mitigation

Status: Aceito Data: 2026-02-21 Autor: Antigravity (IA)

Contexto

Durante o processo de migração de validação de papéis de usuários (ROLE: ENTERPRISE), foi identificado um Erro HTTP 500 persistente na criação de novos usuários através do frontend do Painel Administrativo.

A análise do endpoint POST /manager/users em ambiente local e posterior deploy revelou a falha: D1_ERROR: table users has no column named stripe_metered_subscription_item_id

Isso indicou que as migrações SQL geradas localmente não foram propagadas ou foram ignoradas pelo bucket remoto do Cloudflare D1 em algum momento anterior, criando uma assincronia entre o ORM Drizzle em produção e o Schema físico no banco.

Uma tentativa de rolar as migrações antigas utilizando o comando padrão wrangler d1 migrations apply obrain-db --remote resultou em conflito duplo Duplicate Column Name: video_url, visto que algumas partes da migração já estavam em produção de outras formas, bloqueando o processo automático.

Decisão

Proibida a reinicialização forçada do banco do zero (drop) devido a ser de Produção, optou-se pela intervenção pontual com manipulação manual DDL diretamente no worker live.

• Executada instrução base interativa localmente de identificação de campos na Cloudflare CLI de Produção: npx wrangler d1 execute obrain-db --remote --command="PRAGMA table_info(users);"

• Confirmada a ausência das colunas de assinatura, optamos por ejetar os comandos ALTER TABLE em runtime contornando o tracker imutável da tabela de d1_migrations: ALTER TABLE users ADD COLUMN stripe_metered_subscription_item_id TEXT;

Consequências

• Positivas:
  • Sem downtime no ecossistema e dados persistidos.
  • Zero perda dados (A integridade de Users foi preservada).
  • Os endpoints dependentes do objeto "Users" normalizado pelo Drizzle voltaram a funcionar instantaneamente retornando Status 201 Created.
• Negativas/Alerta:
  • A tabela de governança de migrações (d1_migrations) permanece num estado inconsistente contra as migrations físicas presentes no projeto (drizzle/0006...). Futuras migrações massivas precisarão utilizar a flag sqlite squashing para reequilibrar a base ou gerar um delta migration específico para ignorar essa fase de discrepância do Schema.