Gestionar migraciones de base de datos del núcleo

Las migraciones del núcleo de EmDash actualizan las tablas propias de EmDash y las columnas estándar en las tablas de contenido. No crean, eliminan ni renombran sus colecciones y campos; consulte Evolving a Deployed Site para cambios en el modelo de contenido.

El modo de migración en tiempo de ejecución es auto por defecto, por lo que los despliegues existentes siguen aplicando migraciones del núcleo pendientes al iniciar. Las migraciones gestionadas por despliegue permiten que un build migre su base de datos antes de que el nuevo código de aplicación reciba tráfico, y luego permiten que el tiempo de ejecución verifique o confíe en ese paso de despliegue.

Build, migrate, deploy, check

Un build o sync de Astro escribe .emdash/migrations.json. Este manifiesto sin secretos registra la versión exacta de EmDash, el conjunto ordenado de migraciones, la configuración de locale y el ejecutor de migraciones del adaptador utilizado por ese build.

Ejecute estos comandos desde el proyecto cuyas dependencias produjeron el manifiesto. Primero construya e inspeccione el objetivo.

pnpm build
pnpm emdash migrate --status

Después de confirmar que el objetivo reportado es la base de datos prevista, inicie la migración interactiva. Revise el objetivo nuevamente en el prompt antes de confirmar. Luego despliegue el mismo build y verifique el esquema desplegado.

pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

emdash migrate --status reporta migraciones aplicadas, pendientes y desconocidas sin modificar la base de datos. El comando simple emdash migrate muestra el objetivo y solicita confirmación antes de aplicar migraciones pendientes.

--check nunca aplica migraciones y termina con código distinto de cero cuando hay migraciones conocidas pendientes o la base de datos contiene registros de migración desconocidos para el build. Use --status cuando desee inspeccionar los mismos conjuntos de migraciones sin el estado de salida distinto de cero de “trabajo requerido” de check. La referencia CLI distingue códigos de salida pendientes, desconocidos, de confirmación, interrupción y operacionales.

La aplicación no interactiva y cada aplicación con --json requieren --expected-target-fingerprint; el comando falla si el objetivo resuelto no coincide. Use estas opciones en trabajos de despliegue automatizados, no para el flujo de trabajo interactivo descrito arriba.

Use --manifest path/to/migrations.json para un manifiesto almacenado en otra ubicación. Para investigación local, --from-config [--config astro.config.mjs] evalúa explícitamente la configuración de proyecto confiable sin ejecutar hooks de Astro ni iniciar un servidor. Los pipelines de despliegue deben consumir el manifiesto del build.

Seleccionar la base de datos explícitamente

El adaptador configurado contribuye información de objetivo sin secretos al manifiesto. Las credenciales permanecen en variables de entorno y son leídas solo por el comando de migración.

Adaptador	Objetivo del manifiesto	Variable de credencial predeterminada	Sobrescritura útil
SQLite	Ruta de base de datos o URL `file:`	—	`--database <ruta>`
libSQL	URL pública	`TURSO_AUTH_TOKEN`	Configurar `migrationAuthTokenEnv`
PostgreSQL	Nombre de variable de conexión	`DATABASE_URL`	`--database-url-env <nombre>`
Cloudflare D1	Nombre de binding de Wrangler	`CLOUDFLARE_API_TOKEN`	`--d1`, `--account-id`, `--wrangler-config`, `--wrangler-env`
Hyperdrive	Nombre de binding primario y variable de origen	Variable direct-origin específica del binding	Configurar `migrationConnectionStringEnv`

Las rutas SQLite relativas se resuelven desde la raíz del proyecto, no desde el paquete EmDash instalado ni desde el subdirectorio actual del shell. Las etiquetas de objetivo de PostgreSQL, libSQL e Hyperdrive omiten credenciales y parámetros de URL.

Provisionar D1 antes de migrarlo

Crear una base de datos D1 y migrar su esquema son operaciones separadas. emdash migrate nunca crea una base de datos faltante.

Provisione la base de datos y registre su UUID de producción.
```
pnpm wrangler d1 create my-site-production
```
Agregue esa UUID al binding y entorno previstos en wrangler.jsonc.
Construya el sitio para que el binding D1 se registre en .emdash/migrations.json.

Configure el ID de cuenta y un token con permiso de edición de D1. Inspeccione el objetivo seleccionado, luego ejecute la migración interactiva. Confirme el prompt solo cuando la cuenta y la base de datos coincidan con la base de datos de producción prevista.

export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."
pnpm emdash migrate \
  --status \
  --wrangler-config wrangler.jsonc \
  --wrangler-env production
pnpm emdash migrate \
  --wrangler-config wrangler.jsonc \
  --wrangler-env production

Alternativamente puede proporcionar --account-id con --d1 <uuid-o-nombre-de-base-de-datos>. La búsqueda por nombre debe resolverse a exactamente una base de datos. Los IDs de vista previa, IDs de marcador de posición, cuentas en conflicto y bindings ambiguos fallan de forma cerrada.

Configurar migraciones D1 en CI

D1 no proporciona el bloqueo de migración consultivo usado por PostgreSQL. Ejecute como máximo un trabajo de migración por cuenta y UUID de base de datos.

Configure los siguientes secretos y variables en el entorno de CI:

Secreto CLOUDFLARE_API_TOKEN: un token con permiso de edición de D1.
Variable CLOUDFLARE_ACCOUNT_ID: el ID de cuenta de Cloudflare que posee la base de datos.
Variable D1_DATABASE_ID: el UUID de la base de datos D1 de producción.
Variable EMDASH_TARGET_FINGERPRINT: la huella digital impresa por emdash migrate --status después de haber revisado la cuenta y la base de datos localmente.

El siguiente flujo de trabajo de GitHub Actions usa esos valores y vincula el grupo de concurrencia a ambos identificadores inmutables de D1. Su paso de aplicación es no interactivo, por lo que proporciona explícitamente la huella digital del objetivo revisado.

name: Deploy

on:
  workflow_dispatch:

concurrency:
  group: emdash-migrations-${{ vars.CLOUDFLARE_ACCOUNT_ID }}-${{ vars.D1_DATABASE_ID }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - name: Inspect EmDash migration target
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --status --json \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"
      - name: Apply EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          EMDASH_TARGET_FINGERPRINT: ${{ vars.EMDASH_TARGET_FINGERPRINT }}
        run: |
          pnpm emdash migrate \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}" \
            --expected-target-fingerprint "$EMDASH_TARGET_FINGERPRINT"
      - run: pnpm wrangler deploy
      - name: Check EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --check \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"

Actualice EMDASH_TARGET_FINGERPRINT solo después de revisar un objetivo cambiado localmente. La huella digital no contiene credenciales, pero cambiarla sin verificar la cuenta y la base de datos elimina la protección contra migrar la base de datos incorrecta.

Hyperdrive se conecta al origen

El ejecutor de migraciones de Hyperdrive abre una conexión PostgreSQL directa al origen. No envía tráfico de migración a través de Hyperdrive, no usa el binding cacheado opcional ni hereda la accesibilidad de red privada del Worker.

El runner de despliegue debe poder alcanzar el origen. Configure migrationConnectionStringEnv en hyperdrive() cuando la variable específica del binding predeterminada sea inadecuada, y proporcione esa variable solo al trabajo de migración. Mantenga separadas las credenciales de Hyperdrive en tiempo de ejecución y las credenciales de despliegue direct-origin.

Adoptar la aplicación en tiempo de ejecución gradualmente

La siguiente configuración de integración de EmDash habilita la aplicación en tiempo de ejecución mientras conserva las migraciones automáticas en desarrollo.

emdash({
	database,
	migrations: {
		runtime: "check",
		dev: "auto",
	},
});

auto es el valor predeterminado compatible con versiones anteriores. El tiempo de ejecución al iniciar verifica y aplica migraciones pendientes.
check realiza una consulta de estado direccional y devuelve 503 antes de servir una solicitud cuando hay migraciones conocidas pendientes. Tolera registros de un build compatible más nuevo durante un despliegue continuo.
manual no realiza migración ni consulta de estado en tiempo de ejecución. Úselo solo después de que el pipeline de despliegue aplique y verifique cada build de manera confiable.

EMDASH_MIGRATIONS_MODE puede sobrescribir el modo en tiempo de ejecución cuando el mismo artefacto se promueve a través de múltiples entornos. Las rutas de bypass de configuración y desarrollo obedecen el modo efectivo; no pueden migrar silenciosamente detrás de check o manual.

Un despliegue conservador es auto mientras se introduce el trabajo de despliegue, luego check después de que el trabajo sea confiable, luego manual cuando se aplique una verificación externa para cada despliegue.

Compatibilidad durante despliegues continuos

Las migraciones del núcleo siguen la secuencia expand/deploy/contract. Un despliegue puede ejecutar temporalmente aislados de aplicación antiguos y nuevos contra la base de datos expandida, y un backfill puede estar aún en progreso. No contraiga un esquema hasta que cada versión desplegada haya dejado de usarlo.

Los registros de migración aplicados desconocidos son tolerados por el check en tiempo de ejecución solo para esta dirección de despliegue continuo. La verificación exacta de la CLI los reporta y apply rechaza la mutación, porque la base de datos puede ser más nueva o puede tener un historial de migración divergente.

Resolución de problemas

No se encontró manifiesto de migración. Construya o sincronice el proyecto primero. Use --manifest para una ubicación de artefacto no estándar o elija explícitamente --from-config para investigación local.
El artefacto no coincide con el EmDash del proyecto. Reconstruya y despliegue la aplicación y el manifiesto juntos. Ejecute la CLI del proyecto en lugar de una instalación global.
El objetivo falta o es ambiguo. Provisiónelo primero, luego proporcione una ruta de base de datos explícita, nombre de variable de conexión, selector D1 o configuración y entorno de Wrangler seleccionados. EmDash no adivina a partir de variables de entorno o bindings no relacionados.
La huella digital del objetivo cambió. Deténgase y revise la cuenta, el entorno, el nombre de la base de datos, UUID o ruta mostrados. Actualice la huella digital esperada solo después de confirmar el objetivo previsto.
Hay registros de migración desconocidos presentes. No elimine los registros ni vuelva a ejecutar apply. Confirme que el artefacto de la aplicación es la versión prevista e investigue si un build más nuevo o divergente migró la base de datos.
Un resultado de escritura D1 es ambiguo. No repita el comando de migración. Ejecute emdash migrate --status contra la misma cuenta y UUID de base de datos, inspeccione el resultado y escale si la migración se detuvo a mitad de camino.
Hyperdrive no puede conectar. Pruebe la accesibilidad desde el runner de despliegue al origen PostgreSQL y verifique la variable direct-origin. La conectividad Worker-a-Hyperdrive no prueba que el runner pueda alcanzar el origen.