n8n/packages/@n8n/db/AGENTS.md

AGENTS.md

Extra information specific to the @n8n/db package.

Creating Migrations

Migration files are named {TIMESTAMP}-{DescriptiveName}.ts. The timestamp must be the exact Unix millisecond timestamp at the time of creation — do not round or fabricate a value. Use Date.now() in a Node REPL or date +%s%3N in a shell (GNU date) to generate it.

Migration DSL

UUID Primary Keys

Do not use autoGenerate or autoGenerate2 on UUID columns. Both cause TypeORM to emit DEFAULT uuid_generate_v4() in PostgreSQL, which requires the uuid-ossp extension in the public schema. This fails on managed Postgres services like Supabase where the extension lives in a different schema.

Instead, generate UUIDs at the application level:

Migration:

column('id').uuid.primary.notNull,

Entity:

import { randomUUID } from 'node:crypto';
import { BeforeInsert, PrimaryColumn } from '@n8n/typeorm';

@PrimaryColumn('uuid')
id: string;

@BeforeInsert()
generateId() {
  if (!this.id) {
    this.id = randomUUID();
  }
}

autoGenerate / autoGenerate2 are fine for integer columns (they use serial / GENERATED BY DEFAULT AS IDENTITY respectively).