The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Upgrade command internal doc (#19541)
Paul Rastoin847e7124d727
diff --git a/.claude-pr/CLAUDE.md b/.claude-pr/CLAUDE.mdindex 229477b7aaf..c0200c5c7c2 100644--- a/.claude-pr/CLAUDE.md+++ b/.claude-pr/CLAUDE.md@@ -71,10 +71,10 @@ npx nx build twenty-server# Database managementnpx nx database:reset twenty-server # Reset databasenpx nx run twenty-server:database:init:prod # Initialize database-npx nx run twenty-server:database:migrate:prod # Run migrations+npx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)-# Generate migration-npx nx run twenty-server:database:migrate:generate+# Generate an instance command (fast or slow)+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>```### Database Inspection (Postgres MCP)@@ -158,14 +158,17 @@ packages/- **Redis** for caching and session management- **BullMQ** for background job processing-### Database & Migrations+### Database & Upgrade Commands- **PostgreSQL** as primary database- **Redis** for caching and sessions- **ClickHouse** for analytics (when enabled)-- Always generate migrations when changing entity files-- Migration names must be kebab-case (e.g. `add-agent-turn-evaluation`)-- Include both `up` and `down` logic in migrations-- Never delete or rewrite committed migrations+- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)+- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills+- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades+- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery+- Include both `up` and `down` logic in instance commands+- Never delete or rewrite committed instance command `up`/`down` logic+- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation### Utility HelpersUse existing helpers from `twenty-shared` instead of manual type guards:@@ -178,7 +181,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li### Before Making Changes1. Always run linting (`lint:diff-with-main`) and type checking after code changes2. Test changes with relevant test suites (prefer single-file test runs)-3. Ensure database migrations are generated for entity changes+3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)4. Check that GraphQL schema changes are backward compatible5. Run `graphql:generate` after any GraphQL schema changesdiff --git a/.cursor/rules/README.mdc b/.cursor/rules/README.mdcindex 88b1b3b495e..c725458435e 100644--- a/.cursor/rules/README.mdc+++ b/.cursor/rules/README.mdc@@ -12,7 +12,7 @@ This directory contains Twenty's development guidelines and best practices in th### Core Guidelines- **architecture.mdc** - Project overview, technology stack, and infrastructure setup (Always Applied)- **nx-rules.mdc** - Nx workspace guidelines and best practices (Auto-attached to Nx files)-- **server-migrations.mdc** - Backend migration and TypeORM guidelines for `twenty-server` (Auto-attached to server entities and migration files)+- **server-migrations.mdc** - Upgrade command guidelines (instance commands and workspace commands) for `twenty-server` (Auto-attached to server entities and upgrade command files)- **creating-syncable-entity.mdc** - Comprehensive guide for creating new syncable entities (with universalIdentifier and applicationId) in the workspace migration system (Agent-requested for metadata-modules and workspace-migration files)### Code Quality@@ -81,10 +81,8 @@ npx nx run twenty-server:typecheck # Type checkingnpx nx run twenty-server:test # Run unit testsnpx nx run twenty-server:test:integration:with-db-reset # Run integration tests-# Migrations-npx nx run twenty-server:database:migrate:generate--# Workspace+# Upgrade commands (instance + workspace)+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>```## Usage Guidelinesdiff --git a/.cursor/rules/changelog-process.mdc b/.cursor/rules/changelog-process.mdcindex 14776fa66b6..e6a5bbb671a 100644--- a/.cursor/rules/changelog-process.mdc+++ b/.cursor/rules/changelog-process.mdc@@ -55,7 +55,8 @@ If feature descriptions are not provided or need enhancement, research the codeb- Services: Look for `*.service.ts` files**For Database/ORM Changes:**-- Migrations: `packages/twenty-server/src/database/typeorm/`+- Instance commands (fast/slow): `packages/twenty-server/src/database/commands/upgrade-version-command/`+- Legacy TypeORM migrations: `packages/twenty-server/src/database/typeorm/`- Entities: `packages/twenty-server/src/entities/`### Research Commandsdiff --git a/.cursor/rules/server-migrations.mdc b/.cursor/rules/server-migrations.mdcindex 57115554dc8..91693bed0ac 100644--- a/.cursor/rules/server-migrations.mdc+++ b/.cursor/rules/server-migrations.mdc@@ -1,27 +1,46 @@----description: Guidelines for generating and managing TypeORM migrations in twenty-server+description: Guidelines for generating and managing upgrade commands (instance commands and workspace commands) in twenty-serverglobs: ["packages/twenty-server/src/**/*.entity.ts",- "packages/twenty-server/src/database/typeorm/**/*.ts"+ "packages/twenty-server/src/database/commands/upgrade-version-command/**/*.ts"]alwaysApply: false----## Server Migrations (twenty-server)+## Upgrade Commands (twenty-server)-- **When changing an entity, always generate a migration**- - If you modify a `*.entity.ts` file in `packages/twenty-server/src`, you **must** generate a corresponding TypeORM migration instead of manually editing the database schema.- - Use the Nx command from the project root:+The upgrade system uses two types of commands instead of raw TypeORM migrations:+- **Instance commands** — schema and data migrations that run once at the instance level.+- **Workspace commands** — commands that iterate over all active/suspended workspaces.++See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation.++### Instance Commands++- **When changing a `*.entity.ts` file**, generate an instance command:```bash- npx nx run twenty-server:database:migrate:generate+ npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>```-- **Prefer generated migrations over manual edits**- - Let TypeORM infer schema changes from the updated entities; only adjust the generated migration file manually if absolutely necessary (for example, for data backfills or complex constraints).- - Keep schema changes (DDL) in these generated migrations and avoid mixing in heavy data migrations unless there is a strong reason and clear comments.+- **Fast commands** (`--type fast`, default) are for schema-only changes that must run immediately. They implement `FastInstanceCommand` with `up`/`down` methods and use the `@RegisteredInstanceCommand` decorator.++- **Slow commands** (`--type slow`) add a `runDataMigration` method for potentially long-running data backfills that execute before `up`. They only run when `--include-slow` is passed. Use the decorator with `{ type: 'slow' }`.++- The generator auto-registers the command in `instance-commands.constant.ts` — do not edit that file manually.++- **Keep commands consistent and reversible**: include both `up` and `down` logic. Do not delete or rewrite existing, committed commands unless on a pre-release branch.++### Workspace Commands++- Use the `@RegisteredWorkspaceCommand` decorator alongside nest-commander's `@Command` decorator.+- Extend `ActiveOrSuspendedWorkspaceCommandRunner` and implement `runOnWorkspace`.+- The base class provides `--dry-run`, `--verbose`, and workspace filter options automatically.++### Execution Order-- **Keep migrations consistent and reversible**- - Ensure the generated migration includes both `up` and `down` logic that correctly applies and reverts the entity change when possible.- - Do not delete or rewrite existing, committed migrations unless you are explicitly working on a pre-release branch where history rewrites are allowed by team conventions.+Within a given version, commands run in this order (timestamp-sorted within each group):+1. Instance fast commands+2. Instance slow commands (only with `--include-slow`)+3. Workspace commandsdiff --git a/CLAUDE.md b/CLAUDE.mdindex 229477b7aaf..c0200c5c7c2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -71,10 +71,10 @@ npx nx build twenty-server# Database managementnpx nx database:reset twenty-server # Reset databasenpx nx run twenty-server:database:init:prod # Initialize database-npx nx run twenty-server:database:migrate:prod # Run migrations+npx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)-# Generate migration-npx nx run twenty-server:database:migrate:generate+# Generate an instance command (fast or slow)+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>```### Database Inspection (Postgres MCP)@@ -158,14 +158,17 @@ packages/- **Redis** for caching and session management- **BullMQ** for background job processing-### Database & Migrations+### Database & Upgrade Commands- **PostgreSQL** as primary database- **Redis** for caching and sessions- **ClickHouse** for analytics (when enabled)-- Always generate migrations when changing entity files-- Migration names must be kebab-case (e.g. `add-agent-turn-evaluation`)-- Include both `up` and `down` logic in migrations-- Never delete or rewrite committed migrations+- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)+- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills+- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades+- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery+- Include both `up` and `down` logic in instance commands+- Never delete or rewrite committed instance command `up`/`down` logic+- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation### Utility HelpersUse existing helpers from `twenty-shared` instead of manual type guards:@@ -178,7 +181,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li### Before Making Changes1. Always run linting (`lint:diff-with-main`) and type checking after code changes2. Test changes with relevant test suites (prefer single-file test runs)-3. Ensure database migrations are generated for entity changes+3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)4. Check that GraphQL schema changes are backward compatible5. Run `graphql:generate` after any GraphQL schema changesdiff --git a/packages/twenty-server/docs/UPGRADE_COMMANDS.md b/packages/twenty-server/docs/UPGRADE_COMMANDS.mdnew file mode 100644index 00000000000..024fc3eb0a5--- /dev/null+++ b/packages/twenty-server/docs/UPGRADE_COMMANDS.md@@ -0,0 +1,117 @@+# Upgrade Commands++The upgrade process relies on two types of commands:++- **Instance commands** — schema and data migrations that run once at the instance level (replacing raw TypeORM migrations).+- **Workspace commands** — commands that iterate over all active or suspended workspaces to apply per-workspace changes.++Both are registered via decorators and automatically discovered by the upgrade pipeline.++## Instance Commands++### Generating an instance command++```bash+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>+```++This generates a timestamped file and auto-registers it in `instance-commands.constant.ts` — do not edit that file manually.++### Fast instance commands++Fast commands run immediately during the upgrade. They are used for schema changes that could introduce breaking inconsistencies between the database and the server if delayed.++A fast command implements `FastInstanceCommand` and provides `up` / `down` methods:++```ts+@RegisteredInstanceCommand('1.22.0', 1775758621017)+export class AddWorkspaceIdToTotoFastInstanceCommand+ implements FastInstanceCommand+{+ public async up(queryRunner: QueryRunner): Promise<void> {+ await queryRunner.query(+ `ALTER TABLE "core"."toto" ADD "workspaceId" uuid`,+ );+ }++ public async down(queryRunner: QueryRunner): Promise<void> {+ await queryRunner.query(+ `ALTER TABLE "core"."toto" DROP COLUMN "workspaceId"`,+ );+ }+}+```++### Slow instance commands++Slow commands are used when a potentially long-running data migration must happen before the schema change. They only run when the `--include-slow` flag is passed.++A slow command implements `SlowInstanceCommand`, which extends `FastInstanceCommand` with an additional `runDataMigration` method that executes before `up`:++```ts+@RegisteredInstanceCommand('1.22.0', 1775758621018, { type: 'slow' })+export class BackfillWorkspaceIdSlowInstanceCommand+ implements SlowInstanceCommand+{+ async runDataMigration(dataSource: DataSource): Promise<void> {+ // Backfill logic (can be slow — e.g. iterating over workspaces, cache recomputation)+ }++ public async up(queryRunner: QueryRunner): Promise<void> {+ await queryRunner.query(+ `ALTER TABLE "core"."toto" ALTER COLUMN "workspaceId" SET NOT NULL`,+ );+ }++ public async down(queryRunner: QueryRunner): Promise<void> {+ await queryRunner.query(+ `ALTER TABLE "core"."toto" ALTER COLUMN "workspaceId" DROP NOT NULL`,+ );+ }+}+```++A common pattern is to pair a **fast** command (add a nullable column) with a **slow** command (backfill existing rows, then set `NOT NULL`).++## Workspace Commands++Workspace commands run per-workspace logic across all active or suspended workspaces. They are registered with the `@RegisteredWorkspaceCommand` decorator alongside nest-commander's `@Command` decorator:++```ts+@RegisteredWorkspaceCommand('1.22.0', 1780000002000)+@Command({+ name: 'upgrade:1-22:backfill-standard-skills',+ description:+ 'Backfill standard skills for existing workspaces',+})+export class BackfillStandardSkillsCommand+ extends ActiveOrSuspendedWorkspaceCommandRunner+{+ constructor(+ protected readonly workspaceIteratorService: WorkspaceIteratorService,+ // inject any services you need+ ) {+ super(workspaceIteratorService);+ }++ override async runOnWorkspace({+ workspaceId,+ options,+ }: RunOnWorkspaceArgs): Promise<void> {+ // Per-workspace logic goes here+ // options.dryRun, options.verbose are available for free+ }+}+```++The base class `ActiveOrSuspendedWorkspaceCommandRunner` handles workspace iteration and provides `--dry-run`, `--verbose`, and workspace filter options automatically.++## Execution Order++Within a given version of Twenty, the upgrade pipeline runs commands in this order, sorted by timestamp within each group:++1. **Instance fast** commands+2. **Instance slow** commands+3. **Workspace commands**++Workspace commands are executed sequentially across all active/suspended workspaces.