For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/backup-upgrade.md.
SFMC
  • English

      • Backup, upgrade, and rollback

      Backup

      Back up together:

      • data/ (SQLite)
      • configs/
      • modules/ (installed packages, catalog, and lock)
      • packs/ and the BDS world, behavior packs, resource packs, and world pack references

      Schedule a maintenance window. Stop BDS and db-server, verify both processes have exited, and then archive the assets above to a location outside the instance. Include the actual database path if it is outside data/; do not assume the BDS directory is named BedrockDedicatedServer.

      Check modules/packages/ for symlinks or Windows junctions first. Archiving modules/ alone may omit their targets: an isolated Compress-Archive check on Windows included ordinary files but skipped the junction's contents. Record each link and target, archive the actual source directories separately, and verify that both content and links can be restored. A dangling link is not a backed-up module. The simple archive examples in the Chinese guide apply only when the module directory has no links.

      Do not copy a live SQLite database while it may have uncheckpointed WAL data:

      sfmc> /stop -all
# archive and check the backup; keep services stopped if upgrading
      Important

      Do not copy .db files while db-server is running.

      Upgrade CLI / monorepo

      Global pnpm
      monorepo
      pnpm add -g @sfmc-bds/[email protected]

      pnpm v11+ waits 24 hours by default before selecting a newly published version from an unversioned package name. For a release-day upgrade, check pnpm view @sfmc-bds/sfmc version and install that exact version.

      Confirm SFMC_ROOT and the CLI version before changing the instance. Upgrading the CLI does not replace installed modules or the deployed behavior pack. In a maintenance window, install the intended module versions, then build and deploy before starting BDS:

      sfmc> mod reload --build-only

      Upgrade modules

      sfmc> mod install <id>
sfmc> mod reload --build-only

      Upgrade BDS

      sfmc> update
# or check only
sfmc> update --check-only

      If the upgrade includes schema migrations, rehearse them on an isolated copy and keep the pre-migration cold backup. Do not assume an older version can read data written by a newer version.

      Rollback

      TargetApproach
      Config / lockStop affected services, restore the matching cold backup, then start and inspect fresh logs
      Module behavior packStop BDS; restore the previous modules, catalog, lock, and deployed pack, or install an exact prior package with mod install <id> --from npm:@sfmc-bds/module-<id>@<version>; rebuild and start BDS
      BDSbds-tools rollback (if backup policy enabled)
      DatabaseStop all writers, preserve a copy of the failed state, restore a verified cold backup, and run SQLite integrity checks before starting

      Runtime state and logs: <SFMC_ROOT>/.sfmc/ (including db.log, qq.log, bds.log under logs/).