Como migrar um banco SQLite local para o Cloudflare D1 em Produção

A experiência de desenvolvimento com o Cloudflare D1 é excelente, principalmente porque ele emula o comportamento do servidor através de um arquivo SQLite escondido na sua máquina local na pasta .wrangler/state. Você desenvolve toda a sua API localmente, inserindo e lendo dados de mock.

Mas e quando chega a hora de fazer o deploy para a nuvem? Como levar a estrutura das tabelas e os dados base (como configurações de cargo de um concurso) para o banco de produção?

Passo 1: Criar o banco de produção

A sua máquina local não precisa de cadastro na nuvem, mas a produção sim. Via terminal, crie o banco D1 na sua conta:

npx wrangler d1 create meu_banco

Isso retornará um ID único (database_id). Copie esse ID e cole no seu arquivo wrangler.toml:

[[d1_databases]]
binding = "DB" # Como a variável chegará no JavaScript (env.DB)
database_name = "meu_banco"
database_id = "seu-uuid-aqui"

Passo 2: O Arquivo de Esquema (Schema)

Para criar as tabelas no servidor remoto, não basta arrastar o arquivo .sqlite local para o servidor da Cloudflare. Bancos remotos exigem instruções SQL puras.

Crie um arquivo chamado schema.sql na raiz do seu projeto com a estrutura do seu banco:

DROP TABLE IF EXISTS cargos;
CREATE TABLE cargos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  nome TEXT NOT NULL
);

-- Inserindo dados essenciais (seeds)
INSERT INTO cargos (nome) VALUES ('Técnico Judiciário'), ('Analista Judiciário');

Passo 3: Executando o Seed (Migração)

Com o arquivo SQL criado, você precisa instruir o Wrangler a executar esse arquivo no servidor D1 remoto. Para isso, execute o comando com a flag --remote.

(Omitir o --remote aplicará o schema apenas no seu banco SQLite de desenvolvimento local).

npx wrangler d1 execute meu_banco --remote --file=./schema.sql

A Cloudflare enviará a transação SQL para os nós de bancos de dados. Se estiver tudo correto com a sintaxe, você verá o output das linhas alteradas.

Lembre-se: O D1 é baseado no motor do SQLite, então a sintaxe de migração precisa respeitar o dialeto SQLite (funções específicas de Postgres/MySQL, como UUID(), podem exigir adaptações para texto puro).

Para bancos massivos, a Cloudflare recomenda que você divida o schema.sql em pedaços de no máximo 100MB de limite de ingestão de texto, mas para tabelas de configuração normais, o comando acima envia toda a sua base para as nuvens de forma instantânea.