Ir al contenido

Schema y migraciones

Tu configuración no crea tablas por sí sola. Kevin CMS la convierte en un schema de Drizzle y en ficheros SQL que revisas antes de aplicar. Nada toca la base de datos sin que tú lo pidas.

cms.config.ts
│ cms db:generate
├──▶ .cms/schema.ts schema de Drizzle (generado, no se commitea)
└──▶ .cms/types.d.ts tipos + App.Locals (generado, no se commitea)
│
│ cms db:migrate
▼
migrations/<fecha>_<nombre>/migration.sql (se commitea) ▲
migrations/<fecha>_<nombre>/snapshot.json (se commitea) │ db:pop
│ │ lo deshace
│ cms db:apply
▼
D1

Commitea migrations/. Añade .cms/ al .gitignore: se regenera siempre, y commitear artefactos generados solo produce conflictos de merge.

Esa cadena la recorren las colecciones. Un global se queda a mitad: vive en Cloudflare KV, así que no genera tabla ni migración —añadir uno, cambiarle un campo o quitarlo no produce una línea de SQL, y db:generate --check ni lo mira— pero sí entra en .cms/types.d.ts, con su interfaz y su entrada en Astro.locals.cms.globals.

Un CMS que altera su propio schema durante un request es imposible de revisar y de revertir. Generando antes de desplegar consigues tres cosas: las migraciones son ficheros SQL que se leen en una pull request, se pueden revertir, y el runtime nunca toca el schema, así que ningún request puede romper la base de datos.

  1. Cambia tu cms.config.ts — añade un campo, marca uno como unique, lo que sea.

  2. Genera la migración:

    Ventana de terminal
    pnpm cms db:migrate

    Esto regenera .cms/ y después llama a drizzle-kit generate, que escribe el SQL.

  3. Lee el SQL que ha salido. Es el paso que no conviene saltarse:

    Ventana de terminal
    cat migrations/*/migration.sql

    Si no te convence, tíralo y vuelve al paso 1:

    Ventana de terminal
    pnpm cms db:pop
  4. Aplícalo en local y compruébalo:

    Ventana de terminal
    pnpm cms db:apply
  5. Cuando estés conforme, en producción:

    Ventana de terminal
    pnpm cms db:apply --remote

Ninguno de esos comandos hace el trabajo del siguiente. db:migrate no aplica, db:apply no genera. Es a propósito: el paso 3, leer el SQL antes de que toque una base de datos, sólo existe si nada lo salta por ti.

Hacen falta dos ficheros, una vez.

drizzle.config.ts
import { defineConfig } from 'drizzle-kit'
export default defineConfig({
dialect: 'sqlite',
schema: './.cms/schema.ts',
out: './migrations',
})

Y en wrangler.jsonc, junto al binding de D1:

wrangler.jsonc
"d1_databases": [{
"binding": "DB",
"database_name": "mi-sitio",
"database_id": "<id>",
"migrations_dir": "migrations",
"migrations_pattern": "migrations/*/migration.sql"
}]

drizzle-kit lo instalas tú, en tu proyecto, y con la versión que el CMS declara como peer —sin fijarla te llevas la línea 0.31, que no la satisface:

Ventana de terminal
pnpm add -D drizzle-kit@1.0.0-rc.4

Un ejemplo real. Este config:

cms.config.ts
const posts = defineCollection({
slug: 'posts',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'slug', type: 'text', required: true, unique: true, index: true },
{ name: 'status', type: 'select', options: ['draft', 'published'], required: true },
{ name: 'author', type: 'relationship', to: 'users', onDelete: 'cascade' },
],
})

produce este schema:

.cms/schema.ts
export const posts = sqliteTable('posts', {
id: text('id').primaryKey(),
createdAt: integer('createdAt', { mode: 'timestamp_ms' }).notNull(),
updatedAt: integer('updatedAt', { mode: 'timestamp_ms' }).notNull(),
title: text('title'),
slug: text('slug'),
status: text('status'),
author: text('author').references(() => users.id, { onDelete: 'cascade' }),
}, (t) => [
uniqueIndex('uniq_posts_slug').on(t.slug),
index('idx_posts_author').on(t.author),
])

Tres cosas que aparecen sin que las pidas:

  • id, createdAt y updatedAt en toda colección.
  • Un índice en cada relación, la pidas o no. Filtrar por una relación es el patrón de acceso más común de un CMS, y sin índice cada una de esas consultas recorre la tabla entera.

Y una que no aparece, aunque la hayas pedido: ni title ni slug llevan NOT NULL, y status no lleva CHECK. Está explicado justo debajo.

La tabla completa de tipo de campo a columna está en Campos.

required: true y los options de un select no llegan a la tabla. Los hace cumplir la capa de datos en cada escritura —la API local, la REST, el panel, las subidas de ficheros y los globals—, con el mismo error de validación de siempre. La razón es que SQLite no puede añadir ni quitar un NOT NULL o un CHECK de una columna que ya existe: hay que recrear la tabla, y en D1 eso destruye filas ajenas si otra tabla apunta a ella. Sin las restricciones, alternar required o cambiar las opciones de un select no genera una línea de SQL, y añadir un campo required a una tabla con filas es un ALTER TABLE … ADD que no falla.

El precio: una escritura que se salte la capa de datos ya no tiene la red de la base de datos. Un INSERT a mano con wrangler d1 execute, o un script que escriba por SQL, puede dejar un title vacío o un status fuera de la lista, y nadie lo rechaza. Valida en ese script, o escribe por la API local.

Conservan el NOT NULL los campos que pone el propio CMS: id, createdAt, updatedAt, el email de users, los de un fichero (filename, mimeType, filesize) y las tablas de la autenticación.

Elemento Regla Ejemplo
Tabla El slug de la colección, tal cual posts
Columna El nombre del campo, tal cual publishedAt
Columna de un group <grupo>_<campo>, con los grupos anidados concatenados seo_metaTitle, seo_og_title
Columnas de un point <campo>_lng y <campo>_lat location_lng, location_lat
Tabla hija de un array <colección>_<campo> posts_links
Tabla hija de un tipo de blocks <colección>_<campo>_<slug> posts_sections_hero
Índice idx_<tabla>_<columna> idx_posts_author, idx_posts_sections_hero_image
Único uniq_<tabla>_<columna> uniq_posts_slug

Sin conversión a snake_case: el nombre que escribes en el config es el que aparece en la base de datos. Una traducción implícita solo obliga a recordar dos nombres para lo mismo. La única traducción es la del guion, que una tabla hija no admite en el nombre: la colección blog-posts con un array links da la tabla blog_posts_links, y un bloque con slug: 'hero-banner', posts_sections_hero_banner.

Una lista no es una columna: cada fila es una fila de una tabla hija, y la tabla del documento no cambia. Este config:

cms.config.ts
const posts = defineCollection({
slug: 'posts',
fields: [
{ name: 'title', type: 'text' },
{
name: 'links',
type: 'array',
fields: [
{ name: 'label', type: 'text', required: true },
{ name: 'url', type: 'text', required: true },
],
},
{
name: 'sections',
type: 'blocks',
blocks: [
{ slug: 'hero', fields: [{ name: 'title', type: 'text' }, { name: 'image', type: 'upload', to: 'ssd' }] },
{ slug: 'quote', fields: [{ name: 'text', type: 'textarea' }] },
],
},
],
})

añade a .cms/schema.ts tres tablas, posts_links, posts_sections_hero y posts_sections_quote, y cms db:migrate las crea con CREATE TABLE y nada más:

migrations/…/migration.sql
CREATE TABLE `posts_sections_hero` (
`parent` text NOT NULL,
`id` text NOT NULL,
`_order` integer NOT NULL,
`title` text,
`image` text,
CONSTRAINT `posts_sections_hero_pk` PRIMARY KEY(`parent`, `id`),
CONSTRAINT `fk_posts_sections_hero_image_ssd_id_fk` FOREIGN KEY (`image`) REFERENCES `ssd`(`id`) ON DELETE SET NULL
);
--> statement-breakpoint
CREATE INDEX `idx_posts_sections_hero_image` ON `posts_sections_hero` (`image`);

(Las otras dos tienen la misma forma, con sus subcampos y sin clave ni índice de upload.) Lo que conviene saber:

  • parent, id y _order van primero y son lo único NOT NULL. parent es el id del documento, id el de la fila y _order su posición en la lista, desde 0. Un subcampo required no lleva NOT NULL, como en una colección, y por lo mismo un select no lleva CHECK.
  • La clave primaria es (parent, id), no id. Un cliente no puede colisionar con las filas de otro documento ni quedárselas, la escritura puede reemplazar el conjunto sin leer antes, y la clave cubre el índice que hace falta para leer las filas de un documento. Por eso no hay ningún índice por parent.
  • No hay clave foránea de parent al documento, a propósito. Con ella, toda colección con una lista quedaría bloqueada por la guarda de recreación cada vez que drizzle-kit recreara la tabla del documento, y lo hace por cambios corrientes (el onDelete de una relación, el tipo de un campo). Sin ella, esa recreación pasa aunque haya listas, que es lo que se espera. El precio es que la base no borra las filas de un documento que desaparece: lo hace el CMS, en el mismo batch() del borrado (llega con la escritura de las filas), y un DELETE a mano contra D1 deja filas huérfanas. Acéptalo igual que aceptas que wrangler d1 execute salte la validación.
  • Un relationship o un upload dentro de una fila conserva su clave foránea y su índice, y su onDelete es el del campo: set null en un upload y, por defecto, en una relación; restrict si lo pides. cascade no existe en una fila (INVALID_ROW_OPTION), porque borrar el destino se llevaría filas de otros documentos sin tocar su updatedAt.
  • Una tabla por tipo de bloque y por campo, y ninguna tabla índice. El blockType de una fila es el final del nombre de su tabla, y _order es la posición dentro de todo el campo, así que leer las tablas de un blocks y ordenar por _order da la secuencia. Por eso tampoco hay columna _path.
  • Añadir una lista es aditivo. Solo aparecen CREATE TABLE (y los CREATE INDEX de los subcampos relación o upload): la tabla del documento, users, ssd y las tablas de la autenticación no se tocan.

Las filas se guardan y se leen ya (ver Cómo se guarda una lista y Leer listas). Las tablas se crean con la migración.

Un campo con hasMany: true usa la misma mecánica con una sola columna de datos. Este campo:

cms.config.ts
{ name: 'tags', type: 'select', hasMany: true, options: ['news', 'tech'] }

añade la tabla posts_tags, y cms db:migrate la crea con un CREATE TABLE y nada más:

migrations/…/migration.sql
CREATE TABLE `posts_tags` (
`parent` text NOT NULL,
`id` text NOT NULL,
`_order` integer NOT NULL,
`value` text,
CONSTRAINT `posts_tags_pk` PRIMARY KEY(`parent`, `id`)
);
  • Las reglas de una tabla hija valen tal cual: parent, id y _order van primero y son lo único NOT NULL, la clave es (parent, id), _order cuenta desde 0 y no hay clave foránea al documento. Borrar un documento borra sus valores en el mismo batch(); un DELETE a mano contra D1 los deja huérfanos.
  • value lleva el tipo del campo: text en un text y en un select, real en un number y integer con integer: true. Sin NOT NULL y, en un select, sin CHECK: la lista de opciones la impone la validación, así que cambiarla no genera migración.
  • El id de cada valor es su posición ('0', '1'…). Cada guardado reemplaza el conjunto entero y nada apunta a un valor suelto, así que no hace falta un UUID. Al leer, la API no lo expone.
  • No hay índice sobre value. Un where recorre los valores de los documentos candidatos.
  • En una colección con guion la tabla se llama con guion bajo, como la de una lista: blog-posts da blog_posts_tags. Y un campo no puede llamarse rels (RESERVED_FIELD_NAME): <colección>_rels es un nombre que el CMS se reserva.
  • Cuenta como una tabla hija más para el límite de sentencias: un hasMany es una T más, valgan 3 valores o 100.
  • Añadir, quitar y renombrar se comportan como con un array: añadir es un CREATE TABLE; quitar, un DROP TABLE que borra los valores; renombrar se para pidiendo una pista (rename de tabla, posts_tags a posts_topics; con create, los valores se pierden).

Un relationship o un upload con hasMany: true también es una tabla hija, pero con una columna por colección destino en vez de value. Este campo:

cms.config.ts
{ name: 'related', type: 'relationship', to: ['categories', 'pages'], hasMany: true }

añade la tabla posts_related, y cms db:migrate la crea con un CREATE TABLE y un CREATE INDEX por columna destino:

migrations/…/migration.sql
CREATE TABLE `posts_related` (
`parent` text NOT NULL,
`id` text NOT NULL,
`_order` integer NOT NULL,
`categoriesId` text,
`pagesId` text,
CONSTRAINT `posts_related_pk` PRIMARY KEY(`parent`, `id`),
CONSTRAINT `fk_posts_related_categoriesId_categories_id_fk`
FOREIGN KEY (`categoriesId`) REFERENCES `categories`(`id`) ON DELETE CASCADE,
CONSTRAINT `fk_posts_related_pagesId_pages_id_fk`
FOREIGN KEY (`pagesId`) REFERENCES `pages`(`id`) ON DELETE CASCADE
);
CREATE INDEX `idx_posts_related_categoriesId` ON `posts_related` (`categoriesId`);
CREATE INDEX `idx_posts_related_pagesId` ON `posts_related` (`pagesId`);
  • Una tabla por campo y una columna <destino>Id por colección. Un campo con un solo destino lleva una sola columna (categoriesId); el guion del slug es un guion bajo (my-notes da my_notesId). No hay una tabla posts_rels compartida: rels sigue reservado como nombre de campo (RESERVED_FIELD_NAME).
  • Cada fila rellena una sola columna. Lo comprueba la escritura, no un CHECK: las demás quedan en NULL. Al leer, una fila con todas las columnas a NULL se salta (es lo que deja quitar un destino).
  • Las columnas destino son claves foráneas, y el onDelete del campo decide qué hacen. Con setNull (el valor por defecto) la clave es ON DELETE CASCADE: al borrar el documento destino, el elemento desaparece de la lista y el hueco se queda en _order sin renumerar. Con restrict la clave es ON DELETE RESTRICT y el borrado se rechaza mientras algún documento lo tenga en su lista. cascade no existe aquí (INVALID_HAS_MANY): borrar el destino no puede borrar al documento padre, que no tiene clave foránea.
  • Índice por columna. Un where y el borrado del destino buscan por <destino>Id sin recorrer la tabla.
  • El resto de reglas son las de cualquier tabla hija: parent, id y _order primero, clave (parent, id), id es la posición, _order cuenta desde 0, sin clave foránea al documento, y cuenta como una T más para el límite de sentencias.

Cambiar el campo después se comporta así:

Cambio en el config SQL generado Tus datos
Añadir un hasMany de relaciones CREATE TABLE de la tabla hija y un CREATE INDEX por destino Intactos
Añadir un destino a to ALTER TABLE <tabla hija> ADD <destino>Id text REFERENCES … y su CREATE INDEX Intactos
Quitar un destino de to Recrea la tabla hija copiando las filas, sin esa columna. db:migrate pide confirmación Se pierden las referencias a ese destino; sus filas quedan con todas las columnas a NULL y no se leen
Cambiar el onDelete (setNull ↔ restrict) Recrea la tabla hija copiando las filas Intactos
Quitar el hasMany DROP INDEX de cada índice y DROP TABLE Se pierden los elementos
Cambiar de destino (categories a pages) Quitar una columna y añadir otra. Se para pidiendo --hints Se pierden las referencias
Convertir una relación suelta en hasMany, o al revés db:migrate no genera nada: es un moved, como en Convertir un campo en hasMany Se pierden si lo fuerzas a mano

Guardar un documento con listas es un solo batch() cuyo número de sentencias depende de las tablas hijas, no de las filas: 3T + 2 en un update y 2T + 2 en un delete, con T tablas hijas de la colección. El plan Free de D1 admite 50 consultas por invocación (el de pago, 1000), así que T = 17 ya pasa: 53 sentencias. cms db:generate lo avisa por colección. Si todavía no sabes si D1 cuenta cada sentencia de un batch() para ese tope —está sin medir en un Worker desplegado—, trátalo como si contara.

Cuando cambias el config sin generar la migración, db:generate te lo dice:

El schema ha cambiado desde la última migración:
~ posts.readingTime (integer → real)
+ posts.views (integer)
- posts.body
Ejecuta `cms db:migrate` para generar la migración.

+ es una columna nueva, - una que has quitado, ~ un cambio de tipo o un campo que cambia de columna a tabla hija (o al revés). Las columnas de las tablas hijas cuentan como las de cualquier tabla —+ posts_links.label (text)—, incluidas parent, id y _order.

Es un aviso, no un error: en desarrollo cambias el config todo el rato y bloquear el dev sería insoportable. En integración continua usa --check, que convierte ese aviso en un fallo:

Ventana de terminal
pnpm cms db:generate --check

La comparación se hace contra los snapshot.json que hay en migrations/, que están commiteados, así que funciona igual en tu máquina que en un clon recién hecho por CI.

No todos los cambios cuestan lo mismo. Estos son los casos, con el SQL que sale de verdad:

Cambio en el config SQL generado Tus datos
Añadir un campo, también required o select ALTER TABLE posts ADD subtitle text Intactos
Marcar o desmarcar required, cambiar las opciones de un select, min, maxLength, defaultValue Ninguno Intactos
Añadir o quitar unique o index CREATE / DROP INDEX Intactos
Quitar un campo ALTER TABLE posts DROP COLUMN subtitle Se pierde esa columna
Cambiar el tipo de un campo, el onDelete de una relación, o quitar una relación o un upload Recrea la tabla con INSERT … SELECT Se conservan las filas
Renombrar un campo Se para pidiendo --hints; con la pista, ALTER TABLE … RENAME COLUMN Intactos
Añadir un group o un point Un ALTER TABLE … ADD por subcampo (dos por point) Intactos
Añadir un array o un blocks, o un tipo de bloque CREATE TABLE de cada tabla hija, y CREATE INDEX de sus relaciones y upload Intactos
Añadir un subcampo a una lista ALTER TABLE <tabla hija> ADD Intactos
Quitar un array, un blocks o un tipo de bloque DROP TABLE de la tabla hija Se pierden sus filas
Renombrar un array o el slug de un bloque Se para pidiendo --hints; con la pista rename de tabla, ALTER TABLE … RENAME TO Intactos; con «create», se pierden
Convertir un campo en un subcampo de un group Se para pidiendo --hints; ver Convertir un campo en un group Se pierden si respondes «creada»
Añadir un campo con hasMany CREATE TABLE de su tabla hija Intactos
Quitar un campo con hasMany DROP TABLE de su tabla hija Se pierden sus valores
Añadir o quitar un destino de un hasMany de relaciones, o cambiar su onDelete Un ALTER TABLE … ADD (añadir) o recrear la tabla hija (quitar, onDelete): ver tablas hijas de un hasMany de relaciones Quitar un destino pierde sus referencias
Convertir un campo en hasMany, o un hasMany en un campo normal db:migrate no genera nada: ver Convertir un campo en hasMany Se pierden si lo fuerzas a mano

db:migrate te pide confirmación en los dos casos destructivos —quitar y cambiar tipo— antes de generar nada. Quitar una lista cuenta: sus columnas salen como quitadas, y el DROP TABLE borra las filas.

Actualizar un proyecto que ya tiene migraciones

Sección titulada «Actualizar un proyecto que ya tiene migraciones»

Una base creada con la 0.9 o una anterior tiene un NOT NULL por cada required y un CHECK por cada select. Esta versión no emite ni uno ni otro, y el aviso de deriva compara nombres y tipos de columna, no restricciones: no te avisa. Tu base conserva las viejas hasta que migres, y mientras tanto cualquier cambio que toques arrastrará la recreación consigo. Hazlo una vez, nada más actualizar y antes de tocar el config, para que la migración solo contenga esto:

Ventana de terminal
pnpm cms db:migrate

Lee el SQL que deja en migrations/. Hay dos desenlaces:

  • Recrea solo tablas a las que no apunta ninguna relación —posts en la demo—. db:migrate la genera, cambia el PRAGMA por uno que D1 sí aplica, y la aplicas como cualquier otra. Las filas se copian enteras. Compara los recuentos antes y después en local.
  • Recrea una tabla a la que sí apunta una relación, que pasa si declaras campos required o select propios en users. db:migrate se planta y borra la migración. El camino es la receta de abajo.

Las tablas del CMS (users con sus campos de siempre, ssd, session, account, verification y rateLimit) no cambian ni un byte: nunca entran en esa recreación.

Recrear es CREATE TABLE __new_x, INSERT … SELECT, DROP TABLE x y RENAME. Ese DROP destruye datos en D1 cuando alguna clave foránea apunta a x: D1 acepta el PRAGMA foreign_keys=OFF que drizzle-kit pone delante y lo ignora, así que el borrado implícito del DROP dispara los ON DELETE de las hijas y se lleva sus filas, en verde y sin que wrangler avise. Está en Limitaciones.

Por eso db:migrate se planta ahí, borra la migración que acababa de generar y sale con error:

Migración bloqueada y borrada: recrea tablas a las que apuntan claves foráneas, y en D1 eso destruye
filas de otras tablas.
users, apuntada desde:
- account (ON DELETE CASCADE)
- session (ON DELETE CASCADE)
- posts (ON DELETE SET NULL)

La migración la escribes tú, en cuatro pasos. Lo que tienes que saber de cada hija depende de su ON DELETE: es lo que el DROP le hace y, por tanto, lo que hay que guardar y devolver.

ON DELETE Qué le hace el DROP Qué respaldar Cómo se devuelve
CASCADE Borra sus filas, y las de sus propias hijas en cascada Las filas enteras, siguiendo la cadena hasta el final INSERT … SELECT, la madre antes que la hija
SET NULL Anula la columna El id y esa columna UPDATE … FROM
RESTRICT Impide el DROP mientras apunte alguien El id y esa columna, y se anula antes del DROP UPDATE … FROM
  1. Genera el SQL y el snapshot. db:migrate borró los dos, y el snapshot es lo que le dice a db:migrate que la base ya está al día. Llama a drizzle-kit directamente, una vez:

    Ventana de terminal
    pnpm drizzle-kit generate --name users_sin_restricciones < /dev/null

    Escribe migrations/<fecha>_users_sin_restricciones/ con un snapshot.json correcto y un migration.sql que no se puede aplicar tal cual: es la recreación sin respaldo.

    El < /dev/null (en Windows, < NUL) no es adorno: es lo que hace cms db:migrate por ti. En una terminal, si además de lo de arriba quitaste o añadiste una columna, drizzle-kit pregunta «¿creada o renombrada?» con «creada» marcada, y esa respuesta borra la columna vieja con sus datos. Sin terminal se para con código 2 y te pide --hints, que añades igual que en Renombrar una columna.

  2. Reescribe migration.sql conservando lo que escribió drizzle-kit. Solo cambia el pragma (foreign_keys por defer_foreign_keys, y fuera el que lo vuelve a encender) y añades el respaldo delante y la restauración detrás. Para el caso de arriba, con comments colgando de posts y dos hijas más, notes a NULL y reviews a RESTRICT:

    migrations/20261101120000_users_sin_restricciones/migration.sql
    PRAGMA defer_foreign_keys=true;
    -- 1. Respaldo de lo que el DROP se va a llevar. Tablas normales, porque D1 no admite TEMP.
    -- CASCADE: las filas enteras, y las de las hijas de las hijas.
    CREATE TABLE `bk_account` AS SELECT `id`, `userId`, `providerId` FROM `account`;
    CREATE TABLE `bk_posts` AS SELECT `id`, `title`, `author` FROM `posts` WHERE `author` IS NOT NULL;
    CREATE TABLE `bk_comments` AS SELECT `id`, `body`, `post` FROM `comments`
    WHERE `post` IN (SELECT `id` FROM `bk_posts`);
    -- SET NULL y RESTRICT: solo el id y la columna, con el id como clave primaria
    CREATE TABLE `bk_notes_owner` (`id` text PRIMARY KEY, `owner` text);
    INSERT INTO `bk_notes_owner` SELECT `id`, `owner` FROM `notes` WHERE `owner` IS NOT NULL;
    CREATE TABLE `bk_reviews_reviewer` (`id` text PRIMARY KEY, `reviewer` text);
    INSERT INTO `bk_reviews_reviewer` SELECT `id`, `reviewer` FROM `reviews` WHERE `reviewer` IS NOT NULL;
    -- RESTRICT no deja borrar mientras alguien apunte: se anula ahora y se restaura después
    UPDATE `reviews` SET `reviewer` = NULL WHERE `reviewer` IS NOT NULL;
    -- 2. La recreación, tal como la escribió drizzle-kit
    CREATE TABLE `__new_users` (
    `id` text PRIMARY KEY,
    `createdAt` integer NOT NULL,
    `email` text NOT NULL,
    `plan` text
    );
    INSERT INTO `__new_users`(`id`, `createdAt`, `email`, `plan`) SELECT `id`, `createdAt`, `email`, `plan` FROM `users`;
    DROP TABLE `users`;
    ALTER TABLE `__new_users` RENAME TO `users`;
    CREATE UNIQUE INDEX `uniq_users_email` ON `users` (`email`);
    -- 3. Restauración, las madres antes que las hijas
    INSERT INTO `account`(`id`, `userId`, `providerId`) SELECT `id`, `userId`, `providerId` FROM `bk_account`;
    INSERT INTO `posts`(`id`, `title`, `author`) SELECT `id`, `title`, `author` FROM `bk_posts`;
    INSERT INTO `comments`(`id`, `body`, `post`) SELECT `id`, `body`, `post` FROM `bk_comments`;
    UPDATE `notes` SET `owner` = `b`.`owner` FROM `bk_notes_owner` AS `b` WHERE `notes`.`id` = `b`.`id`;
    UPDATE `reviews` SET `reviewer` = `b`.`reviewer` FROM `bk_reviews_reviewer` AS `b` WHERE `reviews`.`id` = `b`.`id`;
    -- 4. Limpieza
    DROP TABLE `bk_account`;
    DROP TABLE `bk_posts`;
    DROP TABLE `bk_comments`;
    DROP TABLE `bk_notes_owner`;
    DROP TABLE `bk_reviews_reviewer`;
  3. Pruébala en local con datos, no con la base vacía, y compara antes y después:

    Ventana de terminal
    pnpm cms db:apply

    Cuenta las filas de cada tabla de arriba, y de las que cuelgan de ellas, antes y después. Una restauración que se olvida de una hija no da error: da una tabla vacía.

  4. Comprueba que el snapshot encaja. Con la migración puesta, db:migrate tiene que decir que no hay nada que migrar:

    Ventana de terminal
    pnpm cms db:migrate

Tres detalles que importan:

  • Las columnas, una por una, en el INSERT. SELECT * funciona mientras la hija no cambie en esta misma migración, y falla sin avisar cuando cambia.
  • El UPDATE … FROM y no una subconsulta por fila. UPDATE t SET c = (SELECT … WHERE b.id = t.id) recorre el respaldo entero por cada fila: con 50 000 filas tardó 41 s, por encima de los 30 s que D1 concede a una consulta. Con la clave primaria del respaldo, el UPDATE … FROM es una búsqueda por fila.
  • Una tabla grande se parte. Si una tabla pasa de los límites de D1, no hay receta que la salve en una sola migración: copia por trozos fuera de la migración, o aplica en una ventana de mantenimiento.

Kevin CMS no intenta adivinar renombrados, y drizzle-kit tampoco: si quitas excerpt y añades summary, no puede saber si querías renombrar o si querías borrar una columna y crear otra. En una terminal drizzle-kit lo pregunta —«¿summary es una columna creada o renombrada?»— y la respuesta que deja marcada de antemano es «creada», que borra excerpt con todos sus datos.

Por eso cms db:migrate no le presta la terminal: lanza drizzle-kit sin entrada, y esa pregunta no llega a salir. En su lugar, se planta:

missing_hints: 1 unresolved decisions
1. Rename or create — column public.posts.summary
Add to --hints:
{ "type": "rename", "kind": "column", "from": ["<schema>", "<table>", "<old_name>"], "to": ["public", "posts", "summary"] }
OR
{ "type": "create", "kind": "column", "entity": ["public", "posts", "summary"] }

db:migrate sale con código 2 y no genera ninguna migración. La respuesta la das tú, con --hints, un array JSON con una pista por cada decisión de ese bloque. El esquema de SQLite se llama public, y <old_name> es el nombre que tenía la columna:

Ventana de terminal
pnpm cms db:migrate --hints '[{"type":"rename","kind":"column","from":["public","posts","excerpt"],"to":["public","posts","summary"]}]'
migrations/…/migration.sql
ALTER TABLE `posts` RENAME COLUMN `excerpt` TO `summary`;

Los datos se conservan. Para renombrar una colección entera es la misma pista con "kind": "table" y dos nombres en cada lado: "from": ["public", "posts"], "to": ["public", "articles"].

Si de verdad es una columna nueva y la vieja sobra, la pista es { "type": "create", … }. Añade summary y borra excerpt con sus datos: es lo que haría la respuesta marcada por defecto en la terminal, y por eso hay que pedirlo a propósito.

Renombrar links a menu cambia el nombre de su tabla hija, de posts_links a posts_menu, y para el esquema es quitar una tabla y crear otra: igual que con una columna, cms db:migrate se para pidiendo una pista (missing_hints) y no genera nada. Con la pista rename de tabla (los nombres, con el esquema public delante), los datos se quedan:

Ventana de terminal
pnpm cms db:migrate --hints '[{"type":"rename","kind":"table","from":["public","posts_links"],"to":["public","posts_menu"]}]'
migrations/…/migration.sql
ALTER TABLE `posts_links` RENAME TO `posts_menu`;

Si algún subcampo es una relación o un upload, la migración suma el cambio de nombre de su índice, que lleva el de la tabla (DROP INDEX y CREATE INDEX); la tabla no se recrea. Con la pista create, en cambio, son un DROP TABLE y un CREATE TABLE: las filas se pierden. Lo mismo vale para renombrar el slug de un tipo de bloque (posts_sections_hero a posts_sections_banner), y para renombrar la colección entera, que renombra además todas sus tablas hijas: una pista por tabla.

Añadir un group o un point a una colección con datos es aditivo: cada subcampo es una columna nueva, un ALTER TABLE … ADD y nada más. Convertir un campo que ya existe en un subcampo no lo es. metaTitle pasa a ser seo.metaTitle, o sea la columna seo_metaTitle, y para el esquema eso es quitar una columna y añadir otra: drizzle-kit se para a preguntar si es un renombrado, y la respuesta «creada» borra la columna vieja con sus datos. Kevin CMS no copia ni mueve datos por ti. Hay dos caminos.

Si el tipo no cambia, renombra la columna. Una sola migración, los datos se quedan donde están:

Ventana de terminal
pnpm cms db:migrate --hints '[{"type":"rename","kind":"column","from":["public","posts","metaTitle"],"to":["public","posts","seo_metaTitle"]}]'
migrations/…/migration.sql
ALTER TABLE `posts` RENAME COLUMN `metaTitle` TO `seo_metaTitle`;

Si el campo es unique o index, o es una relationship o un upload, la migración suma el cambio de nombre del índice, porque lleva el de la columna. La tabla sigue sin recrearse, y la clave foránea viaja con la columna renombrada:

migrations/…/migration.sql
ALTER TABLE `posts` RENAME COLUMN `slug` TO `seo_slug`;
DROP INDEX IF EXISTS `uniq_posts_slug`;
CREATE UNIQUE INDEX `uniq_posts_seo_slug` ON `posts` (`seo_slug`);

Si mueves varios campos a la vez, una pista por cada columna en el mismo array. Si además cambia el tipo —un number que pasa a text, un text que pasa a date—, el renombrado trae consigo la recreación de la tabla (CREATE TABLE __new_posts más un INSERT … SELECT): los datos se conservan, pero es el caso caro, y si otra tabla apunta a posts db:migrate ni la genera. Para ese caso, la copia de abajo.

Si el tipo cambia, o quieres transformar el valor por el camino, copia en tres pasos y no quites nada hasta tener la copia hecha:

  1. Añade el group y deja el campo viejo. Las dos columnas conviven —metaTitle y seo_metaTitle— y la migración es solo ALTER TABLE posts ADD seo_metaTitle text.

  2. Copia los datos con SQL, en local y en remoto:

    Ventana de terminal
    npx wrangler d1 execute DB --local --command "UPDATE posts SET seo_metaTitle = metaTitle"
    npx wrangler d1 execute DB --remote --command "UPDATE posts SET seo_metaTitle = metaTitle"
  3. Quita el campo viejo cuando tu código ya lee seo.metaTitle. Es una migración con un solo ALTER TABLE posts DROP COLUMN metaTitle, y db:migrate te pide confirmación antes de generarla porque pierde esa columna.

Hacerlo en un solo paso, sin renombrar, es lo que borra los datos: quitar metaTitle y añadir el group en la misma migración genera DROP COLUMN y ADD, y la columna nueva sale vacía.

Pasar keywords: { type: 'text' } a keywords: { type: 'text', hasMany: true } no es aditivo: el campo deja de ser una columna de posts y pasa a ser una tabla hija. Para el esquema es quitar una columna y crear una tabla, y ninguna migración copia lo que había en la columna. Por eso cms db:generate lo avisa como una sola línea,

El schema ha cambiado desde la última migración:
~ posts.keywords pasa de columna a tabla hija (posts_keywords): sus valores no se copian

y cms db:migrate no genera la migración: sale con error y apunta a esta receta, antes de preguntar nada. El camino inverso (un hasMany que pasa a campo normal) pierde igual los valores, y se rechaza del mismo modo. Se hace en dos migraciones y una copia en medio, y no se quita nada hasta tener la copia hecha:

  1. Añade el campo nuevo con otro nombre y deja el viejo. keywordList: { type: 'text', hasMany: true } junto a keywords. La migración es solo CREATE TABLE posts_keywordList.

  2. Copia los datos con SQL, en local y en remoto. Una columna con un valor pasa a una lista de uno:

    INSERT INTO posts_keywordList (parent, id, _order, value)
    SELECT id, '0', 0, keywords FROM posts WHERE keywords IS NOT NULL AND keywords <> '';

    Y una columna json que guardaba un array (["a","b"]) pasa a una fila por elemento, con el índice como posición:

    INSERT INTO posts_keywordList (parent, id, _order, value)
    SELECT p.id, CAST(j.key AS TEXT), j.key, j.value FROM posts p, json_each(p.keywords) AS j;
    Ventana de terminal
    npx wrangler d1 execute DB --local --file copiar-keywords.sql
    npx wrangler d1 execute DB --remote --file copiar-keywords.sql
  3. Quita el campo viejo cuando tu código ya lee keywordList. Es una migración con un solo ALTER TABLE posts DROP COLUMN keywords, y db:migrate te pide confirmación antes de generarla porque pierde esa columna.

Si prefieres quedarte con el nombre original, una tercera migración con la pista rename de tabla (posts_keywordList a posts_keywords) lo devuelve, cuando la columna vieja ya no existe. Hacerlo en un solo paso —el mismo nombre, sin campo intermedio— es lo que borra los datos.

La integración de Astro llama a generate al arrancar y vigila tu cms.config.ts, así que editarlo regenera los tipos sin salir del dev.

Lo que no hace nunca es generar ni aplicar migraciones. Eso siempre lo pides tú.