Workspace Migrations & Instance Commands

Relevant source files

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

• CLAUDE.md
• .cursor/rules/server-migrations.mdc
• packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration.module.ts
• packages/twenty-shared/src/constants/DocumentationPaths.ts
• packages/twenty-docs/MIGRATION.md

Workspace migrations and instance commands constitute the core mechanism for managing database schema evolution and data consistency within the Twenty CRM platform. This system allows developers to apply global instance-level changes and iterate over specific workspace schemas to perform upgrades, backfills, and metadata synchronizations.

The architecture distinguishes between "Fast" commands for schema updates and "Slow" commands for data-intensive migrations. It leverages TypeORM for relational mapping and NestJS modules to manage the lifecycle of workspace migrations across a multi-tenant environment.

Sources: CLAUDE.md, .cursor/rules/server-migrations.mdc

Architecture and Command Types

The migration system is divided into specific command categories based on their impact and execution speed. These commands are discovered automatically using decorators and are executed via the Nx CLI.

Instance Commands

Instance commands are global operations that affect the platform's core infrastructure or metadata.

• Fast Instance Commands: Used primarily for schema changes (e.g., adding columns, changing types). These are expected to execute quickly during deployment.
• Slow Instance Commands: Include a runDataMigration step intended for backfilling data or performing complex transformations that might take significant time.

Sources: CLAUDE.md:144-150, .cursor/rules/server-migrations.mdc

Workspace Commands

Workspace commands are designed to iterate over all active and suspended workspaces. This is crucial for Twenty's multi-tenant architecture, where each workspace may have its own specific schema or configuration that needs to stay in sync with the core engine.

Sources: CLAUDE.md:151-152, packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration.module.ts

Command Lifecycle Flow

The following diagram illustrates the workflow for generating and executing database migrations:

This flowchart shows the process from detecting an entity change to successfully applying a migration using instance command decorators.
Sources: CLAUDE.md:144-155

Key Commands and CLI Operations

Database operations are managed through Nx targets within the twenty-server package.

Operation	Command	Description
Reset Database	npx nx database:reset twenty-server	Wipes and resets the entire database.
Initialize Database	npx nx run twenty-server:database:init:prod	Initializes the database for production.
Run Migrations	npx nx run twenty-server:database:migrate:prod	Executes pending fast instance commands.
Generate Migration	npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>	Scaffolds a new migration file.

Sources: CLAUDE.md:46-51

Implementation Guidelines

Developers must follow strict rules when implementing migration logic to prevent data loss or deployment failures:

The Up/Down Pattern

Every instance command must include both up and down logic.

• Up: Applies the change.
• Down: Reverses the change to allow for rollbacks.
• Immutability: Once an instance command's up/down logic is committed, it should never be deleted or rewritten.

Sources: CLAUDE.md:154-156

Multi-Tenant Schema Structure

The Postgres database uses a complex multi-tenant structure that migrations must navigate:

• Core Schema: Shared platform data.
• Metadata Schema: Definitions of objects and fields.
• Workspace-specific Schemas: Isolated data for each individual tenant.

Sources: CLAUDE.md:57-61

Workspace Migration Module

The WorkspaceMigrationModule in the server engine is responsible for orchestrating the migration process across different workspaces. It utilizes NestJS providers to inject necessary services for schema management.

// packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration.module.ts

@Module({
  providers: [
    WorkspaceMigrationService,
    WorkspaceMigrationRunner,
    // Additional migration logic providers
  ],
  exports: [WorkspaceMigrationService],
})
export class WorkspaceMigrationModule {}

Sources: packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration.module.ts

Conclusion

Workspace Migrations and Instance Commands provide a robust framework for maintaining a scalable, multi-tenant CRM. By enforcing specific command types (Fast vs. Slow) and requiring reversible logic (Up/Down), the system ensures that schema evolutions are predictable and safe across thousands of isolated workspace schemas.

Sources: CLAUDE.md, .cursor/rules/server-migrations.mdc