47 lines
2.1 KiB
Plaintext
47 lines
2.1 KiB
Plaintext
---
|
|
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
|
|
|