Data Tables Management

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md
• packages/quality/testing/playwright/tests/e2e/data-tables/tables.spec.ts
• packages/quality/testing/playwright/tests/e2e/data-tables/details.spec.ts
• packages/cli/src/modules/source-control.ee/source-control-import.service.ee.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts

Data Tables Management allows users to store, retrieve, and manipulate structured data within the n8n ecosystem without external database dependencies. The system provides a built-in persistent storage solution for workflows, supporting operations such as row insertion, updates, and complex schema definitions.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:219-223, packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md:1-10

Architecture and Core Components

The Data Table system integrates directly into the n8n CLI and node infrastructure. It utilizes a repository-based pattern for managing table metadata and a DDL (Data Definition Language) service to manage physical database tables.

Component Interaction

The following diagram illustrates the relationship between the Source Control service, the Data Table repository, and the physical database layer.

Data Table Schema

Every Data Table includes default system columns and user-defined columns. The system enforces strict naming conventions and type validation for all columns.

Column Category	Field/Type	Description
System Default	id (String)	Unique identifier for the row.
System Default	createdAt (Date)	Timestamp of row creation.
System Default	updatedAt (Date)	Timestamp of last modification.
User Defined	string	For text, email, phone, or IDs.
User Defined	number	For counts, amounts, or ages.
User Defined	boolean	For true/false flags.
User Defined	date	For calendar dates.

Sources: packages/quality/testing/playwright/tests/e2e/data-tables/details.spec.ts:100-110, packages/cli/src/modules/source-control.ee/source-control-import.service.ee.ts:1335-1345, packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md:70-95

Operational Logic

Workflow Integration

Workflows interact with Data Tables using the n8n-nodes-base.dataTable node. Common operations include insert, update, and get.

• Insert: Adds new rows to a table. Users often use this for logging extracted document data.
• Update: Modifies existing rows based on matching columns (e.g., matching by id or email).
• Get: Retrieves rows, often used for dashboard pre-loading or conditional logic.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:219-223, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:70-85

Row Life Cycle

The following sequence diagram shows the process of inserting a row through a workflow node, including validation and physical table update.

Import and Synchronization

The SourceControlImportService manages the lifecycle of Data Tables during environment synchronization (e.g., Pulling from Git).

Identity Adoption and Reconciliation

When a table in the source control has the same name and project as a local table but a different ID, the system performs "Identity Adoption." This re-keys the local metadata and renames the physical SQL table to match the incoming remote ID while preserving existing row data.

1. Check Existence: Verify if the physical table for the new ID already exists.
2. Rename Table: Rename the physical SQL table if necessary.
3. Update Metadata: Delete old metadata and insert new metadata with the remote ID.
4. Sync Columns: Map existing column data to new column IDs where names and types match.

Sources: packages/cli/src/modules/source-control.ee/source-control-import.service.ee.ts:1474-1502

Ownership Resolution

Data Table ownership is determined by the project type. During import, the system resolves the target project based on the following logic:

• Team Projects: Use the specific teamId provided in the export.
• Personal Projects: Attempt to find the local personal project of the original owner via email; otherwise, fall back to the personal project of the user performing the pull.

Sources: packages/cli/src/modules/source-control.ee/source-control-import.service.ee.ts:1456-1472

Management Best Practices

Schema Design Patterns

• Leads/Contacts: Use email as a unique identifier for matching and updates.
• Orders: Keep order_id as a string even if it appears numeric to prevent precision issues.
• Workflow State: Use a status column and processed_at date for idempotency in processing queues.

Sources: packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md:28-55

Import Quality Checks

Before bulk inserting data (e.g., from CSV or JSON), the manager performs the following checks:

• Drops empty columns from the source.
• Flattens nested JSON objects if they contain useful fields.
• Prefers string types for postal codes and phone numbers to preserve formatting.

Sources: packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md:70-85

Summary

Data Tables Management provides a native, schema-aware storage layer for n8n. It bridges the gap between transient workflow data and permanent external storage by offering a repository-driven architecture that handles metadata synchronization, physical table schema evolution, and structured data operations within the application core.

Sources: packages/cli/src/modules/source-control.ee/source-control-import.service.ee.ts:1330-1345, packages/@n8n/instance-ai/skills/data-table-manager/references/data-table-playbook.md:1-10