---
title: "Upgrade a client site"
description: "Read upgrade notes, review the CLI plan and apply changes through the correct database lane."
requested_language: ar
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/ar/next/guides/recipes/upgrading-a-client-site
version: unreleased (main)
docs_index: https://docs.systhema.app/ar/next/llms.txt
---
> This page isn't translated yet. Showing English.


## Goal

Upgrade a client site with a reviewed file and database plan. Rehearse the release against a copy of production data before changing the live site.

## 1. Read the installed version and notes first

```bash
node -p "require('./node_modules/@systhemaui/core/package.json').version"
systhema info
```

Read the [Changelog](../../release-notes/index.md), served at `/changelog`, before running the upgrade. With the docs MCP, request the interval explicitly:

```json title="get_upgrade_notes arguments"
{
  "from": "1.6.0",
  "to": "1.7.5",
  "detail": "outline"
}
```

Use the actual installed and target versions. Read the full sections for changes that affect this project's modules, token names, roles or schema. Do not let the CLI plan replace the release's upgrade instructions.

## 2. Make recovery concrete

Start with a clean branch. Back up the database and uploads, and confirm you can restore them. Record the deployment revision, environment choices, adapter and whether the site has project-owned Payload migration history.

Update the global CLI if required. An omitted upgrade target defaults to the CLI's own version, not a registry lookup for the newest release:

```bash
systhema self-update
systhema upgrade 1.7.5 --dry-run
```

Use your reviewed target in place of `1.7.5`. Review token migrations, codemods, package changes, managed-file updates and database hooks.

## 3. Apply the reviewed file changes

```bash
systhema upgrade 1.7.5
```

The interactive command reviews its changes. For automation, `--yes` accepts file defaults; it does not authorize database-writing hooks. Those require `--allow-database` after you review and authorize the database plan.

Review `.new` managed-file siblings rather than overwriting customized files wholesale. Keep the site's configuration choices and supported Payload package versions aligned.

## 4. Use the database lane declared by the release

| Lane      | What changes                          | Required action                                            |
| --------- | ------------------------------------- | ---------------------------------------------------------- |
| A, rename | Existing database objects are renamed | Run the release's rename hooks before the next schema push |
| B, shape  | Stored data or schema shape changes   | Use reviewed project-owned Payload migrations              |

A shape hook blocks upgrade when a migration directory is missing. Do not bypass that requirement by starting the application and accepting destructive schema suggestions.

For a PostgreSQL database that has only used development push, the additive path is:

```bash
systhema migrate --schema --dry-run
systhema migrate --schema
```

Use it only after reviewing the release's instructions and the dry-run output. It adds schema without offering unrelated DROP objects as rename candidates and does not write Payload migration history. It does not replace the shape lane or a project's existing migration history.

See [Database migrations](https://docs.systhema.app/ar/next/payload/database/migrations.md) and [PostgreSQL schema migration](https://docs.systhema.app/ar/next/payload/database/schema-migration.md) for ordering and limits. SQLite sites also need applicable rename hooks; the additive `--schema` path is PostgreSQL-specific.

## 5. Verify and deploy

```bash
pnpm sync
pnpm exec tsc --noEmit
pnpm lint
pnpm format
systhema doctor
pnpm build
```

Check existing pages, custom blocks, live preview, forms, password reset and each locale against the rehearsed database. Verify that known content survived and that publishing revalidates it.

Deploy only after the migration rehearsal passes. Record the applied hooks and migration files so the next developer knows which lane the site uses.

## Check your work

- Upgrade notes were read before file changes.
- The dry-run plan and final diff were reviewed.
- Database-writing steps have explicit authorization and a restore path.
- Stored content and client roles survive the rehearsal.
- Build, health checks and signed-out smoke tests pass.