Database migration

Treat a database move as a restore into a new installation, not as an in-place conversion.

Prepare

1. Confirm both source and destination versions are supported.
2. Install the required database client tools and run the portability preflight.
3. Stop writes or schedule a maintenance window.
4. Create a complete, verified backup of database and blobs.
5. Choose an explicit destination that does not exist, or an empty database that has never been published.

Restore and verify

Keep the destination unpublished while the tool restores and verifies it. On an isolated origin, compare:

• document and account counts;
• roles, groups, and exceptional document restrictions;
• search results for representative terms;
• original-file access across old and recent documents;
• connector and token configuration that is expected to carry over.

Publish only after these checks pass. Keep the old installation stopped and recoverable through the rollback window.

Common stops

• “the destination must be an explicit path that does not exist” — choose a new path; do not point at a directory whose contents are uncertain.
• “the restore target database must be empty and unpublished” — create a fresh destination database.
• “a required database portability tool is unavailable” — install the client tool named in the surrounding diagnostic.
• “the database portability tool version is incompatible” — use the supported client major version for the source/destination.

See Error messages for recovery steps.