Introducción
Un equipo de soporte necesita registros que pueda filtrar y actualizar sin perder la identificación de cada ticket. Cloudflare D1 es una base de datos administrada que almacena información relacionada en tablas y acepta SQL, un lenguaje para describir los datos que desea. Una tabla se parece a una hoja de cálculo: cada fila representa un ticket y las columnas con nombre contienen sus campos.
Antes de comenzar este curso, complete Conectar LabEx a su cuenta de Cloudflare. Allí aprenderá a usar la terminal de la máquina virtual de LabEx, la autorización del dispositivo, la confirmación de la cuenta y el almacenamiento del ID real de la cuenta. Si accede directamente a este laboratorio, primero debe completar ese laboratorio. También debe comprender los conceptos básicos de un Worker de JavaScript; aquí no se presupone ningún conocimiento de SQL.
Creará una base de datos, definirá reglas para validar los tickets y distinguirá los registros de práctica locales de los registros en la nube. Este laboratorio necesita una base de datos D1 desechable y ningún Worker implementado.
Use su propia cuenta de aprendizaje y una máquina virtual nueva. La configuración prepara Node.js 22.22.0 y después ejecuta npm install para instalar Wrangler 4.131.1 localmente en el proyecto y cualquier dependencia de evaluación en /home/labex/project/ticket-database. Las versiones de las dependencias directas están fijadas; la instalación crea su propio archivo de bloqueo. Durante la configuración no se ejecuta ningún inicio de sesión en la nube ni ninguna operación evaluada sobre la base de datos. En una máquina personal, instale la misma versión de Wrangler con npm install --save-dev wrangler@4.131.1 dentro de su proyecto.
Este ejercicio utiliza pequeños registros sintéticos dentro de los límites gratuitos de D1. El uso existente de la cuenta cuenta para esos límites. No necesita un dominio adquirido. Conserve esta máquina virtual hasta comprobar tanto la eliminación de los recursos como el cierre de sesión.
Autorice esta máquina virtual y seleccione la cuenta
En este paso, conectará esta terminal nueva a su propia cuenta de aprendizaje. Iniciar sesión en el Dashboard por sí solo no autoriza la máquina virtual. El permiso de D1 permite crear bases de datos, modificar SQL y eliminarlas. Revise la página de consentimiento real, incluido Background Access, antes de autorizar.
Abra el proyecto preparado e inspeccione la versión fijada de la CLI:
cd /home/labex/project/ticket-database
npx wrangler --version
Debe aparecer 4.131.1. Inicie la autorización del dispositivo; --device muestra un código para el navegador y --browser=false le permite elegir cómo abrir el navegador:
npx wrangler login --device --browser=false --scopes account:read user:read d1:write
Abra en el navegador la URL que se muestra, introduzca el código actual, confirme su cuenta de aprendizaje y los permisos, y autorice el acceso. Espere a que la terminal confirme que la operación se realizó correctamente. Nunca pegue contraseñas ni tokens en los archivos del proyecto.
Este ejemplo muestra D1 Write junto con el acceso a la cuenta y el acceso en segundo plano obligatorio. Confirme su propia cuenta de aprendizaje seleccionada antes de autorizar.
npx wrangler whoami --json
Compruebe loggedIn: true y lea después los valores name e id de la cuenta, aunque solo aparezca una cuenta en la lista. Copie el ID previsto en la configuración siguiente. La variable de shell que aparece a continuación usa 6 bytes aleatorios (12 caracteres hexadecimales) para evitar colisiones con otros estudiantes. Un documento aquí escribe el JSON situado entre las líneas JSON; $RUN se expande dentro de él.
La barra invertida delante de $schema conserva esa clave JSON literalmente; $RUN sigue expandiéndose al nombre único de esta ejecución.
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
Sustituya YOUR_ACCOUNT_ID antes de ejecutar el bloque. Mantenga abierta esta terminal para que RUN siga disponible. name identifica esta ejecución; account_id selecciona la cuenta para las operaciones en la nube. El archivo es JSON normal, que también es válido como JSONC. Escribir este archivo no implementa ningún Worker.
Cree una tabla local de tickets
En este paso, definirá un esquema: las columnas y las reglas que impone la base de datos. Primero cree el contenedor en la nube y su binding, pero mantenga locales los primeros cambios de SQL.
Cree una base de datos desechable en la nube. --binding DB proporciona al código de la aplicación un nombre corto, --update-config registra su nombre real y su UUID en wrangler.jsonc, y --use-remote=false mantiene el desarrollo en local:
npx wrangler d1 create "$RUN-db" --binding DB --update-config --use-remote=false
Lea el nombre y el ID creados y, después, inspeccione el binding guardado:
cat wrangler.jsonc
La entrada DB debe indicar la base de datos de esta ejecución. Un binding es una conexión configurada entre el código y un recurso. Su UUID identifica la base de datos en la nube, mientras que --local utiliza una base de datos SQLite independiente en esta máquina virtual. Incluya siempre --local o --remote en los comandos SQL.
CREATE TABLE define una tabla. INTEGER PRIMARY KEY proporciona a cada fila una identidad numérica única. TEXT almacena cadenas. NOT NULL prohíbe los valores ausentes y CHECK rechaza los valores que no cumplen la regla. DEFAULT proporciona un valor cuando una instrucción de inserción omite ese campo. Estas comprobaciones ayudan a evitar tickets incompletos.
Escriba el esquema y dos filas sintéticas en un archivo SQL. El marcador entre comillas SQL impide que el shell interprete el contenido. Las instrucciones SQL terminan en punto y coma. INSERT INTO empareja los nombres de las columnas con los valores de cada fila:
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 el archivo únicamente a la base de datos local:
npx wrangler d1 execute DB --local --file schema.sql
Si el comando se ejecuta correctamente, informará de la ejecución en la base de datos local. Esto no demuestra que exista ninguna tabla remota. Inspeccione las definiciones de las columnas mediante PRAGMA table_info de SQLite:
npx wrangler d1 execute DB --local --command "PRAGMA table_info(tickets);"
Deben aparecer id, subject, status y source. El campo pk identifica la clave primaria, mientras que notnull indica los valores obligatorios.
Filtre, actualice y elimine filas locales
En este paso, practicará SQL básico y dejará una marca solo local. SELECT elige las columnas, FROM identifica una tabla, WHERE filtra las filas coincidentes y ORDER BY hace predecible su orden.
npx wrangler d1 execute DB --local --command "SELECT id, subject FROM tickets WHERE status = 'open' ORDER BY id;"
El resultado debe ser el ticket 1, Cannot sign in. Las cadenas SQL utilizan comillas simples dentro de las comillas dobles del comando. Añada un ticket de práctica local:
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source) VALUES (3, 'Local rehearsal', 'local');"
UPDATE modifica las filas coincidentes. Lea siempre la condición WHERE antes de ejecutar el comando: si la omite, modificaría todas las filas.
npx wrangler d1 execute DB --local --command "UPDATE tickets SET status = 'closed' WHERE id = 3;"
Pruebe un estado no válido para comprobar que la restricción protege los datos:
npx wrangler d1 execute DB --local --command "UPDATE tickets SET status = 'lost' WHERE id = 3;"
Este comando debe fallar intencionadamente. Espere un mensaje CHECK constraint failed, no un error de autenticación ni de red. La fila conserva el estado closed. Cree y después elimine una fila desechable; DELETE elimina únicamente las filas que coinciden con su predicado:
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source) VALUES (4, 'Temporary', 'local'); DELETE FROM tickets WHERE id = 4;"
Lea las filas restantes:
npx wrangler d1 execute DB --local --command "SELECT id, subject, status, source FROM tickets ORDER BY id;"
Deben aparecer los ID 1, 2 y 3; el ticket 3 debe tener el estado closed y el origen local. El ticket 4 no debe aparecer. La actualización fallida no debe haber cambiado la fila válida.
Inicialice e inspeccione la base de datos remota
En este paso, aplicará el mismo esquema a la base de datos en la nube y demostrará que los cambios locales no se copiaron automáticamente. --remote envía estas instrucciones SQL a la base de datos identificada por el UUID de la cuenta seleccionada.
npx wrangler d1 execute DB --remote --file schema.sql
Si se le solicita confirmación, confirme únicamente la base de datos de este laboratorio. Añada una fila exclusiva de la base de datos remota con el mismo ID que la fila de práctica local, pero con datos diferentes:
npx wrangler d1 execute DB --remote --command "INSERT INTO tickets (id, subject, source) VALUES (3, 'Cloud inbox', 'remote');"
Lea explícitamente ambos 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;"
El ticket remoto 3 debe ser Cloud inbox, open, remote; el ticket local 3 debe seguir siendo Local rehearsal, closed, local. Esta diferencia demuestra que eligió el destino previsto.
En Cloudflare Dashboard, seleccione la misma cuenta y abra Storage & databases → D1 SQLite Database. Busque el nombre exacto de la base de datos de esta ejecución y abra su página de detalles. Compare su ID de base de datos con el valor de wrangler.jsonc. Utilice la vista de tablas de solo lectura, si está disponible, para inspeccionar tickets. No cree ni edite registros allí. Las respuestas SQL anteriores establecen el contenido de las filas; un recuento retrasado en Metrics no lo establece.
Ejecute la verificación de este paso antes de eliminar la base de datos.
Abra Explore Data y seleccione tickets en Studio. Inspeccione las filas sin editarlas. El nombre aleatorio de la base de datos del ejemplo pertenece a una ejecución de prueba; el suyo será diferente. El ticket 3 es Cloud inbox con origen remote, mientras que la base local conserva Local rehearsal con origen local.
Elimine los recursos desechables
En este paso, eliminará únicamente los recursos de este laboratorio mientras la máquina virtual todavía está autorizada. Termine primero todas las comprobaciones funcionales. Conserve la configuración hasta completar la verificación de la eliminación.
npx wrangler d1 delete DB
Inspeccione el aviso y confirme únicamente la base de datos de esta ejecución. Después, enumere las bases de datos:
npx wrangler d1 list --json
El nombre y el UUID de la base de datos que registró deben estar ausentes en una respuesta correcta. Es posible que queden otros recursos. Un error de autenticación o de red no permite llegar a una conclusión: resuelva el acceso y repita la lectura antes de continuar. Ejecute la verificación de este paso mientras aún tenga la sesión iniciada.
Termine la autorización de esta máquina virtual
En este paso, terminará la autorización únicamente después de que la comprobación independiente de la eliminación se haya realizado correctamente. El cierre de sesión elimina la autorización de Wrangler almacenada en esta máquina virtual; cerrar una máquina virtual por sí solo no limpia los recursos de la nube.
npx wrangler logout
npx wrangler whoami --json
Debe aparecer loggedIn: false. Esta consulta sin autenticación puede terminar con un código distinto de cero; eso solo es correcto cuando la respuesta estructurada indica explícitamente que ha cerrado la sesión. Complete la verificación y, después, cierre el entorno del laboratorio.
Resumen
Practicó la creación de una base de datos de tickets de soporte. Comprobó resultados observables de la base de datos, mantuvo explícitos la cuenta seleccionada y el estado local, y eliminó los recursos desechables antes de cerrar la sesión.
