aws-amplify · cadivus · Apr 29, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 29, 2026
diff --git a/cspell.json b/cspell.json
@@ -1650,7 +1650,12 @@
     "posttags",
     "callouts",
     "immer",
-    "ERESOLVE"
+    "ERESOLVE",
+    "graphqls",
+    "swiftpm",
+    "xcshareddata",
+    "unsynced",
+    "vararg"
   ],
   "flagWords": ["hte", "full-stack", "Full-stack", "Full-Stack", "sudo"],
   "patterns": [

@@ -1908,12 +1908,41 @@ export const directory = {
                             {
                               path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/add-local-caching/index.mdx'
                             },
-
                             {
                               path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/advanced-patterns/index.mdx'
                             },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/remove-datastore/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/schema-and-operations/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/set-up-apollo-kotlin/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/set-up-apollo-ios/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/migrate-datastore-to-apollo/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/migrate-to-api/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/local-caching/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/offline-first/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/authorization-and-data/index.mdx'
+                            },
                             {
                               path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/disable-conflict-resolution/index.mdx'
+                            },
+                            {
+                              path: 'src/pages/gen1/[platform]/build-a-backend/more-features/datastore/migrate-from-datastore/helpful-resources/index.mdx'
                             }
                           ]
                         }

@@ -0,0 +1,52 @@
+import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
+
+export const meta = {
+  title: 'Authorization and data handling',
+  description: 'Manage authorization rules and handle existing customer data during the migration from DataStore to Amplify API for Flutter.',
+  platforms: [
+    'flutter'
+  ]
+};
+
+export const getStaticPaths = async () => {
+  return getCustomStaticPath(meta.platforms);
+};
+
+export function getStaticProps(context) {
+  return {
+    props: {
+      platform: context.params.platform,
+      meta
+    }
+  };
+}
+
+## Authorization rules
+
+As part of the transition from Amplify DataStore, it is essential to understand how to manage authorization rules for your models using AWS AppSync, which continues to serve as the source of truth for all auth rules. While DataStore previously handled the synchronization and application of these rules automatically, the responsibility now shifts to you as the developer to integrate these auth rules into your chosen local data storage solution.
+
+Here are some key considerations:
+
+- **AppSync as the source of truth:** AWS AppSync remains the authoritative service for defining and enforcing authorization rules for your models. Ensure that your local data handling and synchronization strategies are aligned with the rules set in AppSync to maintain security and data consistency.
+- **Managing local storage:** You are responsible for implementing the logic to save data to your selected local storage solution. This includes ensuring that your offline models are compatible with the authorization rules defined in AppSync.
+- **Clearing local storage on sign-out:** As a best practice, clear your local storage whenever a user signs out of your application. This helps to prevent unauthorized access to data and ensures that each user's session begins with a fresh, secure state aligned with the current auth rules.
+
+## Handle existing customer data
+
+As you transition from Amplify DataStore to a new local storage solution, it is important to carefully manage the data currently stored on users' devices. The approach varies depending on whether your application is connected to AWS AppSync for remote synchronization or operates entirely in a local-only mode.
+
+### Connected apps using AWS AppSync
+
+If your application connects to AWS AppSync for data synchronization, AWS AppSync should be treated as the single source of truth. During migration:
+
+1. **Sync unsynced data.** Before transitioning to the new local store, ensure that any unsynced data on the device is successfully pushed to AWS AppSync.
+2. **Re-sync from AppSync.** Once the unsynced data is uploaded, clear the existing local storage and initialize the new local store. Use AWS AppSync to re-sync all necessary data down to the device.
+3. **Validate data.** After re-syncing, perform validation checks to confirm that the data in your new local store matches the data in AWS AppSync.
+
+### Local-only users
+
+If your application operates without a remote sync to AWS AppSync, handle the migration of local data manually.
+
+1. **Back up local data.** Before starting the migration, create a backup of the existing local data.
+2. **Query and migrate local data.** Query all existing data from the current local store. Depending on the structure of your data, you may need to transform or reformat the data to fit the schema of your new local storage solution.
+3. **Map data.** Carefully map the data from your existing store to your new solution, ensuring that all fields and relationships are preserved.
@@ -4,11 +4,14 @@ export const meta = {
   title: 'Disable conflict resolution',
   description: 'Disable AppSync conflict resolution and prepare your backend for migration from DataStore to a standard GraphQL client with zero downtime.',
   platforms: [
+    'android',
     'angular',
+    'flutter',
     'javascript',
     'nextjs',
     'react',
     'react-native',
+    'swift',
     'vue'
   ]
 };
@@ -28,7 +31,7 @@ export function getStaticProps(context) {
 
 <Callout warning>
 
-**Complete the frontend migration first.** This page covers the **final backend step** of the migration. Before following these instructions, migrate all frontend clients from DataStore to Apollo Client (or the Amplify API category) using the preceding pages in this guide. Disabling conflict resolution while any client still uses DataStore will break that client immediately.
+**Complete the frontend migration first.** This page covers the **final backend step** of the migration. Before following these instructions, migrate all frontend clients from DataStore using the preceding pages in this guide. Disabling conflict resolution while any client still uses DataStore will break that client immediately.
 
 </Callout>
 

@@ -0,0 +1,131 @@
+import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
+
+export const meta = {
+  title: 'Helpful resources',
+  description: 'Additional documentation, third-party packages, and references for the DataStore migration.',
+  platforms: [
+    'android',
+    'flutter',
+    'swift'
+  ]
+};
+
+export const getStaticPaths = async () => {
+  return getCustomStaticPath(meta.platforms);
+};
+
+export function getStaticProps(context) {
+  return {
+    props: {
+      platform: context.params.platform,
+      meta
+    }
+  };
+}
+
+<InlineFilter filters={["flutter"]}>
+
+## Amplify API
+
+- [Amplify API Category — GraphQL](https://docs.amplify.aws/gen1/flutter/build-a-backend/graphqlapi/)
+- [Amplify API — Mutate Data](https://docs.amplify.aws/gen1/flutter/build-a-backend/graphqlapi/mutate-data/)
+- [Amplify API — Query Data](https://docs.amplify.aws/gen1/flutter/build-a-backend/graphqlapi/query-data/)
+- [Amplify API — Subscribe to Data](https://docs.amplify.aws/gen1/flutter/build-a-backend/graphqlapi/subscribe-data/)
+
+## AWS AppSync
+
+- [Conflict detection and resolution](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)
+
+## Amplify DataStore (Legacy)
+
+- [How DataStore works](https://docs.amplify.aws/gen1/flutter/build-a-backend/more-features/datastore/how-it-works/)
+- [Schema updates](https://docs.amplify.aws/gen1/flutter/build-a-backend/more-features/datastore/schema-updates/)
+
+## General
+
+- [Android Offline First Guide](https://developer.android.com/topic/architecture/data-layer/offline-first)
+- [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
+
+## Local storage packages
+
+While migrating off of DataStore, we found a few third-party packages to share. We do not maintain any of these packages and our experiences are limited to the versions we tested on.
+
+| Feature | [isar-community](https://pub.dev/packages/isar_community) | [Drift](https://pub.dev/packages/drift) | [sqlite3](https://pub.dev/packages/sqlite3) |
+|---|---|---|---|
+| Model Schemas | ✅ | ✅ | ✅ |
+| Nested Models | ✅ | ✅ | ✅ |
+| Custom Primary Key | ✅ | ✅ | ✅ |
+| CRUD | ✅ | ✅ | ✅ |
+| Query Predicates | ✅ | [Have to use where()](https://drift.simonbinder.eu/docs/dart-api/select/#where) | ✅ |
+| Observe/ObserveQuery | ✅ | ✅ | [Via `updates` stream](https://pub.dev/documentation/sqlite3/latest/common/CommonDatabase/updates.html) |
+
+<Callout>
+
+Isar does not support Gradle 8, which is a requirement for Amplify Flutter Android, but there is a [fork](https://github.com/isar/isar/issues/1470#issuecomment-1978766200) that resolves this. Drift is used with the Amplify Flutter packages, which can result in restrictions for what Drift versions you can use.
+
+</Callout>
+
+</InlineFilter>
+
+<InlineFilter filters={["swift"]}>
+
+## AWS AppSync
+
+- [AWS AppSync Apollo Extensions documentation (Swift)](https://docs.amplify.aws/swift/build-a-backend/data/aws-appsync-apollo-extensions/)
+- [AWS AppSync Apollo Extensions GitHub repository](https://github.com/aws-amplify/aws-appsync-apollo-extensions-swift)
+- [AWS AppSync Delta Sync guide](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-delta-sync.html)
+- [Conflict detection and resolution](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)
+
+## Apollo iOS
+
+- [Apollo iOS documentation](https://www.apollographql.com/docs/ios)
+- [Apollo iOS Getting Started](https://www.apollographql.com/docs/ios/get-started)
+- [Apollo iOS GitHub repository](https://github.com/apollographql/apollo-ios)
+- [Apollo iOS Normalized Cache](https://www.apollographql.com/docs/ios/caching/introduction)
+- [Apollo iOS Watching Queries](https://www.apollographql.com/docs/ios/fetching/queries#watching-queries)
+
+## Amplify DataStore (Legacy)
+
+- [How DataStore works](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/datastore/how-it-works/)
+- [Schema updates](https://docs.amplify.aws/gen1/swift/build-a-backend/more-features/datastore/schema-updates/)
+- [Client code generation (Amplify CLI)](https://docs.amplify.aws/gen1/swift/tools/cli-legacy/client-codegen/)
+
+## Local storage frameworks
+
+- [SwiftData documentation](https://developer.apple.com/documentation/swiftdata/)
+- [CoreData documentation](https://developer.apple.com/documentation/coredata)
+
+</InlineFilter>
+
+<InlineFilter filters={["android"]}>
+
+## Android
+
+- [Android Offline First Guide](https://developer.android.com/topic/architecture/data-layer/offline-first)
+
+## AWS AppSync
+
+- [AWS AppSync Apollo Extensions documentation](https://docs.amplify.aws/android/build-a-backend/data/aws-appsync-apollo-extensions/)
+- [AWS AppSync Delta Sync guide](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-delta-sync.html)
+- [Conflict detection and resolution](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)
+
+## Apollo Kotlin
+
+- [Apollo Kotlin documentation](https://www.apollographql.com/docs/kotlin)
+- [Apollo Kotlin Getting Started](https://www.apollographql.com/docs/kotlin#getting-started)
+- [Apollo Kotlin Gradle Plugin configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration)
+- [Apollo Kotlin Normalized Cache](https://www.apollographql.com/docs/kotlin/caching/normalized-cache)
+- [Apollo Kotlin Query Watchers](https://www.apollographql.com/docs/kotlin/caching/query-watchers)
+
+## Amplify DataStore (Legacy)
+
+- [How DataStore works](https://docs.amplify.aws/gen1/android/build-a-backend/more-features/datastore/how-it-works/)
+- [Schema updates](https://docs.amplify.aws/gen1/android/build-a-backend/more-features/datastore/schema-updates/)
+- [Client code generation (Amplify CLI)](https://docs.amplify.aws/gen1/android/tools/cli-legacy/client-codegen/)
+
+## Local storage libraries
+
+- [Room (Android)](https://developer.android.com/training/data-storage/room)
+- [SQLDelight](https://sqldelight.github.io/sqldelight)
+
+</InlineFilter>