--- title: "systhema migrate" description: "Run one data migration, or `--schema`." requested_language: hu language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/hu/cli/migrate version: unreleased (main) docs_index: https://docs.systhema.app/hu/llms.txt --- > This page isn't translated yet. Showing English. Run a single **data migration** by id. These are the post-upgrade hooks that `systhema upgrade --allow-database` runs after `pnpm install` — the ones that rewrite stored database content rather than source files. `systhema migrate` exposes them individually, the same way `systhema codemod` exposes a single code codemod, for when you need to (re-)run one outside a full upgrade — e.g. after restoring a database snapshot, or to verify a migration in isolation. ```bash systhema migrate --list # list available data migrations systhema migrate unify-block-slugs-data # run by id systhema migrate unify-block-slugs-data --dry-run # plan only (reports it would run, runs nothing) ``` Each migration is **idempotent** and guards itself with an applicability check, so running one against an already-migrated project, the wrong project type, or a fresh install is a clean no-op. Under the hood each one is a thin wrapper around a project-local Payload bin script (with the package manager substituted in), so the two forms below are equivalent — `systhema migrate` just adds the `--list` index, the applicability check, and `--dry-run`: ```bash systhema migrate unify-block-slugs-data # ≡ pnpm payload migrate-unify-block-slugs ``` ## Available data migrations The currently bundled data migrations (Payload projects only): | ID | Release | Kind | Writes database | Description | | ---------------------------- | ------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `migrate-emails-data` | `1.6.0` | `rename` | yes | Copies the legacy emails global into general-settings.emails. Disabled tabs are skipped; an enabled tab requires its SQL destination. Preserve the legacy data until copied. Run nav renames before schema additions, then copy settings. For push-mode PostgreSQL, review `systhema migrate --schema --dry-run`, then apply `systhema migrate --schema`; do not run `payload migrate` with a dev-push marker or generate a full-schema migration without a baseline. For a migration-based project with an existing snapshot baseline and no dev marker, use `pnpm payload migrate:create`, review the DDL, then `pnpm payload migrate`. `systhema migrate --schema` needs `@systhemaui/cli` and `@systhemaui/payload` at 1.7.0-canary.16 or later; an older Payload package does not register the command. | | `migrate-header-nav-dbnames` | `1.6.0` | `rename` | yes | Runs the Payload bin script that renames the default Header global's nav objects — tables, and on Postgres also constraints, indexes, enum types, and owned sequences — to the namespaced forms `header_nav` / `header_sub_nav` (+ versioned `_header_nav_v` / `_header_sub_nav_v`) that Payload 3.85.0 generates (the dbName change shipped in v1.6.0 #65). Handles every pre-upgrade state: the 1.5.x long names (`header_navigation` / `header_navigation_sub_navigation` + `_v_version_*` siblings), the earlier canary bare names (`nav` / `sub_nav` + `_nav_v` / `_sub_nav_v`), and the half-migrated state where a prior canary renamed the tables but left the `enum_nav_*` enums and `_nav_v_id_seq` sequences stale. Enum types are the ones that trigger Drizzle's interactive rename prompt. Runs on Postgres AND SQLite (the dbName becomes the table name verbatim on both), idempotent, and a no-op on MongoDB, fresh installs, already-migrated DBs, custom Headers, and projects that strip enums to varchar via `beforeSchemaInit`. Safe to skip with `--skip migrate-header-nav-dbnames` if you have already renamed by hand. | | `unify-block-slugs-data` | `1.6.0` | `rename` | yes | Runs the Payload bin script that walks every Lexical-bearing collection (pages, components, …) and rewrites legacy block slugs to the unified forms (rootImage/regionImage/fragmentImage/nestedImage → image; same for video/youtube/googleMap/embed; formBlock/nestedFormBlock → form; nestedCard → card; nestedColumns → columns; nestedCarousel → carousel; richTextInStack/buttonInStack/chipInStack/iconInStack/avatarInStack → richText/button/chip/icon/avatar; imageInStack/nestedImageInStack → image). Also injects `_tier` on every block. Idempotent. Safe to skip with `--skip unify-block-slugs-data` if you have already migrated by hand. | | `migrate-localize-status` | `1.7.0` | `rename` | yes | Per-locale publishing is now on by default for every project with locales, so `_status` moves from the shared column on `pages`, `posts` and `components` (and their `_v` version tables) into their `_locales` siblings. The script performs the whole transition in a transaction and writes the matching Payload migration file when the project has a migration directory. It is idempotent: a second run reports "already migrated" and exits 0. Skip it with `--skip migrate-localize-status` if you are opting out with `localization: { localizeStatus: false }`, or if you migrate on your own deploy schedule. | | `migrate-seo-data` | `1.7.0` | `rename` | yes | Copies the legacy seo global into general-settings.seo. Disabled tabs are skipped; an enabled tab requires its SQL destination. Preserve the legacy data until copied. Run nav renames before schema additions, then copy settings. For push-mode PostgreSQL, review `systhema migrate --schema --dry-run`, then apply `systhema migrate --schema`; do not run `payload migrate` with a dev-push marker or generate a full-schema migration without a baseline. For a migration-based project with an existing snapshot baseline and no dev marker, use `pnpm payload migrate:create`, review the DDL, then `pnpm payload migrate`. `systhema migrate --schema` needs `@systhemaui/cli` and `@systhemaui/payload` at 1.7.0-canary.16 or later; an older Payload package does not register the command. | | `migrate-capability-strings` | `1.7.1` | `rename` | yes | Rewrites stored per-user capability strings after the emails and SEO capability renames. On PostgreSQL, add the replacement enum labels before this hook. Run this before an operator-owned enum recreate that removes the legacy labels. | ### Migration behavior - ----------------------------: ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ - `migrate-localize-status`: Moves `_status` out of the shared column on `pages`, `posts` and `components` (and their `_v` version tables) into their `_locales` siblings, so each locale carries its own publication state. Runs in one transaction; a rerun reports "already migrated" and exits 0. On a project that keeps a Payload migration directory it also writes the matching `*_systhema_localize_status.ts` migration and records it in `payload-migrations`, so the same move reaches production through `payload migrate`. See [Per-locale publishing](https://docs.systhema.app/hu/payload/localization/per-locale-publishing.md). - `migrate-header-nav-dbnames`: **Postgres + SQLite.** Renames the default Header global's `navigation` / `subNavigation` tables to their explicit `dbName` forms (`header_nav` / `header_sub_nav` / `_header_nav_v` / `_header_sub_nav_v`), plus the dependent constraints/indexes/enums/sequences on Postgres and the indexes on SQLite. No-op on MongoDB. `migrate-localize-status` can perform the complete transition itself. [Per-locale publishing](https://docs.systhema.app/hu/payload/localization/per-locale-publishing.md) is on by default for every project with `locales` configured, so `systhema upgrade` plans the migration whenever the project is a Payload project, has locales, and has not opted out with `localization: { localizeStatus: false }`. It is idempotent, so declining it costs nothing: `--skip migrate-localize-status` leaves it for later, and `systhema migrate migrate-localize-status` runs it whenever you are ready. `systhema doctor`'s `localize-status-schema` check reports a project that never ran it. A Payload project can also run `pnpm payload systhema-localization-report` at any time — a read-only dry run printing which fields [the content localization field policy](https://docs.systhema.app/hu/payload/localization/field-policy.md)'s `policy: 'all'` would move from shared to localized, and how many rows the back-fill would write per locale. It is not part of `systhema upgrade`; `systhema doctor`'s `localization-policy` check points at it. ## Schema reconciliation For additive PostgreSQL schema reconciliation, use `systhema migrate --schema --dry-run` to print the live-catalog SQL and `systhema migrate --schema` to print and apply it in one transaction. Both run with stdin closed. This path works without Payload migration history and retains legacy tables. It is separate from named data hooks and is not run automatically by `upgrade`. See [Non-interactive schema migration](https://docs.systhema.app/hu/payload/database/schema-migration.md) for supported changes, refusal cases, and the required nav/schema/SEO ordering. ## Options | Flag | Description | Default | | ----------- | ----------------------------------------------------------------------- | ------- | | `--dry-run` | Plan only, no changes | `false` | | `--list` | List available data migrations | `false` | | `--schema` | Add missing PostgreSQL schema objects without prompts; prints SQL first | `false` | See [Database migrations](https://docs.systhema.app/hu/payload/database/migrations.md) for what these steps do, why they run before Payload's first schema push, and how they differ from project-owned Payload migrations.