Upgrade a client site

GoalLink to this section

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 firstLink to this section

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

Read the Changelog, served at /changelog, before running the upgrade. With the docs MCP, request the interval explicitly:

{
  "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 concreteLink to this section

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:

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 changesLink to this section

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 releaseLink to this section

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:

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 and PostgreSQL schema migration for ordering and limits. SQLite sites also need applicable rename hooks; the additive --schema path is PostgreSQL-specific.

5. Verify and deployLink to this section

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 workLink to this section

• 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.