Evolucionar el esquema de un sitio desplegado

EmDash guarda las colecciones, los campos y las taxonomías en la base de datos junto al contenido. Usa esta guía para cambiar ese modelo de contenido en vivo 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 cualquier adaptador 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 estructura se aplican una 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 vivo siempre se hace 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 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 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, así que puede apuntar directamente al sitio desplegado:

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 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, lo cual resulta ú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 guardar en un script 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 contra 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 de recuperación ante desastres o un segundo despliegue del mismo sitio. Si el seed aún describe el blog inicial mientras producción ha evolucionado hacia otra cosa, todos los entornos nuevos arrancan con el modelo equivocado.

La compilación incrusta el primer archivo seed que encuentra en .emdash/seed.json, la ruta de 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 vivo de vuelta a tu repositorio. emdash export-seed lee un archivo SQLite local. Crea los archivos SQL como se describe en Crear un volcado D1 externo, carga las tablas y las filas en una base de datos local y exporta el seed:

sqlite3 prod.db < backup-schema.sql
sqlite3 prod.db < backup-folders.sql
sqlite3 prod.db < backup-data.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 vivo. 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) se ensaya con más seguridad contra una copia desechable de producción.

Recuperarse de un error

• Un campo se eliminó por error. La columna y sus datos han desaparecido de la base de datos en vivo. Restaura desde una copia de seguridad de un punto en el tiempo con Time Travel de D1, o vuelve a añadir el campo y restaura sus valores desde un volcado D1 externo anterior.
• Un entorno nuevo arrancó con el modelo equivocado. El seed incrustado estaba obsoleto o faltaba. Actualiza .emdash/seed.json (consulta Mantener sincronizado el archivo seed), recompila y apunta el despliegue a una base de datos vacía para volver a arrancar.
• El esquema y las plantillas no coinciden. Los despliegues y los cambios de esquema son independientes, así que ordénalos con criterio: los cambios aditivos del esquema (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.