Description
Local and Hosted Workspace Migration moves a company-scoped Dots workspace between a local PostgreSQL instance and a hosted deployment. The transfer builds an ordered table plan, resolves the intended company, copies tenant-scoped relational data and supported blobs, and validates the destination rather than treating a successful stream as proof. Stable identifiers are preserved so rows, relations, and graph references keep their meaning after the move.
The package includes one-way local-to-hosted and hosted-to-local legs plus a round-trip proof driver. Safety checks refuse protected or ambiguous source/target environments, and schema/catalog comparison catches incompatible destinations. Validation collects scoped facts and ID-stability evidence so migration can report exactly what held or failed.
Selling Points
- Lets customers begin locally and later adopt a shared hosted deployment without recreating their knowledge base.
- Supports the reverse path, preserving an exit route from hosted service back to self-managed infrastructure.
- Maintains identifiers across transfers, protecting links and graph relationships that depend on stable row identity.
- Validates the destination and supports round-trip rehearsal, turning portability into an exercised capability rather than a marketing promise.
- Scopes the transfer to the intended company instead of copying an entire multi-tenant database.
User Story
A small team starts with a bundled local workspace during evaluation. When collaboration expands, an operator runs the local-to-hosted migration leg against the new company destination. Dots transfers the scoped data, checks the catalog and IDs, and reports validation facts. Later, the team can rehearse the reverse leg into a scratch local instance to confirm ongoing portability.
Extension Surface
This feature is automatable. packages/local-runtime/src/client/migrate.ts exposes migration legs to the CLI, and packages/local-runtime/src/proof/legs.ts provides programmatic local-to-hosted and hosted-to-local drivers. The workflow can be scripted and rehearsed, but its table plan and correctness checks are core implementation rather than a third-party migration-adapter registry.
Capabilities & Limits
- Transfers tenant-scoped relational data and supported file/blob content in both directions.
- Preserves and asserts stable IDs across the move.
- Validates schema shape, scoped facts, and round-trip outcomes using scratch deployments.
- Limit: the source and target must be compatible Dots schemas; unsafe environment combinations are refused.
- Limit: unsupported external storage capabilities are reported rather than silently pretending all blobs moved.
Implementation Map
packages/local-runtime/src/client/migrate.tspackages/local-runtime/src/db/migrate-bridge.tspackages/local-runtime/src/db/migrate-validate.tspackages/local-runtime/src/proof/legs.tspackages/local-runtime/src/proof/round-trip.ts