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:
```typescript
column('id').uuid.primary.notNull,
```

Entity:
```typescript
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).