Evolucionar un sitio desplegado | EmDash CMS Everything

EmDash almacena colecciones, campos y taxonomías en la base de datos, junto al contenido en sí. Desplegar código nuevo no cambia ese modelo de contenido, pero una nueva versión de EmDash puede migrar las tablas de base de datos gestionadas por EmDash en la primera solicitud. Esta página explica cómo cambiar el modelo de contenido de un sitio que ya está desplegado, usando Cloudflare D1 como ejemplo. Los mismos flujos de trabajo aplican a las otras opciones 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 administración o API de contenido
Despliegue de código	Plantillas, config, versión EmDash	`wrangler deploy` — puede migrar tablas de base de datos de EmDash
Bootstrap inicial	Todo, desde vacío	Migraciones + archivo seed + asistente de setup, automático en primer arranque
Evolución de esquema	Colecciones, campos, taxonomías	Panel 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 setup no se ha completado. Desplegar un archivo seed modificado contra una base de datos existente no hace nada — evolucionar el esquema de un sitio en producción siempre sucede a través del panel admin o la API.

Cambiar el esquema en el panel admin

El panel 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 UI 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 widget.

Después de cambiar el esquema, regenera los tipos TypeScript que usan tus plantillas. El comando emdash types lee el esquema de una instancia en ejecución, así 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, así 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

Como estos comandos son llamadas CLI simples, pueden ser scripteados: una “migración” repetible para tu modelo de contenido es un script shell de llamadas emdash schema, registrado en tu repositorio y ejecutado contra cada entorno en turno.

Consulta la referencia 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 fresca: 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 producción ha evolucionado a algo diferente, cada entorno fresco se bootstrapea 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 integrado (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 y áreas de widgets del sitio en producción. Agrega --with-content para incluir entradas. Commitea el .emdash/seed.json actualizado junto con el código que depende del nuevo esquema, para que un entorno fresco siempre se bootstrapee con un modelo que el código entiende.

Ensayar cambios en un entorno de preview

Un cambio de esquema destructivo (eliminar un campo, reestructurar una colección) se ensaya de manera más segura contra una copia desechable de producción.

Agrega un entorno de preview con su propia base de datos D1 a wrangler.jsonc:

{
  "env": {
    "preview": {
      "d1_databases": [{ "binding": "DB", "database_name": "emdash-db-preview" }],
    },
  },
}

Copia producción en él:

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

Despliega y ejecuta el cambio de esquema contra la URL de preview:

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

Verifica que el sitio renderiza y el admin se comporta como se espera, luego ejecuta los mismos comandos contra producción.

Recuperarse de un error

Un campo fue eliminado por error. La columna y sus datos se han ido de la base de datos en producción. Restaura desde un punto de restauración Time Travel de D1, o vuelve a agregar el campo y restaura sus valores desde un wrangler d1 export anterior.
Un entorno fresco se bootstrapeó con el modelo incorrecto. El seed incrustado estaba obsoleto 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 bootstrapear de nuevo.
El esquema y las plantillas no coinciden. Los despliegues y los cambios de esquema son independientes, así que ordénalos deliberadamente: los cambios de esquema aditivos (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.