Upgrade guide

General guidelines

Always 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

To restore from backup:

cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}

If you use Docker Compose, follow these steps:

Stop Clara: docker compose down
Change the TAG value in the .env file next to your docker-compose.yml
Start Clara: docker compose up -d

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

Cross-version upgrades (v1.22+)

Starting from v1.22, Clara 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.22 straight to v2.0 is fully supported.

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:

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status

Example output:

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:

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.

Overview

Apps

API

Self-Host

Contribute

General guidelines

Cross-version upgrades (v1.22+)

Checking upgrade status

Options

Troubleshooting

Before v1.22

​General guidelines

​Cross-version upgrades (v1.22+)

​Checking upgrade status

​Options

​Troubleshooting

​Before v1.22

General guidelines

Cross-version upgrades (v1.22+)

Checking upgrade status

Options

Troubleshooting

Before v1.22