D1 en local: desarrollo y datos de prueba

Nada frena más el aprendizaje de una base de datos que tener miedo de tocarla. Con D1 no lo tienes, porque en desarrollo no trabajas contra tu base real: wrangler dev respalda tu binding con un SQLite de verdad que vive en tu disco, tuyo y solo tuyo, que puedes llenar, vaciar y romper cuantas veces quieras. Esta última lección del nivel cierra el círculo: crear, enlazar, consultar y agrupar ya lo sabes; ahora toca dominar el entorno donde practicas todo eso a golpe de milisegundo, con datos de prueba propios y sin rozar producción.

La base local: un SQLite de verdad

Cuando levantas wrangler dev, la plataforma no simula tu base D1 con un mock aproximado: monta un archivo SQLite auténtico dentro de .wrangler/state, y tu env.DB habla con él exactamente con la misma API que usará en producción. Es el mismo motor, el mismo SQL, los mismos métodos —prepare, bind, first, all, run, batch—, solo que los datos viven en tu máquina.

Dentro de .wrangler/state los datos de D1 se guardan como ficheros SQLite bajo un subdirectorio propio; son archivos normales que, si quieres, puedes abrir con cualquier herramienta de SQLite para inspeccionarlos por tu cuenta. No hay nada mágico ni propietario en ese estado: es SQLite en tu disco. Y como persiste entre sesiones, los datos que escribes hoy siguen ahí mañana cuando vuelvas a arrancar wrangler dev. La carpeta suele ir ignorada por git, porque es tu entorno de trabajo personal.

# arranca el runtime local con tu base D1 respaldada en disco
wrangler dev

# empezar de cero: borra el estado local y vuelve a aplicar esquema y datos
rm -rf .wrangler/state

Ejecutar SQL con wrangler d1 execute

No necesitas levantar el Worker para hablar con la base: wrangler d1 execute ejecuta SQL directamente contra ella desde la terminal, ideal para inspeccionar, corregir o poblar datos. El flag decisivo, otra vez, es --local frente a --remote: define contra qué encarnación de la base actúas.

# una consulta suelta contra la base local
wrangler d1 execute mi-app --local --command "SELECT count(*) AS total FROM usuarios"

# ejecutar un archivo entero de SQL contra la base local
wrangler d1 execute mi-app --local --file=./schema.sql

# la misma consulta, pero contra la base remota real
wrangler d1 execute mi-app --remote --command "SELECT count(*) AS total FROM usuarios"

Con --command lanzas una sentencia rápida y Wrangler te imprime el resultado como una tabla en la consola, comodísimo para comprobar de un vistazo qué hay dentro. Con --file ejecutas un archivo completo, que es como aplicas el esquema o cualquier lote de SQL. Si omites el flag, versiones recientes de Wrangler te preguntan para evitar que toques producción por accidente: no des por sentado a qué base apuntas, dilo siempre.

Y si necesitas la salida para otra herramienta o para un script, --json la devuelve como JSON estructurado en lugar de como tabla, ideal para canalizarla o comprobarla de forma automática.

# resultados en JSON, listos para canalizar a otro comando
wrangler d1 execute mi-app --local --command "SELECT * FROM usuarios" --json

Sembrar datos de prueba

Una base vacía sirve de poco para desarrollar: quieres filas realistas contra las que probar tus consultas. La forma limpia es un archivo seed.sql con las inserciones de prueba, versionado junto al código, que aplicas contra la base local cuando la necesites poblada.

INSERT OR IGNORE INTO usuarios (email) VALUES
  ('ada@ejemplo.dev'),
  ('linus@ejemplo.dev'),
  ('grace@ejemplo.dev');

# aplica el esquema y luego los datos de prueba a la base local
wrangler d1 execute mi-app --local --file=./schema.sql
wrangler d1 execute mi-app --local --file=./seed.sql

Un detalle que ahorra dolores: escribe la siembra de forma idempotente, con INSERT OR IGNORE o limpiando antes con un DELETE, para que reaplicarla sobre una base que quizá ya tiene datos no falle por colisiones de clave única. Así repoblar produce siempre el mismo estado conocido, lo ejecutes una vez o diez. Y separar schema.sql de seed.sql es deliberado: el esquema define la estructura y viaja también a producción; los datos de siembra son solo para desarrollo y nunca deben acabar en la base real.

{
  "scripts": {
    "db:reset": "rm -rf .wrangler/state && wrangler d1 execute mi-app --local --file=./schema.sql && wrangler d1 execute mi-app --local --file=./seed.sql"
  }
}

Ese mismo guion es la base de un entorno reproducible en integración continua: antes de correr las pruebas, el pipeline crea la base local, le aplica el esquema y la siembra, y arranca de un estado idéntico en cada ejecución. La base efímera de las pruebas y la base real de producción no se rozan jamás, y esa es justo la garantía que quieres.

flowchart LR
SC[schema sql] --> EX[wrangler d1 execute local]
SEED[seed sql] --> EX
EX --> ST[SQLite en wrangler state]
ST --> DEV[wrangler dev usa la base local]
style ST fill:#89b4fa,color:#11111b
style DEV fill:#a6e3a1,color:#11111b

Local y remoto: dos universos que cruzas a propósito