@darkj/create-db 1.0.0 → 1.1.1

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

@@ -3,79 +3,81 @@ paths:
   - "schema/**"
 ---
 
-# Reglas para trabajar en schema/
+# Rules for working in schema/
 
-## Regla fundamental de rutas en init.sql
+## Fundamental rule for paths in init.sql
 
-**Todas las rutas en todos los `init.sql` deben ser absolutas desde la raíz del proyecto.**
+**All paths in every `init.sql` must be absolute from the project root.**
 
-psql resuelve los `\i` siempre desde su directorio de trabajo (CWD), no desde el directorio del archivo que se está leyendo. `build.py` también resuelve desde la raíz del proyecto (`ROOT_DIR`). Los dos se comportan igual — por eso todas las rutas deben ser desde la raíz.
+psql always resolves `\i` from its working directory (CWD), not from the directory of the file
+being read. `build.ts` also resolves from the project root (`ROOT_DIR`). Both behave the same way
+— that's why every path must be from the root.
 
 ```sql
--- CORRECTO — ruta desde la raíz
+-- CORRECT — path from the root
 \i schema/auth/roles/create.sql
 \i schema/auth/roles/data.sql
 
--- INCORRECTO — ruta relativa al archivo
+-- WRONG — path relative to the file
 \i create.sql
 \i ../roles/create.sql
 ```
 
-El usuario siempre debe estar parado en la raíz del proyecto al usar psql:
+The user must always be standing at the project root when using psql:
 ```
-\cd /ruta/al/proyecto
+\cd /path/to/project
 \i init.sql
 ```
 
 ---
 
-## Cómo agregar una tabla standalone
+## How to add a standalone table
 
 ```bash
-mkdir schema/mi-tabla
-touch schema/mi-tabla/create.sql schema/mi-tabla/data.sql schema/mi-tabla/init.sql
+mkdir schema/my-table
+touch schema/my-table/create.sql schema/my-table/data.sql schema/my-table/init.sql
 ```
 
-- `create.sql` → `CREATE TABLE` con columnas, constraints y FKs
-- `data.sql` → INSERTs de datos iniciales (roles, estados, catálogos). Si no hay, dejarlo comentado — el archivo debe existir igual
-- `init.sql` → rutas completas desde la raíz del proyecto:
+- `create.sql` → `CREATE TABLE` with columns, constraints, and FKs
+- `data.sql` → INSERTs for initial data (roles, statuses, catalogs). If there's none, leave it commented out — the file must still exist
+- `init.sql` → full paths from the project root:
 
 ```sql
--- sin triggers
-\i schema/mi-tabla/create.sql
-\i schema/mi-tabla/data.sql
-
--- con triggers
-\i schema/mi-tabla/create.sql
-\i schema/mi-tabla/data.sql
-\i schema/mi-tabla/triggers.sql
+-- without triggers
+\i schema/my-table/create.sql
+\i schema/my-table/data.sql
+
+-- with triggers
+\i schema/my-table/create.sql
+\i schema/my-table/data.sql
+\i schema/my-table/triggers.sql
 ```
 
-- Agregar `\i schema/mi-tabla/init.sql` a `schema/init.sql` en la posición correcta
+- Add `\i schema/my-table/init.sql` to `schema/init.sql` in the correct position
 
-## Cómo agregar un grupo
+## How to add a group
 
 ```bash
-mkdir schema/mi-grupo
-touch schema/mi-grupo/init.sql
+mkdir schema/my-group
+touch schema/my-group/init.sql
 ```
 
-El `init.sql` del grupo lista sus tablas con rutas completas desde la raíz: `\i schema/mi-grupo/mi-tabla/init.sql`. Agregar `\i schema/mi-grupo/init.sql` a `schema/init.sql`.
+The group's `init.sql` lists its tables with full paths from the root: `\i schema/my-group/my-table/init.sql`. Add `\i schema/my-group/init.sql` to `schema/init.sql`.
 
-## Cuándo crear un grupo vs standalone
+## When to create a group vs. standalone
 
-| Standalone | Grupo |
+| Standalone | Group |
 |---|---|
-| Tabla transversal a varios dominios (`parameters`, `tags`, `files`) | 2+ tablas del mismo dominio funcional |
-| Una sola tabla en ese dominio | Tablas que solo tienen sentido juntas |
+| Table shared across several domains (`parameters`, `tags`, `files`) | 2+ tables of the same functional domain |
+| A single table in that domain | Tables that only make sense together |
 
-## Lógica de agrupación por dominio
+## Domain grouping logic
 
-Agrupar por **responsabilidad funcional**, no por conveniencia técnica.
+Group by **functional responsibility**, not technical convenience.
 
-Grupos comunes:
+Common groups:
 
-| Grupo | Tablas típicas |
+| Group | Typical tables |
 |---|---|
 | `auth` | `users`, `roles`, `permissions`, `sessions` |
 | `catalog` | `products`, `categories`, `brands` |
@@ -83,48 +85,48 @@ Grupos comunes:
 | `payments` | `payments`, `payment_methods`, `invoices` |
 | `notifications` | `notifications`, `notification_types` |
 
-Una tabla que tiene FK hacia tablas de **dos grupos distintos** probablemente va standalone, después de ambos grupos en `schema/init.sql`.
+A table with FKs into **two different groups** probably goes standalone, after both groups in `schema/init.sql`.
 
-## Formato estándar de CREATE TABLE
+## Standard CREATE TABLE format
 
-Este es el formato propio del proyecto. Toda tabla nueva debe seguirlo sin excepción.
+This is the project's own format. Every new table must follow it without exception.
 
-### Orden de columnas (de arriba hacia abajo)
+### Column order (top to bottom)
 
 ```
-1. PK          → primera columna, siempre
-2. FKs         → en columnas simples, sin referenciar aún, después del PK
-3. Atributos   → campos propios de la tabla en orden lógico de importancia
-4. Timestamps  → created_at y updated_at al final, siempre TIMESTAMPTZ
-5. Constraints → PRIMARY KEY primero, luego cada FOREIGN KEY con REFERENCES
+1. PK          → first column, always
+2. FKs         → as plain columns, not yet referencing anything, right after the PK
+3. Attributes  → the table's own fields in logical order of importance
+4. Timestamps  → created_at and updated_at at the end, always TIMESTAMPTZ
+5. Constraints → PRIMARY KEY first, then each FOREIGN KEY with REFERENCES
 ```
 
 ### Naming
 
-- **Tablas**: `snake_case`, **plural** — representan una colección de registros (`users`, `order_items`)
-- **PK**: nombre de la tabla en singular + `_id` → `user_id`, `order_id`, `role_id`
-  - Si el nombre es largo, usar una versión simplificada que mantenga el contexto
-- **FK columns**: mismo formato que el PK de la tabla que referencian → `role_id`, `created_by`
-- Índices: `idx_{tabla}_{columna}` (`idx_users_email`)
-- Triggers: `trg_{tabla}_{descripcion}`
-- Funciones de trigger: `fn_{tabla}_{descripcion}`
-- Constraints únicos: `uq_{tabla}_{columna}` (`uq_users_email`)
+- **Tables**: `snake_case`, **plural** — they represent a collection of records (`users`, `order_items`)
+- **PK**: singular table name + `_id` → `user_id`, `order_id`, `role_id`
+  - If the name is long, use a shortened version that keeps the context
+- **FK columns**: same format as the PK of the table they reference → `role_id`, `created_by`
+- Indexes: `idx_{table}_{column}` (`idx_users_email`)
+- Triggers: `trg_{table}_{description}`
+- Trigger functions: `fn_{table}_{description}`
+- Unique constraints: `uq_{table}_{column}` (`uq_users_email`)
 
-### Ejemplo de referencia
+### Reference example
 
 ```sql
 CREATE TABLE users (
     user_id             SERIAL,
-    role_id             INT             NOT NULL,                        -- rol asignado al usuario
-    created_by          INT,                                             -- usuario que lo creó (NULL solo para root)
-    full_name           VARCHAR(150)    NOT NULL,                        -- nombre completo del usuario
-    username            VARCHAR(50)     NOT NULL UNIQUE,                 -- nombre de usuario único
-    email               VARCHAR(150),                                    -- correo electrónico
-    password_hash       VARCHAR(255)    NOT NULL,                        -- contraseña almacenada con hash seguro
-    failed_attempts     SMALLINT        NOT NULL DEFAULT 0,              -- contador de intentos de login fallidos
-    active              BOOLEAN         NOT NULL DEFAULT TRUE,           -- cuenta activa/inactiva (no se elimina)
-    requires_pwd_change BOOLEAN         NOT NULL DEFAULT TRUE,           -- fuerza cambio de contraseña en primer ingreso
-    locked_until        TIMESTAMPTZ,                                     -- fecha y hora hasta cuando la cuenta está bloqueada
+    role_id             INT             NOT NULL,                        -- role assigned to the user
+    created_by          INT,                                             -- user who created it (NULL only for root)
+    full_name           VARCHAR(150)    NOT NULL,                        -- user's full name
+    username            VARCHAR(50)     NOT NULL UNIQUE,                 -- unique username
+    email               VARCHAR(150),                                    -- email address
+    password_hash       VARCHAR(255)    NOT NULL,                        -- password stored with a secure hash
+    failed_attempts     SMALLINT        NOT NULL DEFAULT 0,              -- failed login attempt counter
+    active              BOOLEAN         NOT NULL DEFAULT TRUE,           -- active/inactive account (never deleted)
+    requires_pwd_change BOOLEAN         NOT NULL DEFAULT TRUE,           -- forces a password change on first login
+    locked_until        TIMESTAMPTZ,                                     -- date and time until the account is locked
     created_at          TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
     updated_at          TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
     PRIMARY KEY (user_id),
@@ -133,106 +135,109 @@ CREATE TABLE users (
 );
 ```
 
-### Reglas del formato
+### Format rules
 
-- **PK se declara como columna simple** (`SERIAL`) sin `PRIMARY KEY` inline — la constraint va al final
-- **FKs se declaran como columnas simples** (`INT`, `INT NOT NULL`) sin `REFERENCES` inline — la constraint va al final
-- **Alineación visual**: columna, tipo, constraints y comentario alineados con espacios para legibilidad
-- **Comentarios inline** (`--`) en toda columna que no sea autoexplicativa por su nombre
-- **`NOT NULL` explícito** en toda columna que no admite nulos — nunca asumir por defecto
-- **Timestamps**: siempre `TIMESTAMPTZ` (con zona horaria), nunca `TIMESTAMP` a secas
-- **Orden de constraints al final**: primero `PRIMARY KEY`, luego `FOREIGN KEY` en el mismo orden que aparecen las columnas FK arriba
+- **The PK is declared as a plain column** (`SERIAL`) without an inline `PRIMARY KEY` — the constraint goes at the end
+- **FKs are declared as plain columns** (`INT`, `INT NOT NULL`) without an inline `REFERENCES` — the constraint goes at the end
+- **Visual alignment**: column, type, constraints, and comment aligned with spaces for readability
+- **Inline comments** (`--`) on every column that isn't self-explanatory from its name
+- **Explicit `NOT NULL`** on every column that doesn't allow nulls — never assume the default
+- **Timestamps**: always `TIMESTAMPTZ` (with timezone), never bare `TIMESTAMP`
+- **Constraint order at the end**: `PRIMARY KEY` first, then each `FOREIGN KEY` in the same order the FK columns appear above
 
-### Tipos de datos
+### Data types
 
-| Dato | Tipo |
+| Data | Type |
 |---|---|
-| PK autoincremental | `SERIAL` |
-| FK, referencia a otra tabla | `INT` |
-| Texto con longitud conocida | `VARCHAR(N)` |
-| Texto sin límite | `TEXT` |
-| Contador pequeño | `SMALLINT` |
-| Número entero general | `INT` |
-| Dinero / precisión decimal | `NUMERIC(10,2)` — nunca `FLOAT` |
-| Booleano | `BOOLEAN` — nunca `INT` ni `CHAR` |
-| Solo fecha | `DATE` |
-| Fecha + hora + zona | `TIMESTAMPTZ` — siempre esta, nunca `TIMESTAMP` a secas |
-| Enumeraciones | tabla de catálogo con FK — nunca `ENUM` de Postgres (difícil de migrar) |
-
-### Columnas de auditoría
-
-Toda tabla de datos (no catálogo puro) cierra con:
+| Auto-incrementing PK | `SERIAL` |
+| FK, reference to another table | `INT` |
+| Text with a known length | `VARCHAR(N)` |
+| Unbounded text | `TEXT` |
+| Small counter | `SMALLINT` |
+| General integer | `INT` |
+| Money / decimal precision | `NUMERIC(10,2)` — never `FLOAT` |
+| Boolean | `BOOLEAN` — never `INT` or `CHAR` |
+| Date only | `DATE` |
+| Date + time + timezone | `TIMESTAMPTZ` — always this, never bare `TIMESTAMP` |
+| Enumerations | catalog table with FK — never Postgres `ENUM` (hard to migrate) |
+
+### Audit columns
+
+Every data table (not a pure catalog) closes with:
 ```sql
     created_at          TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
     updated_at          TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
 ```
 
-El `updated_at` se mantiene con un trigger en `triggers.sql`.
-Si aplica borrado lógico, agregar `deleted_at TIMESTAMPTZ` antes de `created_at`.
+`updated_at` is maintained with a trigger in `triggers.sql`.
+If soft delete applies, add `deleted_at TIMESTAMPTZ` before `created_at`.
 
-### Integridad referencial
+### Referential integrity
 
-Elegir `ON DELETE` conscientemente en cada FK:
+Choose `ON DELETE` deliberately on every FK:
 
-- `CASCADE` → el hijo no tiene sentido sin el padre (`order_items` → `orders`)
-- `SET NULL` → la relación es opcional (la columna FK debe admitir NULL)
-- Sin cláusula (default `RESTRICT`) → el borrado del padre se bloquea explícitamente
+- `CASCADE` → the child makes no sense without the parent (`order_items` → `orders`)
+- `SET NULL` → the relationship is optional (the FK column must allow NULL)
+- No clause (default `RESTRICT`) → deleting the parent is explicitly blocked
 
-### Índices
+### Indexes
 
-- La PK ya crea índice automáticamente
-- Crear índices en columnas frecuentes en `WHERE`, `JOIN ON`, `ORDER BY`
-- Índice compuesto cuando las queries filtran por dos columnas juntas
-- No sobre-indexar: cada índice tiene costo en escritura
+- The PK already creates an index automatically
+- Create indexes on columns frequently used in `WHERE`, `JOIN ON`, `ORDER BY`
+- Composite index when queries filter by two columns together
+- Don't over-index: every index has a write cost
 
 ### Triggers
 
-Solo crear `triggers.sql` si la tabla realmente lo necesita.
-Siempre usar `CREATE OR REPLACE FUNCTION` para que sea re-ejecutable.
+Only create `triggers.sql` if the table genuinely needs it.
+Always use `CREATE OR REPLACE FUNCTION` so it's re-runnable.
 
 ---
 
-## Diccionario de tabla (DICTIONARY.md)
+## Table dictionary (DICTIONARY.md)
 
-Cada carpeta de tabla debe tener un `DICTIONARY.md` junto a `create.sql`, `data.sql` e `init.sql`.
+Every table folder must have a `DICTIONARY.md` alongside `create.sql`, `data.sql`, and `init.sql`.
 
-**Cuándo generarlo**: al crear una tabla nueva o al recibir un `create.sql` existente.
-Si trabajo en una tabla que no tiene su `DICTIONARY.md`, preguntar si debo generarlo.
+**When to generate it**: when creating a new table or receiving an existing `create.sql`.
+If working on a table that doesn't have its `DICTIONARY.md`, ask whether to generate it.
 
-### Plantilla
+Write its content in the language noted under "Documentation language" in `.claude/CLAUDE.md` —
+this instruction stays in English, but the DICTIONARY.md text itself follows that setting.
+
+### Template
 
 ```markdown
-# {nombre_tabla}
+# {table_name}
 
-{Descripción en 1-2 líneas: qué representa esta tabla en el dominio del negocio.}
+{1-2 line description: what this table represents in the business domain.}
 
-## Columnas
+## Columns
 
-| Columna | Tipo | Nulo | Default | Descripción |
-|---------|------|------|---------|-------------|
-| {col}   | {tipo} | NO/SÍ | {default o —} | {descripción en lenguaje de negocio} |
+| Column | Type | Nullable | Default | Description |
+|--------|------|----------|---------|-------------|
+| {col}  | {type} | YES/NO | {default or —} | {description in business language} |
 
-## Relaciones
+## Relationships
 
-| Columna | Referencia | Descripción |
-|---------|------------|-------------|
-| {fk_col} | {tabla.col} | {qué representa esta relación en el negocio} |
+| Column | Reference | Description |
+|--------|-----------|--------------|
+| {fk_col} | {table.col} | {what this relationship means in the business} |
 
-## Reglas de negocio
+## Business rules
 
-- {regla o restricción relevante para el negocio}
-- {caso especial o comportamiento esperado}
+- {rule or constraint relevant to the business}
+- {special case or expected behavior}
 
-## Notas técnicas
+## Technical notes
 
-- {constraints, triggers, índices relevantes que no son obvios del create.sql}
+- {constraints, triggers, indexes relevant that aren't obvious from create.sql}
 ```
 
-### Reglas del diccionario
+### Dictionary rules
 
-- La descripción del header explica **qué representa** la tabla, no cómo está implementada
-- Columnas: descripciones en **lenguaje de negocio**, no técnico ("Rol del usuario" no "FK a roles")
-- Relaciones: solo las FK; explicar el **significado de la relación**, no solo el dato técnico
-- Reglas de negocio: comportamiento esperado, casos borde, qué operaciones están prohibidas
-- Notas técnicas: solo lo que no es visible a simple vista en el `create.sql` (triggers, índices, constraints nombrados)
-- Si una sección no aplica (ej. tabla sin FK → sin sección Relaciones), omitirla completamente
+- The header description explains **what the table represents**, not how it's implemented
+- Columns: descriptions in **business language**, not technical ("User's role" not "FK to roles")
+- Relationships: FKs only; explain the **meaning of the relationship**, not just the technical fact
+- Business rules: expected behavior, edge cases, which operations are forbidden
+- Technical notes: only what isn't obvious at a glance from `create.sql` (triggers, indexes, named constraints)
+- If a section doesn't apply (e.g. a table with no FKs → no Relationships section), omit it entirely

package/templates/base/init.sql

@@ -1,6 +1,6 @@
 -- ==========================================================
--- RESET COMPLETO — elimina todo y recarga desde schema/
--- Usar solo en entornos vacíos o de desarrollo.
+-- FULL RESET — drops everything and reloads from schema/
+-- Use only on empty or development environments.
 -- ==========================================================
 
 DO $$ DECLARE

package/templates/base/schema/init.sql

@@ -1,10 +1,10 @@
 -- ==========================================================
 -- SCHEMA LOAD ORDER
--- Rutas siempre desde la raíz del proyecto. Dependencias primero.
+-- Paths are always from the project root. Dependencies first.
 -- ==========================================================
 
--- Tabla standalone (sin grupo):
--- \i schema/mi-tabla/init.sql
+-- Standalone table (no group):
+-- \i schema/my-table/init.sql
 
--- Grupo de tablas:
--- \i schema/mi-grupo/init.sql
+-- Table group:
+-- \i schema/my-group/init.sql

package/templates/base/scripts/migrate.ts

@@ -24,7 +24,7 @@ function loadEnv(): Record<string, string> {
 
 async function ensureMigrationsTable(client: Client): Promise<void> {
   await client.query(`
-    CREATE TABLE IF NOT EXISTS _migrations (
+    CREATE TABLE IF NOT EXISTS migrations (
       migration   VARCHAR(255) PRIMARY KEY,
       applied_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
     )
@@ -33,7 +33,7 @@ async function ensureMigrationsTable(client: Client): Promise<void> {
 
 async function appliedMigrations(client: Client): Promise<Set<string>> {
   const result = await client.query<{ migration: string }>(
-    "SELECT migration FROM _migrations ORDER BY migration"
+    "SELECT migration FROM migrations ORDER BY migration"
   );
   return new Set(result.rows.map((r) => r.migration));
 }
@@ -75,23 +75,25 @@ async function main(): Promise<void> {
     return;
   }
 
-  for (const name of pending) {
-    const upPath = path.join(MIGRATIONS_DIR, name, "up.sql");
-    const sql = fs.readFileSync(upPath, "utf-8");
-    console.log(`Applying: ${name}`);
-    await client.query("BEGIN");
-    try {
+  // The whole run is one transaction: if any migration in this batch fails, every
+  // migration applied earlier in the same run is rolled back too, not just the failing one.
+  await client.query("BEGIN");
+  try {
+    for (const name of pending) {
+      const upPath = path.join(MIGRATIONS_DIR, name, "up.sql");
+      const sql = fs.readFileSync(upPath, "utf-8");
+      console.log(`Applying: ${name}`);
       await client.query(sql);
-      await client.query("INSERT INTO _migrations (migration) VALUES ($1)", [name]);
-      await client.query("COMMIT");
+      await client.query("INSERT INTO migrations (migration) VALUES ($1)", [name]);
       console.log(`  ✓ Done`);
-    } catch (err) {
-      await client.query("ROLLBACK");
-      console.error(`  ✗ Failed — rolled back`);
-      console.error(err);
-      await client.end();
-      process.exit(1);
     }
+    await client.query("COMMIT");
+  } catch (err) {
+    await client.query("ROLLBACK");
+    console.error(`  ✗ Failed — rolled back the whole batch`);
+    console.error(err);
+    await client.end();
+    process.exit(1);
   }
 
   console.log(`\nApplied ${pending.length} migration(s).`);

package/templates/base/scripts/rollback.ts

@@ -41,7 +41,7 @@ async function main(): Promise<void> {
   await client.connect();
 
   const tableCheck = await client.query<{ exists: boolean }>(
-    "SELECT EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'public' AND tablename = '_migrations') AS exists"
+    "SELECT EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'public' AND tablename = 'migrations') AS exists"
   );
   if (!tableCheck.rows[0].exists) {
     console.log("No applied migrations to revert.");
@@ -50,7 +50,7 @@ async function main(): Promise<void> {
   }
 
   const result = await client.query<{ migration: string }>(
-    "SELECT migration FROM _migrations ORDER BY migration DESC LIMIT $1",
+    "SELECT migration FROM migrations ORDER BY migration DESC LIMIT $1",
     [steps]
   );
 
@@ -60,28 +60,28 @@ async function main(): Promise<void> {
     return;
   }
 
-  for (const { migration } of result.rows) {
-    const downPath = path.join(MIGRATIONS_DIR, migration, "down.sql");
-    if (!fs.existsSync(downPath)) {
-      console.error(`No down.sql for migration: ${migration}`);
-      await client.end();
-      process.exit(1);
-    }
-    const sql = fs.readFileSync(downPath, "utf-8");
-    console.log(`Reverting: ${migration}`);
-    await client.query("BEGIN");
-    try {
-      await client.query("DELETE FROM _migrations WHERE migration = $1", [migration]);
+  // The whole run is one transaction: if any down.sql in this batch fails, every
+  // migration reverted earlier in the same run is rolled back too.
+  await client.query("BEGIN");
+  try {
+    for (const { migration } of result.rows) {
+      const downPath = path.join(MIGRATIONS_DIR, migration, "down.sql");
+      if (!fs.existsSync(downPath)) {
+        throw new Error(`No down.sql for migration: ${migration}`);
+      }
+      const sql = fs.readFileSync(downPath, "utf-8");
+      console.log(`Reverting: ${migration}`);
+      await client.query("DELETE FROM migrations WHERE migration = $1", [migration]);
       await client.query(sql);
-      await client.query("COMMIT");
       console.log(`  ✓ Reverted`);
-    } catch (err) {
-      await client.query("ROLLBACK");
-      console.error(`  ✗ Failed — rolled back`);
-      console.error(err);
-      await client.end();
-      process.exit(1);
     }
+    await client.query("COMMIT");
+  } catch (err) {
+    await client.query("ROLLBACK");
+    console.error(`  ✗ Failed — rolled back the whole batch`);
+    console.error(err);
+    await client.end();
+    process.exit(1);
   }
 
   console.log(`\nReverted ${result.rows.length} migration(s).`);