> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade guide

## General guidelines

**Always back up your database before starting the upgrade process** by running:

```bash theme={null}
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
```

To restore from backup:

```bash theme={null}
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
```

If you use Docker Compose, follow these steps:

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`

The server runs all required upgrade migrations automatically on startup. No manual command is needed.

### Redis cache prefix

`REDIS_CACHE_PREFIX` is optional and defaults to an empty string. Leaving it empty preserves existing cache key names exactly, with no extra colon and no key migration.

For Redis Enterprise or Azure Managed Redis deployments that report `CROSSSLOT` errors during cache operations, set `REDIS_CACHE_PREFIX={twenty-cache}` on every server, worker, and upgrade command. The braces make all cache-storage keys share one Redis hash slot. This does not distribute cache data across shards. `REDIS_QUEUE_PREFIX` applies only to queues and remains separate.

For example, `engine:workspace:flatObjectMetadataMaps:123:hash` becomes `{twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash` only when that prefix is configured. `cache:flush` automatically uses the configured prefix.

Changing the prefix switches to a separate cache namespace. Stop all Twenty servers and workers before changing it, then restart them with the same value. Existing entries under the previous prefix remain untouched. If you reuse a previously used prefix, run `yarn command:prod cache:flush` with that value before restarting to remove stale entries. Rolling deployments with different prefix values are not supported.

## Upgrading to v2.34+ — PostgreSQL 15 minimum

Twenty v2.34 requires PostgreSQL 15 or newer. The official Docker Compose configuration uses PostgreSQL 16. If your instance connects to an externally managed database, upgrade it before starting the v2.34 server.

## Cross-version upgrades (v1.23+)

Starting from **v1.23**, Twenty supports cross-version upgrades. You can jump directly from any supported version to the latest release without stepping through each intermediate version.

For example, upgrading from v1.23 straight to v2.0 is fully supported.

## Upgrading to v2.5+ — at-rest encryption envelope

Starting in **v2.5**, Twenty stores at-rest secrets (OAuth tokens, application variables, signing-key private keys, sensitive config values, TOTP secrets) inside a versioned `enc:v2:` envelope encrypted with `ENCRYPTION_KEY` (or `APP_SECRET` if `ENCRYPTION_KEY` is unset).

The first boot on v2.5 runs slow upgrade commands that **backfill** existing rows into the new envelope. They are idempotent — interrupting and restarting the server resumes from where it left off — but they can take a while on large databases. You can monitor progress with `upgrade:status`.

You should set a dedicated `ENCRYPTION_KEY` **before** the v2.5 upgrade so the backfill writes rows under it from the start. Switching keys after the backfill requires a [rotation](/developers/self-host/capabilities/key-rotation).

## Rotating secrets and signing keys

For day-to-day operational tasks like rotating `ENCRYPTION_KEY`, rotating the JWT signing key, or revoking a leaked signing key, see the dedicated [Key rotation guide](/developers/self-host/capabilities/key-rotation).

## Checking upgrade status

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 theme={null}
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
```

Example output:

```sh theme={null}
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
  App*** (20202020-***)
      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. |
| `--show-full-identifiers` | Display full workspace names and IDs. By default, only the first three characters of each workspace name and the first section of each workspace ID are shown. |

## 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 theme={null}
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.23

If your instance is older than v1.23, 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.23. From there, you can jump directly to the latest version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.