Introdução
Uma equipe de suporte precisa de registros que possam ser filtrados e atualizados sem perder a identificação de cada ticket. O Cloudflare D1 é um banco de dados gerenciado que armazena informações relacionadas em tabelas e aceita SQL, uma linguagem usada para descrever os dados desejados. Uma tabela se parece com uma planilha: cada linha representa um ticket, e as colunas nomeadas armazenam seus campos.
Antes de iniciar este curso, conclua Connect LabEx to Your Cloudflare Account. Esse laboratório ensina a usar o terminal da VM do LabEx, autorizar o dispositivo, confirmar a conta e salvar o ID real da conta. Se você estiver entrando diretamente neste laboratório, faça aquele laboratório primeiro. Você também deve entender o básico de um Worker em JavaScript; não é necessário ter conhecimento de SQL.
Você criará um banco de dados, definirá regras para tickets válidos e distinguirá registros de prática locais dos registros na nuvem. Este laboratório precisa de um único banco de dados D1 descartável e não exige um Worker implantado.
Use sua própria conta de aprendizado e uma VM nova. A configuração prepara o Node.js 22.22.0 e, em seguida, executa npm install para instalar o Wrangler 4.131.1 localmente no projeto e quaisquer dependências de avaliação em /home/labex/project/ticket-database. As versões das dependências diretas são fixadas; a instalação cria seu próprio lockfile. Nenhum login na nuvem nem operação avaliada no banco de dados é executada 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 também é contabilizado nessas franquias. Nenhum domínio adquirido é necessário. Mantenha esta VM até confirmar a exclusão dos recursos e o logout.
Autorize esta VM e selecione a conta
Nesta etapa, você conectará este terminal novo à sua própria conta de aprendizado. Fazer login no Dashboard, por si só, não autoriza a VM. A permissão do D1 permite criar bancos de dados, alterar SQL e excluir bancos de dados. Revise a página de consentimento real, incluindo 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 aprendizado e as permissões e autorize o acesso. Aguarde a confirmação de sucesso no terminal. Nunca cole senhas ou tokens nos arquivos do projeto.
Este exemplo mostra D1 Write junto com o acesso à conta e o acesso em segundo plano obrigatório. Confirme sua própria conta de aprendizado selecionada antes de autorizar.
npx wrangler whoami --json
Verifique loggedIn: true e leia o name e o id da conta, mesmo quando apenas uma conta estiver listada. Copie o ID desejado para a configuração abaixo. A variável de shell a seguir usa 6 bytes aleatórios, ou 12 caracteres hexadecimais, para evitar colisões com outros alunos. 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-d01-$(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. Escrever esse arquivo não implanta nenhum Worker.
Crie uma tabela local de tickets
Nesta etapa, você definirá um schema: as colunas e regras impostas pelo banco de dados. Primeiro, crie o contêiner na nuvem e sua binding, mas mantenha as primeiras alterações SQL apenas localmente.
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, em seguida, verifique a binding salva:
cat wrangler.jsonc
A entrada DB deve indicar o banco de dados desta execução. Uma 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.
CREATE TABLE define uma tabela. INTEGER PRIMARY KEY fornece a cada linha uma identidade numérica exclusiva. TEXT armazena strings. NOT NULL impede valores ausentes, e CHECK rejeita valores que estejam fora da regra. DEFAULT fornece um valor quando um INSERT não informa aquele campo. Essas verificações ajudam a evitar tickets incompletos.
Grave o schema e duas linhas sintéticas em um arquivo SQL. O marcador SQL entre aspas impede que o shell interprete o conteúdo. As instruções SQL terminam com ponto e vírgula. INSERT INTO associa os nomes das colunas aos valores de cada linha:
cat > schema.sql <<'SQL'
CREATE TABLE tickets (
id INTEGER PRIMARY KEY,
subject TEXT NOT NULL CHECK(length(trim(subject)) > 0),
status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open','closed')),
source TEXT NOT NULL
);
INSERT INTO tickets (id, subject, status, source) VALUES
(1, 'Cannot sign in', 'open', 'seed'),
(2, 'Invoice copy', 'closed', 'seed');
SQL
Aplique o arquivo somente ao banco de dados local:
npx wrangler d1 execute DB --local --file schema.sql
Um comando bem-sucedido informa que a execução ocorreu no banco de dados local. Isso não comprova que exista uma tabela remota. Inspecione as definições das colunas usando o PRAGMA table_info do SQLite:
npx wrangler d1 execute DB --local --command "PRAGMA table_info(tickets);"
O resultado esperado inclui id, subject, status e source. O campo pk identifica a chave primária, enquanto notnull registra os valores obrigatórios.
Filtre, atualize e remova linhas locais
Nesta etapa, você praticará SQL básico e deixará um marcador somente local. SELECT escolhe as colunas, FROM identifica uma tabela, WHERE filtra as linhas correspondentes e ORDER BY torna a ordem previsível.
npx wrangler d1 execute DB --local --command "SELECT id, subject FROM tickets WHERE status = 'open' ORDER BY id;"
O resultado é o ticket 1, Cannot sign in. As strings SQL usam aspas simples dentro das aspas duplas do comando. Adicione um ticket local de prática:
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source) VALUES (3, 'Local rehearsal', 'local');"
UPDATE altera as linhas correspondentes. Sempre leia a condição WHERE antes da execução: se ela fosse omitida, todas as linhas seriam alteradas.
npx wrangler d1 execute DB --local --command "UPDATE tickets SET status = 'closed' WHERE id = 3;"
Tente usar um status inválido para ver a restrição protegendo os dados:
npx wrangler d1 execute DB --local --command "UPDATE tickets SET status = 'lost' WHERE id = 3;"
Este comando deve falhar intencionalmente. Espere uma mensagem CHECK constraint failed, não uma falha de autenticação ou de rede. A linha continua com o status closed. Crie e depois exclua uma linha descartável; DELETE remove apenas as linhas que correspondem ao seu predicado:
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source) VALUES (4, 'Temporary', 'local'); DELETE FROM tickets WHERE id = 4;"
Leia as linhas restantes:
npx wrangler d1 execute DB --local --command "SELECT id, subject, status, source FROM tickets ORDER BY id;"
O resultado esperado contém os IDs 1, 2 e 3; o ticket 3 está closed e tem origem local. O ticket 4 não aparece. A atualização que falhou não deve ter alterado a linha válida.
Popule e inspecione o banco de dados remoto
Nesta etapa, você aplicará o mesmo schema ao banco de dados na nuvem e comprovará que as alterações locais não foram aplicadas automaticamente. --remote envia estas instruções SQL ao banco de dados identificado pelo UUID na conta selecionada.
npx wrangler d1 execute DB --remote --file schema.sql
Se for solicitado, confirme apenas o banco de dados deste laboratório. Adicione uma linha exclusiva do ambiente remoto com o mesmo ID da linha de prática local, mas com dados diferentes:
npx wrangler d1 execute DB --remote --command "INSERT INTO tickets (id, subject, source) VALUES (3, 'Cloud inbox', 'remote');"
Leia explicitamente os dois destinos:
npx wrangler d1 execute DB --remote --command "SELECT id, subject, status, source FROM tickets ORDER BY id;"
npx wrangler d1 execute DB --local --command "SELECT id, subject, status, source FROM tickets ORDER BY id;"
O ticket remoto 3 é Cloud inbox, open, remote; o ticket local 3 continua sendo Local rehearsal, closed, local. Essa diferença comprova que você escolheu o destino correto.
No Cloudflare Dashboard, selecione a mesma conta e abra Storage & databases → D1 SQLite Database. Encontre o nome exato do banco de dados desta execução e abra a página de detalhes. Compare o ID do banco de dados com o valor em wrangler.jsonc. Use a visualização de tabela somente leitura, se estiver disponível, para inspecionar tickets. Não crie nem edite registros nessa página. As respostas SQL acima estabelecem o conteúdo das linhas; uma contagem atrasada em Metrics não estabelece esse conteúdo.
Execute a verificação desta etapa antes de excluir o banco de dados.
Abra Explore Data e selecione tickets no Studio. Inspecione as linhas sem editá-las. O nome aleatório do banco no exemplo pertence a uma execução de teste; o seu será diferente. O ticket 3 é Cloud inbox com origem remote, enquanto o banco local ainda contém Local rehearsal com origem local.
Exclua os recursos descartáveis
Nesta etapa, você removerá apenas os recursos deste laboratório enquanto a VM ainda estiver autorizada. Conclua primeiro todas as verificações funcionais. Mantenha a configuração até concluir a verificação da exclusão.
npx wrangler d1 delete DB
Leia o prompt e confirme apenas 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 é inconclusivo: resolva o problema de acesso e repita a leitura antes de continuar. Execute a verificação desta etapa enquanto ainda estiver conectado.
Encerre a autorização desta VM
Nesta etapa, você encerrará 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 um código diferente de zero; isso só é esperado quando a resposta estruturada indicar explicitamente que você saiu da sessão. Conclua a verificação e depois feche o ambiente do laboratório.
Resumo
Você praticou a criação de um banco de dados de tickets de suporte. 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 sair da sessão.
