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.
La cadena completa
Sección titulada «La cadena completa»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 ▼ D1Commitea 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.
Por qué en build y no en caliente
Sección titulada «Por qué en build y no en caliente»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.
El ciclo
Sección titulada «El ciclo»-
Cambia tu
cms.config.ts— añade un campo, marca uno comounique, lo que sea. -
Genera la migración:
Ventana de terminal pnpm cms db:migrateEsto regenera
.cms/y después llama adrizzle-kit generate, que escribe el SQL. -
Lee el SQL que ha salido. Es el paso que no conviene saltarse:
Ventana de terminal cat migrations/*/migration.sqlSi no te convence, tíralo y vuelve al paso 1:
Ventana de terminal pnpm cms db:pop -
Aplícalo en local y compruébalo:
Ventana de terminal pnpm cms db:apply -
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.
Configuración
Sección titulada «Configuración»Hacen falta dos ficheros, una vez.
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:
"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:
pnpm add -D drizzle-kit@1.0.0-rc.4Qué genera cada campo
Sección titulada «Qué genera cada campo»Un ejemplo real. Este config:
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:
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,createdAtyupdatedAten 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.
Sin NOT NULL ni CHECK
Sección titulada «Sin NOT NULL ni CHECK»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.
Nombres
Sección titulada «Nombres»| 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.
Tablas hijas: array y blocks
Sección titulada «Tablas hijas: array y blocks»Una lista no es una columna: cada fila es una fila de una tabla hija, y la tabla del documento no cambia. Este config:
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:
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-breakpointCREATE 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,idy_ordervan primero y son lo únicoNOT NULL.parentes eliddel documento,idel de la fila y_ordersu posición en la lista, desde 0. Un subcamporequiredno llevaNOT NULL, como en una colección, y por lo mismo unselectno llevaCHECK.- La clave primaria es
(parent, id), noid. 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 porparent. - No hay clave foránea de
parental 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 (elonDeletede 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 mismobatch()del borrado (llega con la escritura de las filas), y unDELETEa mano contra D1 deja filas huérfanas. Acéptalo igual que aceptas quewrangler d1 executesalte la validación. - Un
relationshipo unuploaddentro de una fila conserva su clave foránea y su índice, y suonDeletees el del campo:set nullen unuploady, por defecto, en una relación;restrictsi lo pides.cascadeno existe en una fila (INVALID_ROW_OPTION), porque borrar el destino se llevaría filas de otros documentos sin tocar suupdatedAt. - Una tabla por tipo de bloque y por campo, y ninguna tabla índice. El
blockTypede una fila es el final del nombre de su tabla, y_orderes la posición dentro de todo el campo, así que leer las tablas de unblocksy ordenar por_orderda la secuencia. Por eso tampoco hay columna_path. - Añadir una lista es aditivo. Solo aparecen
CREATE TABLE(y losCREATE INDEXde los subcampos relación oupload): la tabla del documento,users,ssdy 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.
Tablas hijas de un hasMany
Sección titulada «Tablas hijas de un hasMany»Un campo con hasMany: true usa la misma mecánica con una sola
columna de datos. Este campo:
{ 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:
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,idy_ordervan primero y son lo únicoNOT NULL, la clave es(parent, id),_ordercuenta desde 0 y no hay clave foránea al documento. Borrar un documento borra sus valores en el mismobatch(); unDELETEa mano contra D1 los deja huérfanos. valuelleva el tipo del campo:texten untexty en unselect,realen unnumberyintegerconinteger: true. SinNOT NULLy, en unselect, sinCHECK: la lista de opciones la impone la validación, así que cambiarla no genera migración.- El
idde 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. Unwhererecorre 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-postsdablog_posts_tags. Y un campo no puede llamarserels(RESERVED_FIELD_NAME):<colección>_relses un nombre que el CMS se reserva. - Cuenta como una tabla hija más para el límite de sentencias: un
hasManyes unaTmás, valgan 3 valores o 100. - Añadir, quitar y renombrar se comportan como con un
array: añadir es unCREATE TABLE; quitar, unDROP TABLEque borra los valores; renombrar se para pidiendo una pista (renamede tabla,posts_tagsaposts_topics; concreate, los valores se pierden).
Tablas hijas de un hasMany de relaciones
Sección titulada «Tablas hijas de un hasMany de relaciones»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:
{ 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:
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>Idpor colección. Un campo con un solo destino lleva una sola columna (categoriesId); el guion del slug es un guion bajo (my-notesdamy_notesId). No hay una tablaposts_relscompartida:relssigue 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 enNULL. Al leer, una fila con todas las columnas aNULLse salta (es lo que deja quitar un destino). - Las columnas destino son claves foráneas, y el
onDeletedel campo decide qué hacen. ConsetNull(el valor por defecto) la clave esON DELETE CASCADE: al borrar el documento destino, el elemento desaparece de la lista y el hueco se queda en_ordersin renumerar. Conrestrictla clave esON DELETE RESTRICTy el borrado se rechaza mientras algún documento lo tenga en su lista.cascadeno existe aquí (INVALID_HAS_MANY): borrar el destino no puede borrar al documento padre, que no tiene clave foránea. - Índice por columna. Un
wherey el borrado del destino buscan por<destino>Idsin recorrer la tabla. - El resto de reglas son las de cualquier tabla hija:
parent,idy_orderprimero, clave(parent, id),ides la posición,_ordercuenta desde 0, sin clave foránea al documento, y cuenta como unaTmá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 |
El límite de sentencias por guardado
Sección titulada «El límite de sentencias por guardado»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.
Aviso de deriva
Sección titulada «Aviso de deriva»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.bodyEjecuta `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:
pnpm cms db:generate --checkLa 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.
Qué genera cada cambio
Sección titulada «Qué genera cada cambio»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:
pnpm cms db:migrateLee el SQL que deja en migrations/. Hay dos desenlaces:
- Recrea solo tablas a las que no apunta ninguna relación —
postsen la demo—.db:migratela genera, cambia elPRAGMApor 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
requiredoselectpropios enusers.db:migratese 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 una tabla a mano
Sección titulada «Recrear una tabla a mano»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 destruyefilas 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 |
-
Genera el SQL y el snapshot.
db:migrateborró los dos, y el snapshot es lo que le dice adb:migrateque 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/nullEscribe
migrations/<fecha>_users_sin_restricciones/con unsnapshot.jsoncorrecto y unmigration.sqlque no se puede aplicar tal cual: es la recreación sin respaldo.El
< /dev/null(en Windows,< NUL) no es adorno: es lo que hacecms db:migratepor 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. -
Reescribe
migration.sqlconservando lo que escribió drizzle-kit. Solo cambia el pragma (foreign_keyspordefer_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, concommentscolgando depostsy dos hijas más,notesa NULL yreviewsaRESTRICT: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 primariaCREATE 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ésUPDATE `reviews` SET `reviewer` = NULL WHERE `reviewer` IS NOT NULL;-- 2. La recreación, tal como la escribió drizzle-kitCREATE 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 hijasINSERT 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. LimpiezaDROP TABLE `bk_account`;DROP TABLE `bk_posts`;DROP TABLE `bk_comments`;DROP TABLE `bk_notes_owner`;DROP TABLE `bk_reviews_reviewer`; -
Pruébala en local con datos, no con la base vacía, y compara antes y después:
Ventana de terminal pnpm cms db:applyCuenta 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.
-
Comprueba que el snapshot encaja. Con la migración puesta,
db:migratetiene 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 … FROMy 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, elUPDATE … FROMes 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.
Renombrar una columna
Sección titulada «Renombrar una columna»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 decisions1. 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:
pnpm cms db:migrate --hints '[{"type":"rename","kind":"column","from":["public","posts","excerpt"],"to":["public","posts","summary"]}]'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 un array o un tipo de bloque
Sección titulada «Renombrar un array o un tipo de bloque»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:
pnpm cms db:migrate --hints '[{"type":"rename","kind":"table","from":["public","posts_links"],"to":["public","posts_menu"]}]'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.
Convertir un campo en un group
Sección titulada «Convertir un campo en un group»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:
pnpm cms db:migrate --hints '[{"type":"rename","kind":"column","from":["public","posts","metaTitle"],"to":["public","posts","seo_metaTitle"]}]'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:
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:
-
Añade el group y deja el campo viejo. Las dos columnas conviven —
metaTitleyseo_metaTitle— y la migración es soloALTER TABLE posts ADD seo_metaTitle text. -
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" -
Quita el campo viejo cuando tu código ya lee
seo.metaTitle. Es una migración con un soloALTER TABLE posts DROP COLUMN metaTitle, ydb:migratete 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.
Convertir un campo en hasMany
Sección titulada «Convertir un campo en hasMany»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 copiany 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:
-
Añade el campo nuevo con otro nombre y deja el viejo.
keywordList: { type: 'text', hasMany: true }junto akeywords. La migración es soloCREATE TABLE posts_keywordList. -
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
jsonque 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.sqlnpx wrangler d1 execute DB --remote --file copiar-keywords.sql -
Quita el campo viejo cuando tu código ya lee
keywordList. Es una migración con un soloALTER TABLE posts DROP COLUMN keywords, ydb:migratete 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.
Durante el desarrollo
Sección titulada «Durante el desarrollo»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ú.