DB Migration CLI

CLI profissional em Node.js + TypeScript para migracao resiliente entre bancos relacionais, com processamento em lotes, checkpoint, dry-run, logs persistidos e experiencia de terminal avancada.

O comportamento atual e generico: a CLI nao depende de tipagem fixa de tabela e pode migrar qualquer tabela relacional visivel no schema configurado, desde que o conector suporte introspeccao do banco.

Requisitos

• Node.js 20+ recomendado
• npm
• Banco de origem e banco de destino acessiveis

Instalar

No diretorio do projeto:

npm install

Configurar ambiente

Crie o arquivo .env a partir do exemplo:

Windows

copy .env.example .env

Linux/macOS

cp .env.example .env

Depois edite o .env com os dados reais dos bancos.

Exemplo:

SOURCE_DB_TYPE=postgres
SOURCE_DB_URL=
SOURCE_DB_HOST=localhost
SOURCE_DB_PORT=5432
SOURCE_DB_NAME=source_db
SOURCE_DB_USER=postgres
SOURCE_DB_PASSWORD=postgres
SOURCE_DB_SCHEMA=public
SOURCE_DB_SSL_MODE=disable
SOURCE_DB_CHANNEL_BINDING=prefer

TARGET_DB_TYPE=postgres
TARGET_DB_URL=
TARGET_DB_HOST=localhost
TARGET_DB_PORT=5432
TARGET_DB_NAME=target_db
TARGET_DB_USER=postgres
TARGET_DB_PASSWORD=postgres
TARGET_DB_SCHEMA=public
TARGET_DB_SSL_MODE=disable
TARGET_DB_CHANNEL_BINDING=prefer

BATCH_SIZE=1000
LOG_LEVEL=info
DRY_RUN=false
FAIL_FAST=false
MAX_RETRIES=3
RETRY_DELAY_MS=1000
QUERY_TIMEOUT_MS=30000
CHECKPOINT_DIR=./runtime/checkpoints
LOG_DIR=./runtime/logs

Se voce usa Neon ou outro provider gerenciado, prefira URL completa + SSL:

SOURCE_DB_TYPE=postgres
SOURCE_DB_URL=postgresql://USER:PASSWORD@HOST/DB_NAME?sslmode=require&channel_binding=require
SOURCE_DB_HOST=localhost
SOURCE_DB_PORT=5432
SOURCE_DB_NAME=placeholder
SOURCE_DB_USER=placeholder
SOURCE_DB_PASSWORD=placeholder
SOURCE_DB_SCHEMA=public
SOURCE_DB_SSL_MODE=require
SOURCE_DB_CHANNEL_BINDING=require

Quando SOURCE_DB_URL ou TARGET_DB_URL estiver definido, a CLI passa a usar a connection string completa.

Como rodar

1. Validar configuracao

Antes de migrar, valide variaveis de ambiente, conectividade e tabelas suportadas:

npm run dev -- validate

2. Rodar uma simulacao de tudo

Executa toda a pipeline sem gravar no banco de destino, para todas as tabelas do schema de origem:

npm run dev -- migrate --dry-run

3. Rodar a migracao real de tudo

Executa a migracao de todas as tabelas encontradas no schema de origem:

npm run dev -- migrate --batch-size=1000

4. Retomar de um checkpoint

Continua de onde a ultima execucao parou:

npm run dev -- migrate --resume

5. Verificar status

Mostra o checkpoint salvo:

npm run dev -- status --table=users

Flags disponiveis

Comando migrate:

• --table <name>: filtra para uma tabela especifica; se omitido, migra todas
• --batch-size <size>: sobrescreve o tamanho do lote
• --dry-run: executa sem gravar no destino
• --resume: retoma a partir do checkpoint salvo
• --from-id <id>: inicia a leitura a partir de um valor explicito da chave primaria
• --limit <count>: limita a quantidade de registros processados
• --verbose: habilita logs mais detalhados

Exemplos:

npm run dev -- migrate --dry-run
npm run dev -- migrate --batch-size=500 --limit=5000
npm run dev -- migrate --table=users --resume --verbose

Rodando a versao compilada

Se quiser gerar a build primeiro:

npm run build

Depois execute:

npm start -- migrate --table=users --dry-run

O que a CLI faz

Pipeline atual:

1. Valida ambiente e argumentos
2. Conecta ao banco de origem e ao banco de destino
3. Verifica se a tabela existe
4. Conta os registros a processar
5. Le os dados em batches
6. Faz upsert em lote no destino
7. Salva checkpoint
8. Gera resumo final com metricas

Saidas geradas

• Logs persistidos em ./runtime/logs
• Checkpoints em ./runtime/checkpoints
• Resumo final no terminal com:
  • quantidade lida
  • quantidade migrada
  • quantidade ignorada
  • quantidade com erro
  • duracao total
  • throughput

Estrutura principal

• src/cli: comandos e bootstrap da CLI
• src/config: .env e registry de tabelas
• src/connectors: conectores de banco
• src/services: orquestracao da migracao
• src/mappers: transformacao dos dados
• src/validators: validacao dos registros transformados
• src/checkpoints: persistencia do estado da execucao
• src/utils: logger, retry, terminal e utilitarios
• src/types: contratos da aplicacao

Observacoes

• A base atual esta pronta para PostgreSQL como origem e destino
• A estrategia de idempotencia atual e upsert por chave primaria
• Se a tabela nao existir no destino, a CLI tenta cria-la a partir da metadata da origem
• A migracao generica exige exatamente uma chave primaria por tabela para suportar cursor e resume