Database & Persistence Layer
Relevant source files
The following files were used as context for generating this wiki page:
The Database and Persistence Layer manages how n8n stores, retrieves, and updates workflow data, execution history, and internal state. n8n uses TypeORM as its Object-Relational Mapper (ORM) to interface with relational databases like SQLite and PostgreSQL. This layer enforces strict architectural boundaries to separate business logic from low-level database operations, ensuring data integrity through centralized transaction management.
Sources: AGENTS.md:195-201, CONTRIBUTING.md:23-28
Core Architecture and Boundaries
The persistence layer follows a Controller-Service-Repository pattern. Business logic resides in services and controllers, while all direct database interactions occur within repositories.
The TypeORM Boundary
n8n enforces a strict boundary for TypeORM. Business logic must not import from @n8n/typeorm. Instead, it interacts with repositories defined in the @n8n/db package or backend-specific persistence adapters. Repository methods take plain parameters and return domain-shaped values rather than exposing raw TypeORM entities or operators to the rest of the system.
Sources: AGENTS.md:195-205, AGENTS.md:209-211
This diagram shows the unidirectional flow from business logic to the persistence layer, illustrating the strict TypeORM boundary. Sources: AGENTS.md:195-205
Transaction Management
Transaction orchestration occurs exclusively within the persistence layer. Business logic triggers transactions using a sanctioned TransactionRunner primitive rather than directly accessing the TypeORM manager.
Transaction Execution Flow
- The service injects the
TransactionRunner. - The service wraps units of work in
txRunner.run(ctx, async (ctx) => ...). - The
runmethod requires anOperationContext(ctx) to track the active transaction. - Repositories resolve the correct
EntityManagerusingthis.managerFor(ctx).
This approach ensures that transactions are joined rather than nested if a context already carries an active transaction.
Sources: AGENTS.md:212-218
This sequence diagram visualizes how the TransactionRunner coordinates atomic units of work across repositories. Sources: AGENTS.md:212-218
Supported Database Systems
n8n supports multiple database backends for different environments.
| Database | Primary Use Case | Management Tool |
|---|---|---|
| SQLite | Local development, simple installations, and testing. | tbls (for schema docs) |
| PostgreSQL | Production environments, high-availability setups. | tbls (for schema docs) |
| Vector Databases | AI/LangChain workflows (Pinecone, Qdrant, Supabase). | N/A |
Sources: CONTRIBUTING.md:86-90, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:63-80
Persistence in AI and Vector Stores
For AI-driven workflows, n8n utilizes vector databases to store and retrieve high-dimensional embeddings. Unlike standard relational persistence, this involves semantic search.
Vector Store Operations
Vector stores within n8n support several key persistence modes:
- Insert: Stores document chunks and their generated embeddings.
- Retrieve: Fetches relevant documents based on semantic similarity to a query.
- Retrieve-as-tool: Allows AI Agents to query the knowledge base on-demand.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:25-35, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:Connection-changing parameters
Data Retention and Cleanup
Relational and vector data persistence must handle updates and deletions to prevent "stale data."
- Unique IDs: n8n uses a combination of Document ID and Chunk Number as a unique identifier to enable targeted updates.
- Namespaces: Vectors are separated into namespaces (e.g.,
hr-policies,tech-docs) to maintain organizational boundaries.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:139-145, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:182-185
Development and Schema Management
Schema Documentation
Database schema documentation is automatically generated from migrations using tbls. This tool runs via git hooks whenever migration files change.
Sources: CONTRIBUTING.md:86-93
Testing Mocks
In unit tests, the persistence layer is mocked using vitest-mock-extended. Developers mock the IDataStoreProjectService and other repository interfaces to ensure tests do not require a live database connection.
Sources: packages/nodes-base/TESTING_PROMPT.md:Mocking Strategies
Key Persistence Components
| Component | Description | File Path |
|---|---|---|
TransactionRunner | Abstract primitive for managing transaction contexts. | packages/@n8n/db |
BaseRepository | Base class for all TypeORM repositories. | packages/@n8n/db |
n8n Data Tables | Internal database storage requiring no external credentials. | n8n-nodes-base.dataTable |
execution_repository | Manages persistence for workflow execution history. | packages/cli/.../execution.repository.ts |
Sources: AGENTS.md:212-218, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:Node selection patterns
The n8n persistence layer ensures that data access is predictable and safe by isolating TypeORM behind repositories and centralizing transaction logic through an operation context.