Evolucionar el esquema de un sitio desplegado

EmDash almacena las colecciones, los campos y las taxonomías en la base de datos junto con el contenido. Usa esta guía para cambiar ese modelo de contenido en producción sin confundirlo con un despliegue de código, un seed inicial o una migración del núcleo de EmDash. Los ejemplos usan Cloudflare D1; la misma separación se aplica a todos los adaptadores de base de datos.

Qué cambia qué

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

El archivo seed solo participa en la tercera fila. Su esquema y su estructura se aplican una sola vez, en la primera solicitud, antes de que se haya completado el asistente de configuración. Desplegar un archivo seed modificado sobre una base de datos existente no hace nada — la evolución del esquema de un sitio en producción siempre se realiza a través del panel de administración o de la API.

Cambiar el esquema en el panel de administración

El panel de administración es la forma principal de evolucionar un sitio desplegado. Abre Content Types en el administrador y añade, edita o elimina colecciones y campos. Los cambios surten efecto de inmediato — la API de contenido, el cargador y la interfaz de edición leen el esquema de la base de datos en tiempo de ejecución.

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

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

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

Cambiar el esquema desde la CLI

Los comandos emdash schema hablan con una instancia en ejecución a través de su API REST, así que funcionan contra un sitio desplegado igual que contra el desarrollo local. Autentícate una vez con el flujo de dispositivo:

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

Como alternativa, crea un token de API en el administrador, en Settings → API Tokens, y pásalo con --token o con la variable de entorno EMDASH_TOKEN — útil para CI.

Después, evoluciona el esquema con los mismos comandos que usarías en local:

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 se pueden incluir en un script versionado para que cada entorno reciba el mismo cambio ordenado. Los comandos no son idempotentes de forma automática: volver a ejecutar create o add-field sobre un objeto que ya existe puede fallar. Inspecciona el destino con emdash schema list o get, registra qué entorno completó cada paso y detente en el primer error.

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

Mantener sincronizado el archivo seed

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

La compilación incrusta el primer archivo seed que encuentre: .emdash/seed.json, la ruta indicada en package.json#emdash.seed o seed/seed.json. Si no hay ninguno, se incrusta un seed predeterminado integrado (el modelo del blog inicial) 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 genera uno a partir de 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 los ajustes, las colecciones, las taxonomías, los menús, las redirecciones, las áreas de widgets y las secciones del sitio en producción. Añade --with-content para incluir las entradas. Haz commit del .emdash/seed.json actualizado junto con el código que depende del nuevo esquema, de modo que un entorno nuevo siempre arranque con un modelo que el código entienda.

Ensayar cambios en un entorno de preview

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

Recuperarse de un error

• Se eliminó un campo por error. La columna y sus datos han desaparecido de la base de datos en producción. Restaura desde una copia de seguridad a un momento dado de D1 Time Travel, o vuelve a añadir el campo y restaura sus valores desde un wrangler d1 export anterior.
• Un entorno nuevo arrancó con el modelo equivocado. El seed incrustado estaba desactualizado o no existía. Actualiza .emdash/seed.json (consulta Mantener sincronizado el archivo seed), vuelve a compilar y apunta el despliegue a una base de datos vacía para arrancar 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 y después el código que los usa. Para las eliminaciones, despliega primero el código que deja de usar el campo y luego elimina el campo.