Database Schema & Twenty ORM

Twenty utilizes a multi-tenant database architecture powered by PostgreSQL and managed through TypeORM within a NestJS backend. The system is designed to handle complex CRM data models, including standard objects (like Companies and Persons) and user-defined custom objects, all while maintaining strict data isolation across different workspace schemas.

The "Twenty ORM" layer provides a developer-friendly abstraction for interacting with this schema, allowing for the definition of objects, fields, and relationships as code. This ensures that the database remains the "source of truth" while offering the flexibility needed for a highly customizable CRM platform.

Sources: CLAUDE.md:83-87, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:129-135

Database Architecture

Twenty's database is structured to support multi-tenancy and high extensibility. It primary uses PostgreSQL as the relational data store, complemented by Redis for caching and ClickHouse for analytics.

Schema Multi-Tenancy

The PostgreSQL instance is organized into distinct schemas to ensure isolation:

• Core Schema: Contains global system data.
• Metadata Schema: Stores definitions for objects, fields, and workspace configurations.
• Workspace-Specific Schemas: Each workspace has its own schema to house its unique data and custom object records.

Sources: CLAUDE.md:65-71, CLAUDE.md:124-128

Database Operations Flow

The following diagram illustrates the interaction between the application layer and the database during common operations such as migrations and data inspection.

The Postgres MCP server provides a read-only interface for inspecting workspace data and metadata definitions without modifying the underlying records.
Sources: CLAUDE.md:65-75, CLAUDE.md:124-128

Data Modeling & Entities

In Twenty, the data model is composed of "Objects" which represent entities (e.g., Leads, Opportunities, Companies). These can be Standard Objects provided by the system or Custom Objects created by developers or users.

Key Components of an Object

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:46-51, packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:38-42

Object Lifecycle and Relationships

Objects are designed to be reused and extended. Standard objects like Company, Person, and Opportunity provide built-in capabilities such as attachments, notes, tasks, and timelines. When defining new models, the system encourages using Person with a role flag (e.g., "Ambassador") before creating a completely new custom object.

Relationships in Twenty are "two-file relations," meaning they are explicitly defined on both sides of the link to maintain referential integrity within the ORM.
Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:52-54, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:129-135

Twenty ORM Development Workflow

Developers interact with the database primarily through the Twenty SDK and CLI tools. This "code-first" approach ensures that schema changes are versioned and reproducible.

Migration Management

Schema changes are handled through "Instance Commands." These are categorized into two types:

1. Fast Commands: Handle standard schema changes (adding columns, changing types).
2. Slow Commands: Include a runDataMigration step for complex data backfills.

# Generate an instance command
npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>

# Run migrations
npx nx run twenty-server:database:migrate:prod

Sources: CLAUDE.md:113-119

App Entity Definition

When developing apps that extend Twenty, entities are defined in the src/ directory. The ORM enforces a "one export per file" rule for helpers and types to maintain modularity.

System Fields

Every record automatically inherits several system-managed fields used for auditing and internal logic:

• id: A unique UUID v4.
• createdAt: Timestamp of record creation.
• updatedAt: Timestamp of the last modification.
• deletedAt: Used for soft-deletion logic.

Sources: packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md:65-72, packages/twenty-codex-plugin/references/develop-app/app-structure.md:31-35

Permissions & Row-Level Security (RLS)

Twenty implements a sophisticated permissions model that operates at multiple levels: Object, Field, and Row.

• Object Level: Determines if a user can access the entity at all.
• Field Level: Restricts access to specific sensitive attributes (e.g., a "Social Security Number" field).
• Row-Level Security (RLS): Filters the actual database rows returned based on the user's workspace role or record ownership. This is a core feature of the "Organization" plan.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:56-58, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:188-192

Summary

The Database Schema and Twenty ORM form the foundational layer of the Twenty CRM. By combining a multi-tenant PostgreSQL structure with a rigid yet flexible code-first ORM, Twenty allows developers to build complex data-driven applications while ensuring data integrity, isolation, and auditability across workspaces. Key tools like the Instance Command CLI and the Postgres MCP server empower developers to manage migrations and inspect metadata efficiently.