Elgato_dark/twenty
1
0
Fork 0
mirror of https://github.com/twentyhq/twenty synced 2026-04-21 13:37:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 17

Cross version and upgrade status docs (#19926)

Browse source
This commit is contained in:
Paul Rastoin 2026-04-21 11:40:23 +02:00 committed by GitHub
parent cd73088be6
commit a583ee405b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 72 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
packages/twenty-docs/developers/self-host/capabilities/upgrade-guide.mdx
View file

@ -5,26 +5,86 @@ icon: "arrow-up-right-dots"
## General guidelines
**Always make sure to back up your database before starting the upgrade process** by running `docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql`.
**Always back up your database before starting the upgrade process** by running:
To restore backup, run `cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}`.
```bash
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
```
If you used Docker Compose, follow these steps:
To restore from backup:
1. In a terminal, on the host where Twenty is running, turn off Twenty: `docker compose down`
```bash
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
```
2. Upgrade the version by changing the `TAG` value in the .env file near your docker-compose. ( We recommend consuming `major.minor` version such as `v0.53` )
If you use Docker Compose, follow these steps:
3. Bring Twenty back online with `docker compose up -d`
1. Stop Twenty: `docker compose down`
2. Change the `TAG` value in the `.env` file next to your `docker-compose.yml`
3. Start Twenty: `docker compose up -d`
**Make sure that after each upgraded version you have non-corrupted backup.**
The server runs all required upgrade migrations automatically on startup. No manual command is needed.
## Version-specific upgrade steps
## Cross-version upgrades (v1.22+)
## After v1.21
Starting from **v1.22**, Twenty supports cross-version upgrades. You can jump directly from any supported version to the latest release without stepping through each intermediate version.
We know support sequential upgrades. You don't need to go through each version one by one.
For example, upgrading from v1.22 straight to v2.0 is fully supported.
## Before v1.21
## Checking upgrade status
Make sure to go through every major tagged version when upgrading (upgrade v1.6.x to v.7.y, then v.7.y to v.8.z, etc.).
The `upgrade:status` command lets you inspect the current state of your instance and workspace migrations. It is useful for debugging upgrade issues or when filing a support request.
Run it from the server container:
```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
```
Example output:
```sh
APP_VERSION: v1.23.0
Instance
Inferred version: 1.23.0
Latest command: 1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
Status: Up to date
Executed by: v1.23.0
At: 2026-04-16T11:43:58.823Z
Workspace
Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
Inferred version: 1.23.0
Latest command: 1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
Status: Up to date
Executed by: v1.23.0
At: 2026-04-16T11:44:09.361Z
Summary
Instance: Up to date
Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
```
### Options
| Flag | Description |
| --- | --- |
| `-w, --workspace-id <id>` | Filter to a specific workspace. Can be passed multiple times. |
| `-f, --failed-only` | Hide up-to-date workspaces, only show behind and failed entries. |
## Troubleshooting
If the upgrade fails on some workspaces, the server will not advance past the failing step. Restarting the server (`docker compose up -d`) will retry the upgrade from where it left off.
To quickly identify problems, run:
```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
```
This shows only workspaces that are behind or have failed, along with the error message for each failure.
## Before v1.22
If your instance is older than v1.22, you must upgrade incrementally through each major tagged version (v1.6 to v1.7, then v1.7 to v1.8, and so on) until you reach v1.22. From there, you can jump directly to the latest version.