Workspace provisioning and migration

Tenant Provisioning & Data Migration

When to Use

Use when implementing workspace creation/onboarding, running schema or data migrations across tenants, transferring resources between workspaces, or deprovisioning and purging a workspace.

1. Idempotent Workspace Provisioning

Creating a workspace often spans multiple steps (creating the workspaces row, assigning the creator as owner in workspace_memberships, seeding default roles/settings/templates, initializing billing/quota records, and provisioning storage/search namespaces):

• Atomic Core + Reconcilable Provisioning State:
  • Execute core database creation (workspace + initial owner membership + default config) inside a single atomic DB transaction so a workspace is never created with 0 owners.
  • If external provisioning is required (Stripe customer creation, dedicated search index, default storage prefix), track provisioning_status (provisioning $\rightarrow$ active / provisioning_failed) with idempotent retry keys so network retries never create duplicate external resources.

2. Multi-Tenant Schema & Data Backfill Discipline

• Shared-Schema Migrations:
  • Remember that ALTER TABLE or backfilling a table shared by 10,000 tenants locks or taxes I/O for every active customer simultaneously. Use non-blocking expand-and-contract steps (ADD COLUMN NULL, batched per-tenant background backfill, CREATE INDEX CONCURRENTLY).
• Schema-per-Tenant / DB-per-Tenant Migrations (when applicable):
  • Track migration version per tenant, run migrations with bounded concurrency, and isolate failures so one tenant with corrupt legacy data does not halt deployment for healthy tenants.

3. Controlled Cross-Workspace Resource Copy / Move

Never allow ad-hoc UPDATE table SET workspace_id = $new WHERE id = $id! Moving a parent row without moving its entire transitive dependency graph creates cross-tenant foreign-key corruption:

• Explicit Transfer Rules:
  1. Verify the actor holds export/move permission in the source workspace and create/import permission in the target workspace.
  2. Enumerate the full closure of dependent records (child rows, attachments/storage blobs, comments, tags) and either deep-copy/re-key them into the target workspace with new IDs and storage keys, or update the entire subgraph atomically while stripping source-workspace-specific references (e.g., user assignees who are not members of the target workspace, source webhook/integration IDs).
  3. Record audit log entries in both the source and target workspaces.

4. Complete Workspace Deprovisioning & GDPR Erasure

When a workspace transitions from pending_deletion (grace period) to permanent erasure:

• Purge in deterministic order across every storage tier:
  1. Cancel active background jobs, webhooks, and external subscriptions.
  2. Delete search index documents and vector embeddings for tenant_id.
  3. Delete object storage blobs (tenants/${tenantId}/...) and invalidate CDN/Redis caches.
  4. Delete relational database records in foreign-key order (or via verified ON DELETE CASCADE in batched chunks to avoid long table locks) and record a minimal tombstoned erasure certificate for compliance.