Migrate from DataStore

Understanding DataStore

AWS Amplify DataStore provided a local-first data layer that automatically synchronized data between your app and the cloud. When you used DataStore, you got several powerful capabilities without writing any synchronization logic yourself: a local database that persisted data across sessions, automatic bidirectional sync with your AppSync backend, built-in conflict resolution using version tracking, full offline support with mutation queuing and replay, and real-time updates through observe() and observeQuery().

DataStore abstracted away the complexity of GraphQL operations, network state management, and data consistency. You worked with simple save, query, and delete methods on local models, and DataStore handled everything else behind the scenes.

This guide shows you how to migrate from DataStore to the Amplify API category for queries, mutations, and subscriptions. Depending on how much of DataStore's feature set your app actually uses, you may find the migration simpler than expected.

Once frontend clients have been migrated off DataStore, disable conflict resolution on the backend to remove the sync infrastructure, simplify mutations (no more _version tracking), and switch from soft deletes to hard deletes.

What this guide covers

This guide walks you through the migration path from DataStore to the Amplify API category. You will replace DataStore operations with API equivalents, and optionally add local caching and offline-first support using third-party Flutter packages.

Quick comparison: before and after

Here is a quick look at how common DataStore operations translate to the Amplify API category:

DataStore Operation	Amplify API Equivalent
`Amplify.DataStore.save()` (create)	`Amplify.API.mutate(request: ModelMutations.create(...))`
`Amplify.DataStore.save()` (update)	`Amplify.API.mutate(request: ModelMutations.update(...))`
`Amplify.DataStore.delete()`	`Amplify.API.mutate(request: ModelMutations.delete(...))`
`Amplify.DataStore.query()` (single)	`Amplify.API.query(request: ModelQueries.get(...))`
`Amplify.DataStore.query()` (list)	`Amplify.API.query(request: ModelQueries.list(...))`
`Amplify.DataStore.observe()`	`Amplify.API.subscribe(ModelSubscriptions.onCreate/onUpdate/onDelete(...))`
`Amplify.DataStore.observeQuery()`	Initial `ModelQueries.list()` + three subscriptions (no direct equivalent)
`Amplify.DataStore.clear()`	No longer needed (no local DataStore to clear)
`Amplify.DataStore.start()` / `stop()`	No longer needed

Use cases

Not all customers need the full extent of DataStore's capabilities. Depending on your specific use case, migration can be straightforward:

Ease of API: If your main reason for using DataStore was to simplify managing GraphQL queries or APIs, and your application does not need offline or local caching, migrate to the Amplify API category. This allows you to continue working with a simplified data management interface while consuming your existing Amplify resources.
Local caching: If you used DataStore primarily as a local caching layer, storing data temporarily on the device but not relying heavily on its offline-first capabilities, consider migrating to a simpler local caching solution using third-party Flutter packages.
Offline-first: If your business requirements rely on fully supporting offline-first functionality, the offline-first guide provides a high-level approach for migrating to a new offline-first solution.

How to use this guide

Follow the pages in order. Each step builds on the previous one.

Remove DataStore. Remove the DataStore dependency from your project and configure the API plugin to use your models.
Migrate to Amplify API. Replace all DataStore operations with API equivalents. Migrate save, query, delete, observe, and observeQuery.
Optional: Local caching. Set up a local cache for offline data access using third-party Flutter packages.
Offline-first. Build full offline support with remote sync, live syncing, network detection, and offline mutations.
Authorization and data handling. Manage auth rules and handle existing customer data during migration.
Disable conflict resolution. Once ALL frontend clients are migrated off DataStore, remove the sync infrastructure, simplify mutations, and switch from soft deletes to hard deletes.
Helpful resources. Additional documentation, third-party packages, and references.

Migration checklist

Use this checklist to plan and track your migration:

Update pubspec.yaml — Remove the amplify_datastore dependency (see Remove DataStore)
Update Amplify configuration — Remove the DataStore plugin and pass ModelProvider to the API plugin
Migrate CRUD operations — Replace DataStore.save(), DataStore.query(), and DataStore.delete() with API equivalents (see Migrate to Amplify API)
Migrate real-time listeners — Replace DataStore.observe() and DataStore.observeQuery() with API subscriptions
Handle API response differences — Adapt to GraphQLResponse types and token-based pagination
Test — Verify all CRUD operations, real-time subscriptions, and error handling
Disable conflict resolution — Once all clients are migrated (see Disable conflict resolution)

Remove DataStore

Remove Amplify DataStore from your project and prepare for migration to the Amplify API category or Apollo Kotlin.

Migrate to Amplify API

Replace DataStore save, query, delete, observe, and observeQuery with Amplify API equivalents for Flutter.

Optional: Local caching

Set up local caching as an alternative to DataStore local storage for Flutter and Android.

Offline-first

Build full offline support with remote sync, live syncing, network detection, and offline mutations.

Authorization and data handling

Manage authorization rules and handle existing customer data during the migration from DataStore to Amplify API for Flutter.

Disable conflict resolution

Disable AppSync conflict resolution and prepare your backend for migration from DataStore to a standard GraphQL client with zero downtime.

Helpful resources

Additional documentation, third-party packages, and references for the DataStore migration.