Skip to content

docs: datastore migration guide for mobile#8580

Merged
cadivus merged 5 commits intodocs/datastore-migrationfrom
docs/datastore-migration-mobile
Apr 29, 2026
Merged

docs: datastore migration guide for mobile#8580
cadivus merged 5 commits intodocs/datastore-migrationfrom
docs/datastore-migration-mobile

Conversation

@cadivus
Copy link
Copy Markdown
Member

@cadivus cadivus commented Apr 29, 2026

Addition to #8578

Description

Updates the DataStore-to-GraphQL migration guide to include backend changes required for a zero-downtime migration.

Problem

PR #8540 assumes clients can keep their Gen1 backend with DataStore/conflict resolution enabled. This is incorrect because:

  • Soft-deleted items (_deleted: true) remain in DynamoDB
  • Standard GraphQL clients (Apollo) receive ALL items including soft-deleted ones
  • Without _deleted in the schema, clients cannot filter them out

Solution

This PR documents the correct migration approach:

  1. Disable conflict resolution via amplify update api
  2. Manually re-add _deleted: Boolean to the GraphQL schema (maps to existing DynamoDB data)
  3. amplify push to apply changes
  4. Update frontend clients to filter { _deleted: { ne: true } }
  5. (Optional) Clean up soft-deleted items and remove _deleted field once all clients are migrated

Why this approach?

  • Zero-downtime: backwards-compatible with both DataStore and Apollo clients
  • No maintenance window required
  • No race conditions with in-flight deletions
  • Gradual migration path: clients can be migrated incrementally

Files changed

  • src/directory/directory.mjs — Added navigation entries for the new migration guide pages
  • src/pages/gen1/[platform]/.../migrate-from-datastore/index.mdx — Parent page explaining why backend changes are required
  • src/pages/gen1/[platform]/.../migrate-from-datastore/disable-conflict-resolution/index.mdx — Step-by-step guide for disabling conflict resolution

Testing

  • All 59 test suites pass (269 tests)
  • yarn prebuild generates directory.json successfully with new entries

Related: #8540

@cadivus cadivus requested a review from a team as a code owner April 29, 2026 00:53
@cadivus cadivus changed the title Docs/datastore migration mobile docs: datastore migration guide for mobile Apr 29, 2026
@cadivus cadivus merged commit b3c69f5 into docs/datastore-migration Apr 29, 2026
3 checks passed
@cadivus cadivus deleted the docs/datastore-migration-mobile branch April 29, 2026 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant