---
description: Guidelines for generating and managing upgrade commands (instance commands and workspace commands) in twenty-server
globs: [
  "packages/twenty-server/src/**/*.entity.ts",
  "packages/twenty-server/src/database/commands/upgrade-version-command/**/*.ts"
]
alwaysApply: false
---

## Upgrade Commands (twenty-server)

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 --name <name> --type <fast|slow>
    ```

- **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

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 commands