Evolucionar el esquema de un sitio desplegado

EmDash almacena colecciones, campos y taxonomías en la base de datos junto al contenido. Usa esta guía para cambiar el modelo de contenido en producción sin confundirlo con un despliegue de código, un seeding inicial o una migración core de EmDash. Los ejemplos usan Cloudflare D1; la misma separación aplica a cada adaptador de base de datos.

Qué cambia qué

Un sitio pasa por cuatro flujos de trabajo distintos. Cada uno toca una capa diferente:

Flujo de trabajo	Qué cambia	Cómo
Edición de contenido	Entradas, medios, configuración	Panel de admin o API de contenido
Despliegue de código	Templates, config, versión EmDash	`wrangler deploy` — puede migrar tablas de BD gestionadas por EmDash
Bootstrap inicial	Todo, desde vacío	Migraciones + archivo seed + asistente de configuración, automático en el primer inicio
Evolución del esquema	Colecciones, campos, taxonomías	Panel de admin o `emdash schema` contra el sitio en producción (esta página)

El archivo seed solo participa en la tercera fila. Se aplica una vez, cuando la base de datos está vacía y el asistente de configuración no se ha completado. Desplegar un archivo seed cambiado contra una base de datos existente no hace nada — evolucionar el esquema de un sitio en producción siempre ocurre a través del panel de admin o la API.

Cambiar el esquema en el panel de admin

El panel de admin es la forma principal de evolucionar un sitio desplegado. Abre Content Types en el admin y agrega, edita o elimina colecciones y campos. Los cambios surten efecto inmediatamente — la API de contenido, el loader y la interfaz de edición leen el esquema de la base de datos en tiempo de ejecución.

Consulta Colecciones y campos para los tipos de campo disponibles, reglas de validación y opciones de widgets.

Después de cambiar el esquema, regenera los tipos TypeScript que usan tus templates. El comando emdash types lee el esquema de una instancia en ejecución, por lo que puede apuntar al sitio desplegado directamente:

npx emdash types --url https://example.com

Cambiar el esquema desde la CLI

Los comandos emdash schema se comunican con una instancia en ejecución a través de su API REST, por lo que funcionan contra un sitio desplegado de la misma manera que contra el dev local. Autentícate una vez con el flujo de dispositivo:

npx emdash login --url https://example.com

Alternativamente, crea un token API en el admin bajo Configuración → Tokens API y pásalo con --token o la variable de entorno EMDASH_TOKEN — útil para CI.

Luego evoluciona el esquema con los mismos comandos que usarías localmente:

npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com

Estos comandos pueden ser registrados en un script para que cada entorno reciba el mismo cambio ordenado. Los comandos no son automáticamente idempotentes: volver a ejecutar create o add-field contra un objeto que ya existe puede fallar. Inspecciona el objetivo con emdash schema list o get, registra qué entorno completó cada paso y detente en el primer error.

Consulta la referencia de CLI para la lista completa de comandos.

Mantener el archivo seed sincronizado

El archivo seed incrustado en tu build determina con qué se inicializa una base de datos nueva: un nuevo entorno de preview, una reconstrucción de recuperación ante desastres o un segundo despliegue del mismo sitio. Si el seed todavía describe el blog de inicio mientras la producción ha evolucionado a otra cosa, cada entorno nuevo se inicializa con el modelo incorrecto.

El build incrusta el primer archivo seed encontrado en .emdash/seed.json, la ruta en package.json#emdash.seed o seed/seed.json. Si ninguno está presente, se incrusta un seed predeterminado incorporado (el modelo del blog de inicio), y astro dev registra una advertencia.

Después de evolucionar el esquema de un sitio desplegado, exporta el modelo en producción de vuelta a tu repositorio. emdash export-seed lee un archivo SQLite local, y wrangler d1 export produce uno desde la base de datos D1 desplegada:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

El seed exportado contiene la configuración, colecciones, taxonomías, menús, redirecciones, áreas de widgets y secciones del sitio en producción. Agrega --with-content para incluir entradas. Haz commit del .emdash/seed.json actualizado junto con el código que depende del nuevo esquema, para que un entorno nuevo siempre se inicialice con un modelo que el código entiende.

Ensayar cambios en un entorno de preview

Un cambio destructivo de esquema (eliminar un campo, reestructurar una colección) es más seguro ensayarlo contra una copia desechable de producción.

Crea una base de datos D1 de preview separada y deja que Wrangler la agregue al entorno preview:
```
npx wrangler d1 create emdash-db-preview \
  --binding DB --env preview --update-config
```
Confirma que env.preview.d1_databases contiene el nuevo nombre de base de datos y UUID. Los bindings no se heredan de la configuración Wrangler de nivel superior.

Exporta producción, luego importa el SQL a través del binding DB del entorno de preview:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
npx wrangler d1 execute DB --env preview --remote --file=./prod.sql

Construye el proyecto, despliégalo en el entorno de preview, luego ejecuta el cambio de esquema contra la URL de preview:

npm run build
npx wrangler deploy --env preview
npx emdash schema remove-field posts legacy_field --url https://preview.example.com

Verifica las páginas públicas, formularios del admin, tipos generados y cualquier template que lea los campos cambiados. Toma un respaldo nuevo de la base de datos de producción, luego ejecuta los mismos comandos una vez contra producción.

Recuperarse de un error

Se eliminó un campo por error. La columna y sus datos desaparecieron de la base de datos en producción. Restaura desde un punto de respaldo D1 Time Travel, o vuelve a agregar el campo y restaura sus valores desde un wrangler d1 export anterior.
Un entorno nuevo se inicializó con el modelo incorrecto. El seed incrustado estaba desactualizado o faltaba. Actualiza .emdash/seed.json (consulta Mantener el archivo seed sincronizado), reconstruye y apunta el despliegue a una base de datos vacía para inicializar de nuevo.
El esquema y los templates no concuerdan. Los despliegues y los cambios de esquema son independientes, así que ordénalos deliberadamente: los cambios aditivos de esquema (nueva colección, nuevo campo opcional) van primero, luego el código que los usa. Para eliminaciones, despliega primero el código que deja de usar el campo, luego elimina el campo.