@darkj/create-db 1.0.0 → 1.1.1

package/templates/base/.claude/commands/new-migration.md

@@ -1,60 +1,61 @@
-Creá una nueva migración para este proyecto siguiendo el formato de carpetas.
+Create a new migration for this project following the folder format.
 
-## Paso 1 — Determinar el número siguiente
+## Step 1 — Determine the next number
 
-Listá las carpetas en `migrations/` en orden alfabético.
-El próximo número es el último + 1, con ceros a la izquierda (ej: si existe `004_...`, el siguiente es `005`).
+List the folders in `migrations/` in alphabetical order.
+The next number is the last one + 1, zero-padded (e.g. if `004_...` exists, the next is `005`).
 
-## Paso 2 — Obtener información
+## Step 2 — Get information
 
-Si el usuario no la dio, preguntá:
-- ¿Qué cambio se quiere hacer?
-- ¿Hay contexto o razón detrás del cambio? (para decidir si crear README.md)
+If the user didn't provide it, ask:
+- What change do you want to make?
+- Is there context or a reason behind the change? (to decide whether to create a README.md)
 
-Si el usuario pasó un script SQL directamente, usarlo como base para `up.sql` — ordenarlo y limpiarlo si hace falta.
+If the user passed a SQL script directly, use it as the base for `up.sql` — order and clean it up if needed.
 
-## Paso 3 — Crear la carpeta
+## Step 3 — Create the folder
 
-Nombre: `NNN_YYYYMMDD_HHMM_proposito_breve`
-- Fecha y hora actuales
-- Propósito en snake_case, breve (3-5 palabras máximo)
+Name: `NNN_YYYYMMDD_HHMM_short_purpose`
+- Current date and time
+- Purpose in snake_case, short (3-5 words max)
 
 ```
-migrations/NNN_YYYYMMDD_HHMM_proposito_breve/
+migrations/NNN_YYYYMMDD_HHMM_short_purpose/
 ├── up.sql
 ├── down.sql
-└── README.md   ← solo si hay contexto claro
+└── README.md   ← only if there's clear context
 ```
 
-## Paso 4 — Escribir up.sql
+## Step 4 — Write up.sql
 
-Aplicar el checklist:
-- ¿Columna NOT NULL nueva? → necesita DEFAULT o backfill previo
-- ¿Eliminás columna con datos? → primero migrar datos, luego DROP
-- ¿FK nueva? → la tabla referenciada ya debe existir
-- ¿Índice en tabla grande? → sugerir CONCURRENTLY
+Apply the checklist:
+- New NOT NULL column? → needs a DEFAULT or a prior backfill
+- Dropping a column with data? → migrate the data first, then DROP
+- New FK? → the referenced table must already exist
+- Index on a large table? → suggest CONCURRENTLY
 
-## Paso 5 — Escribir down.sql
+## Step 5 — Write down.sql
 
-SQL inverso al up.sql. Debe dejar la DB en el estado anterior exactamente.
-Siempre escribirlo, aunque el usuario no lo haya pedido.
+SQL that reverses up.sql. It must leave the DB exactly in its previous state.
+Always write it, even if the user didn't ask for it.
 
-## Paso 6 — Crear README.md (solo si hay contexto)
+## Step 6 — Create README.md (only if there's context)
 
-Si la migración fue planeada o el usuario explicó la razón:
+If the migration was planned or the user explained the reason:
 ```markdown
-# proposito_breve
+# short_purpose
 
-{1-3 líneas del por qué, no del qué.}
+{1-3 lines about why, not what.}
 ```
 
-Si el usuario pasó el script sin contexto: no crear README.md.
+If the user passed the script with no context: don't create README.md.
 
-## Paso 7 — Actualizar schema/
+## Step 7 — Update schema/
 
-Identificá qué archivos `create.sql` en `schema/` quedan desactualizados y actualizalos para reflejar el nuevo estado de las tablas afectadas.
+Identify which `create.sql` files in `schema/` are now outdated and update them to reflect the
+new state of the affected tables.
 
-## Paso 8 — Mostrar el comando para aplicar
+## Step 8 — Show the command to apply it
 
 ```bash
 npm run migrate

package/templates/base/.claude/rules/migrations.md

@@ -3,109 +3,116 @@ paths:
   - "migrations/**"
 ---
 
-# Reglas para trabajar en migrations/
+# Rules for working in migrations/
 
-## Principio fundamental
+## Fundamental principle
 
-`migrations/` es **append-only** e **inmutable**. Solo se agregan carpetas nuevas al final.
-Nunca editar `up.sql` de una migración ya aplicada — si hay un error, crear una nueva migración que lo corrija.
+`migrations/` is **append-only** and **immutable**. Only new folders get added, at the end.
+Never edit the `up.sql` of an already-applied migration — if there's a mistake, create a new
+migration that fixes it.
 
-## Estructura de cada migración
+## Structure of each migration
 
-Cada migración es una **carpeta**, no un archivo suelto:
+Each migration is a **folder**, not a loose file:
 
 ```
 migrations/
-└── NNN_YYYYMMDD_HHMM_proposito_breve/
-    ├── up.sql      ← cambios a aplicar (obligatorio)
-    ├── down.sql    ← cómo revertirlos (obligatorio)
-    └── README.md   ← contexto y razón (solo si fue planeado o tiene contexto claro)
+└── NNN_YYYYMMDD_HHMM_short_purpose/
+    ├── up.sql      ← changes to apply (required)
+    ├── down.sql    ← how to revert them (required)
+    └── README.md   ← context and reason (only if it was planned or has clear context)
 ```
 
-## Naming de la carpeta
+## Folder naming
 
 ```
-NNN_YYYYMMDD_HHMM_proposito_breve
+NNN_YYYYMMDD_HHMM_short_purpose
 ```
 
-- `NNN` — número secuencial con ceros (`001`, `002`, `003`...)
-- `YYYYMMDD` — fecha de creación
-- `HHMM` — hora de creación
-- `proposito_breve` — descripción corta en `snake_case`
+- `NNN` — sequential number with leading zeros (`001`, `002`, `003`...)
+- `YYYYMMDD` — creation date
+- `HHMM` — creation time
+- `short_purpose` — short description in `snake_case`
 
-Ejemplos:
+Examples:
 - `003_20260524_1430_add_phone_to_users`
 - `004_20260525_0900_create_index_orders_status`
 - `005_20260526_1100_rename_column_amount_to_total`
 - `006_20260527_1600_drop_deprecated_sessions`
 
-## up.sql — los cambios
+## up.sql — the changes
 
-SQL que transforma la DB del estado anterior al nuevo. Es lo que `npm run migrate` ejecuta.
+SQL that transforms the DB from the previous state to the new one. This is what `npm run migrate` runs.
 
-## down.sql — el reverso
+## down.sql — the reverse
 
-SQL inverso al `up.sql`. Debe dejar la DB exactamente como estaba antes de aplicar esta migración.
-Siempre escribirlo aunque no se planee usarlo — es la documentación del efecto contrario.
+SQL that reverses `up.sql`. It must leave the DB exactly as it was before this migration was applied.
+Always write it even if it's not planned to be used — it documents the opposite effect.
 
-## README.md — contexto (opcional)
+## README.md — context (optional)
 
-Solo crearlo si la migración fue **planeada** o tiene **contexto conocido** (decisión de negocio, bug fix, refactor coordinado).
-Si el usuario pasa un script sin contexto, generar solo `up.sql` y `down.sql`, sin `README.md`.
+Only create it if the migration was **planned** or has **known context** (business decision, bug
+fix, coordinated refactor). If the user passes a script with no context, generate only `up.sql`
+and `down.sql`, without `README.md`.
 
-Formato del README.md:
+README.md format:
 ```markdown
-# proposito_breve
+# short_purpose
 
-{1-3 líneas explicando por qué se hace este cambio, no qué hace el SQL.}
+{1-3 lines explaining why this change is being made, not what the SQL does.}
 ```
 
-## Checklist antes de escribir up.sql
+## Checklist before writing up.sql
 
-1. ¿El cambio afecta datos existentes? → incluir `UPDATE`/backfill antes del `ALTER`
-2. ¿Se agrega columna `NOT NULL`? → necesita `DEFAULT` o backfill previo
-3. ¿Se elimina columna con datos? → primero migrar los datos, luego `DROP`
-4. ¿Hay FK nueva? → la tabla referenciada ya debe existir
-5. ¿Se crea índice en tabla grande? → considerar `CREATE INDEX CONCURRENTLY`
-6. ¿El SQL es idempotente donde sea posible? → usar `IF NOT EXISTS`, `IF EXISTS`, `CREATE OR REPLACE`
+1. Does the change affect existing data? → include `UPDATE`/backfill before the `ALTER`
+2. Adding a `NOT NULL` column? → needs a `DEFAULT` or a prior backfill
+3. Dropping a column with data? → migrate the data first, then `DROP`
+4. New FK? → the referenced table must already exist
+5. Creating an index on a large table? → consider `CREATE INDEX CONCURRENTLY`
+6. Is the SQL idempotent where possible? → use `IF NOT EXISTS`, `IF EXISTS`, `CREATE OR REPLACE`
 
-## Cómo aplica npm run migrate
+## How npm run migrate applies changes
 
-1. Conecta a la DB leyendo `.env`
-2. Crea tabla `_migrations` si no existe
-3. Lista las **carpetas** de `migrations/` en orden alfabético
-4. Ejecuta `up.sql` de las carpetas no registradas en `_migrations`
-5. Registra el **nombre de la carpeta** con timestamp al aplicarla
-6. Cada migración se ejecuta en una transacción — si falla, hace ROLLBACK y para
+1. Connects to the DB by reading `.env`
+2. Creates the `migrations` tracking table if it doesn't exist (named to match the convention
+   TypeORM/NestJS uses, no leading underscore)
+3. Lists the **folders** in `migrations/` in alphabetical order
+4. Runs the `up.sql` of the folders not yet registered in the `migrations` table
+5. Registers each **folder name** with a timestamp once applied
+6. The whole run is **one transaction** — if any migration in the batch fails, every migration
+   applied earlier in that same run is rolled back too, not just the failing one
 
-## También actualizar schema/
+## Also update schema/
 
-Al crear una migración, actualizar también el `create.sql` correspondiente en `schema/` para que refleje el estado actual. `schema/` es el diseño vigente; `migrations/` es cómo llegamos ahí.
+When creating a migration, also update the corresponding `create.sql` in `schema/` so it reflects
+the current state. `schema/` is the current design; `migrations/` is how we got there.
 
-## Cómo revertir migraciones (npm run rollback)
+## How to revert migrations (npm run rollback)
 
-`rollback.ts` elimina el registro de `_migrations` y luego ejecuta el `down.sql` dentro de la misma transacción — en ese orden, para que si el `down.sql` dropa la tabla `_migrations`, la transacción igual cierre limpia.
+`rollback.ts` deletes each `migrations` table record and then runs its `down.sql`, in that order,
+so that if a `down.sql` drops the `migrations` table itself, the transaction still closes cleanly.
 
 ```bash
-# Revertir la última migración aplicada
+# Revert the last applied migration
 npm run rollback
 
-# Revertir las últimas N migraciones (en orden inverso)
+# Revert the last N migrations (in reverse order)
 npm run rollback 3
 ```
 
-Cómo funciona:
-1. Verifica que la tabla `_migrations` exista — si no, no hay nada que revertir
-2. Consulta `_migrations ORDER BY migration DESC` para obtener las últimas N
-3. Por cada una, en transacción: `DELETE FROM _migrations` → ejecuta `down.sql` → `COMMIT`
-4. Si `down.sql` falla, hace `ROLLBACK` y para
+How it works:
+1. Checks that the `migrations` table exists — if not, there's nothing to revert
+2. Queries `migrations ORDER BY migration DESC` to get the last N
+3. Wraps the whole batch in **one transaction**: for each one, `DELETE FROM migrations` → runs
+   `down.sql`; if any step fails, everything reverted so far in that run rolls back too
+4. Commits once, only after every migration in the batch reverted successfully
 
-**El `down.sql` debe existir.** Si no existe, el script para sin revertir nada.
+**`down.sql` must exist.** If it doesn't, the script stops without reverting anything.
 
-## Error común
+## Common error
 
-Si `npm run migrate` dice que ya está al día pero los cambios no aparecen:
+If `npm run migrate` says it's up to date but the changes don't show up:
 ```sql
-DELETE FROM _migrations WHERE migration = 'NNN_YYYYMMDD_HHMM_nombre';
+DELETE FROM migrations WHERE migration = 'NNN_YYYYMMDD_HHMM_name';
 ```
-Luego volver a correr `npm run migrate`. O crear una nueva migración con el cambio faltante.
+Then run `npm run migrate` again. Or create a new migration with the missing change.