Migration
Plan identity, business data, files, subscriptions, and rollout when changing deployment modes.
Changing modes for an existing product is a migration project. The safe order is inventory → identity mapping → data copy → file copy → entitlement reconciliation → staged client rollout.
Migration checklist
- Freeze the source schema and export users, provider identities, business rows, files, and subscription evidence.
- Define a durable mapping from source user IDs to Better Auth user IDs. Never assume IDs keep their format.
- Recreate profiles and business data with ownership mapped to the destination session identity.
- Copy files, preserve MIME and ownership metadata, and rewrite persisted URLs only after verification.
- Reconcile one authoritative subscription snapshot per destination user before opening purchase buttons.
- Configure trusted origins, OAuth audiences, webhook secrets, storage, and push providers on the host.
- Ship a staging build with explicit Unified configuration and no fallback; run the shared smoke test.
- Roll out with observability and a rollback window. Revoke old sessions only after the new path is confirmed.
Never point an existing client at the new base URL before identity and entitlement mappings are complete. A successful network request can still attach data to the wrong account.
The reverse migration follows the same principles: create independent identities and stores, copy data, then change the deployed client preset.