Introdução
Seu serviço de tickets precisa adicionar urgência sem perder as solicitações existentes. Uma atualização de esquema pode falhar se as linhas antigas não atenderem a uma nova regra. Você criará uma migração ordenada, testará a alteração localmente e aplicará o mesmo arquivo remotamente, preservando as identidades e os assuntos dos tickets.
Este laboratório começa de forma independente com uma migração inicial fornecida. Ele pressupõe que você já conhece a criação de bancos de dados e o SQL básico do D01, mas não usa nenhuma VM ou banco de dados anterior.
Use sua própria conta de aprendizagem e uma VM nova. A configuração prepara o Node.js 22.22.0 e depois executa npm install para instalar o Wrangler 4.131.1 local ao projeto e quaisquer dependências de avaliação em /home/labex/project/ticket-database. As versões das dependências diretas estão fixadas; a instalação cria seu próprio lockfile. Nenhum login na nuvem ou trabalho de banco de dados avaliado é executado durante a configuração. Em uma máquina pessoal, instale a mesma versão do Wrangler com npm install --save-dev wrangler@4.131.1 no seu projeto.
Este exercício usa pequenos registros sintéticos dentro das franquias gratuitas do D1. O uso existente da conta é contabilizado nessas franquias. Não é necessário ter um domínio comprado. Mantenha esta VM até verificar a exclusão dos recursos e o logout.
Autorizar esta VM e selecionar a conta
Nesta etapa, você conecta este terminal novo à sua própria conta de aprendizagem. Fazer login no Dashboard, por si só, não autoriza a VM. A permissão do D1 permite criar, alterar e excluir bancos de dados. Leia a página de consentimento real, incluindo o acesso em segundo plano (Background Access), antes de autorizar.
Abra o projeto preparado e verifique a versão fixada da CLI:
cd /home/labex/project/ticket-database
npx wrangler --version
O resultado esperado é 4.131.1. Inicie a autorização do dispositivo; --device exibe um código para o navegador, e --browser=false permite que você escolha como abrir o navegador:
npx wrangler login --device --browser=false --scopes account:read user:read d1:write
Abra a URL exibida no navegador, informe o código atual, confirme sua conta de aprendizagem e as permissões e autorize. Aguarde a confirmação de sucesso no terminal. Nunca cole senhas ou tokens em arquivos do projeto.
npx wrangler whoami --json
Verifique loggedIn: true e leia o name e o id da conta, mesmo que apenas uma conta seja listada. Copie o ID pretendido para a configuração abaixo. A variável de shell a seguir usa 6 bytes aleatórios (12 caracteres hexadecimais) para evitar conflitos com outros estudantes. Um here-document grava o JSON entre as linhas JSON; $RUN é expandido dentro dele.
A barra invertida antes de $schema mantém essa chave JSON literal; $RUN continua sendo expandido para o nome único desta execução.
RUN=labex-c04-d03-$(openssl rand -hex 6)
cat > wrangler.jsonc <<JSON
{
"\$schema": "./node_modules/wrangler/config-schema.json",
"name": "$RUN",
"account_id": "YOUR_ACCOUNT_ID",
"main": "src/index.js",
"compatibility_date": "2026-09-15",
"workers_dev": true,
"preview_urls": false
}
JSON
Substitua YOUR_ACCOUNT_ID antes de executar o bloco. Mantenha este terminal aberto para que RUN continue disponível. name identifica esta execução; account_id seleciona a conta usada nas operações na nuvem. O arquivo é um JSON comum, que também é um JSONC válido. Escrevê-lo não implanta nenhum Worker.
Preparar o banco de dados existente de tickets
Nesta etapa, você prepara a versão existente do banco de dados da aplicação. Uma migração é um arquivo SQL numerado que descreve uma alteração no esquema. O Wrangler registra os nomes dos arquivos aplicados em d1_migrations, para que as execuções futuras diferenciem o trabalho concluído do trabalho pendente. A configuração fornece 0001_initial.sql como a versão antiga da aplicação; você criará a atualização.
Crie um banco de dados descartável na nuvem. --binding DB fornece ao código da aplicação um nome curto, --update-config registra o nome real e o UUID em wrangler.jsonc, e --use-remote=false mantém o desenvolvimento local:
npx wrangler d1 create "$RUN-db" --binding DB --update-config --use-remote=false
Leia o nome e o ID criados e inspecione o binding salvo:
cat wrangler.jsonc
A entrada DB deve identificar o banco de dados desta execução. Um binding é uma conexão configurada entre o código e um recurso. O UUID identifica o banco de dados na nuvem, enquanto --local usa um banco de dados SQLite separado nesta VM. Sempre inclua --local ou --remote nos comandos SQL.
Leia o esquema antigo antes de aplicá-lo:
cat migrations/0001_initial.sql
Ele contém dois tickets existentes e nenhuma coluna de prioridade. Aplique-o separadamente aos destinos local e remoto, confirmando o banco de dados deste laboratório quando solicitado:
npx wrangler d1 migrations apply DB --local
npx wrangler d1 migrations apply DB --remote
Inspecione as linhas e o estado das migrações aplicadas:
npx wrangler d1 execute DB --remote --command "SELECT id, subject, status, source FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
Os dois tickets originais devem existir; a migração aplicada é 0001_initial.sql. Uma migração aplicada faz parte do histórico: crie um novo arquivo para alterações posteriores em vez de editar esse histórico.
Adicionar localmente uma prioridade com restrições
Nesta etapa, você atribui uma prioridade padrão aos tickets existentes sem excluir a tabela. ALTER TABLE ... ADD COLUMN altera uma tabela diretamente. Uma coluna adicionada como não nula precisa de um valor padrão útil para as linhas antigas. CHECK limita as prioridades a normal ou urgent.
Crie a próxima migração numerada:
npx wrangler d1 migrations create DB add_priority
Neste projeto novo, o comando cria migrations/0002_add_priority.sql. Verifique esse nome de arquivo na saída. Grave a alteração nesse novo arquivo:
cat > migrations/0002_add_priority.sql <<'SQL'
ALTER TABLE tickets ADD COLUMN priority TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('normal','urgent'));
SQL
Liste as migrações pendentes e aplique a alteração somente localmente:
npx wrangler d1 migrations list DB --local
npx wrangler d1 migrations apply DB --local
Os dois tickets existentes devem receber normal. Adicione um ticket urgente e consulte-o:
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'local', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id;"
Uma prioridade fora do conjunto permitido deve falhar, em vez de entrar silenciosamente na tabela:
npx wrangler d1 execute DB --local --command "UPDATE tickets SET priority = 'critical' WHERE id = 3;"
A saída esperada contém CHECK constraint failed; esse erro intencional mantém o ticket 3 como urgent. Leia PRAGMA table_info(tickets) no banco de dados remoto para verificar que o esquema da nuvem ainda é a versão antiga:
npx wrangler d1 execute DB --remote --command "PRAGMA table_info(tickets);"
Ainda não existe priority no banco remoto. O sucesso da migração local não atualiza a nuvem.
Aplicar remotamente a migração testada
Nesta etapa, você implanta no banco de dados remoto o mesmo arquivo revisado. Verifique o trabalho pendente antes de confirmar:
npx wrangler d1 migrations list DB --remote
npx wrangler d1 migrations apply DB --remote
Apenas 0002_add_priority.sql deve estar pendente. As linhas existentes são preservadas. Adicione um ticket urgente remoto e inspecione os dados e o histórico das migrações:
npx wrangler d1 execute DB --remote --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'remote', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
Os tickets 1 e 2 mantêm seus assuntos e têm a prioridade normal; o ticket 3 é urgent. Os dois nomes de arquivo numerados estão registrados. Execute a aplicação novamente:
npx wrangler d1 migrations apply DB --remote
O comando deve informar que não há migrações pendentes e deve deixar as linhas inalteradas. É por isso que a tabela de histórico é importante: executar a implantação novamente não executa de novo os arquivos concluídos. No Dashboard, abra o banco de dados D1 desta execução e inspecione a visualização do esquema/tabela para relacionar a nova coluna ao resultado da CLI. Não edite o esquema ali.
Este exemplo mostra os dois tickets originais com a prioridade padrão normal e o novo ticket remoto com prioridade urgent. O nome gerado do banco de dados identifica esta execução de exemplo; o seu será diferente. As consultas SQL, o histórico de migrações e as verificações de restrições acima confirmam o resultado; a captura é uma referência visual.
Excluir os recursos descartáveis
Nesta etapa, você remove somente os recursos deste laboratório enquanto a VM ainda está autorizada. Conclua todas as verificações funcionais primeiro. Mantenha a configuração até concluir a verificação da exclusão.
npx wrangler d1 delete DB
Leia o prompt e confirme que ele mostra somente o banco de dados desta execução. Em seguida, liste os bancos de dados:
npx wrangler d1 list --json
O nome e o UUID do banco de dados registrados por você devem estar ausentes em uma resposta bem-sucedida. Outros recursos podem permanecer. Um erro de autenticação ou de rede não é conclusivo: resolva o problema de acesso e repita a leitura antes de continuar. Execute a verificação desta etapa enquanto ainda estiver conectado.
Encerrar a autorização desta VM
Nesta etapa, encerre a autorização somente depois que a verificação independente da exclusão for aprovada. O logout remove a autorização armazenada do Wrangler nesta VM; fechar uma VM, por si só, não faz a limpeza na nuvem.
npx wrangler logout
npx wrangler whoami --json
O resultado esperado é loggedIn: false. Essa consulta sem autenticação pode terminar com código diferente de zero; isso só é esperado quando a resposta estruturada informa explicitamente que você está desconectado. Conclua a verificação e depois feche o ambiente do laboratório.
Resumo
Você praticou a migração de um esquema de tickets. Verificou resultados observáveis do banco de dados, manteve explícitos a conta selecionada e o estado local e removeu os recursos descartáveis antes de fazer logout.
