benefriches: Skill for Claude Code

Create Database Migration

Generate timestamped Knex migrations following project conventions.

Quick Start

1. Create migration: pnpm --filter api knex:new-migration {description}
   • Example: pnpm --filter api knex:new-migration add-column-email-to-users-table
   • Creates timestamped file in apps/api/src/shared-kernel/adapters/sql-knex/migrations/
2. Implement up() and down() functions in the generated file
3. Update apps/api/src/shared-kernel/adapters/sql-knex/tableTypes.d.ts if schema changes
4. If new table created: add table name to tablesToCleanUp in apps/api/test/tablesToCleanUp.ts (child tables before parent tables)
5. Run: pnpm --filter api knex:migrate-latest

Transaction Handling

Knex automatically wraps each migration in a transaction — the knex parameter in up()/down() is already a transaction object. Do NOT call knex.transaction() inside migrations.

// WRONG — redundant nested transaction
export async function up(knex: Knex): Promise<void> {
  await knex.transaction(async (trx) => {
    await trx.schema.createTable("example", (table) => { /* ... */ });
  });
}

// CORRECT — knex is already a transaction
export async function up(knex: Knex): Promise<void> {
  await knex.schema.createTable("example", (table) => { /* ... */ });
}

To opt out of auto-transaction for a specific migration (e.g., DDL that can't run in a transaction):

export const config = { transaction: false };

File Naming

Format: {YYYYMMDDHHmmss}_{verb}-{description}.ts

Operation	Pattern	Example
Create table	create-table-{name}	20250211105813_create-table-users-features-alerts.ts
Add column	add-column-{name}-to-{table} or add-{name}-to-{table}	20250915091313_add_newsletter_subscription_to_users_table.ts
Drop column	drop-{column}-from-{table}	20250613111514_drop-is_friche-column-from-sites-table.ts
Rename column	rename-{old}-to-{new}-in-{table}	20250729160857_rename-insee-to-city_code-in-cities-table.ts
Update data	update-{description}	20250225095318_update-friche-activity-values-in-sites-table.ts