AGENTS.md

1# AGENTS.md
2 
3Extra information specific to the `@n8n/db` package.
4 
5## TypeORM boundary
6 
7This package **is** the persistence layer, so importing `@n8n/typeorm` here is
8expected. The convention for the rest of the codebase — business logic must not
9import `@n8n/typeorm` — is in the root [AGENTS.md](../../../AGENTS.md)
10("Persistence layer & the TypeORM boundary"), along with the anti-patterns
11reviewers reject.
12 
13When you add a repository method for a consumer, name it for the use case and
14type its parameters and return value in **domain terms** — don't surface
15`FindOptionsWhere` / entity-`Repository` methods across the boundary, and don't
16add generic `find(options)` passthroughs. This keeps operators and query
17construction inside the persistence layer where they belong.
18 
19## Transactions
20 
21Both transaction primitives live here: the deprecated `withTransaction` helper
22(`src/utils/transaction.ts`) and the `TransactionRunner` port
23(`src/services/transaction.ts`). New code uses `TransactionRunner`; see the root
24and `packages/cli` AGENTS.md for which to use and why.
25 
26## Database migrations
27 
28For full guidance on authoring migrations — scaffolding, the pre-flight
29checklist the `@n8n-io/migrations-review` team enforces, the
30`MigrationContext` API reference, the DSL type mapping, and the detailed
31rule catalogue — use the **`n8n:db-migrations`** skill.
32 
33Source-of-truth files the skill defers to:
34- `packages/@n8n/db/src/migrations/migration-types.ts` — `MigrationContext`, `ReversibleMigration`, `IrreversibleMigration`
35- `packages/@n8n/db/src/migrations/dsl/` — schema builder DSL
36- `packages/@n8n/backend-test-utils/MIGRATION_TESTING.md` — migration testing helpers
37