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 Apollo Kotlin and the AWS AppSync Apollo Extensions library 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 Apollo Kotlin. You will set up Apollo Kotlin with your AppSync endpoint, migrate all CRUD operations, and optionally add local caching and offline-first support.

Quick comparison: before and after

Here is a quick look at how common DataStore operations translate to Apollo Kotlin:

Use cases

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

1. 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, Apollo Kotlin can provide lightweight data caching without the complexities of managing full offline sync, making it a good fit if your application is mostly connected and only occasionally requires offline access.
2. 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.

1. Remove DataStore. Remove the DataStore dependency and plugin from your project.

2. Schema and GraphQL operations. Retrieve your AppSync schema and define your GraphQL operations for Apollo code generation.

3. Set up Apollo Kotlin. Add dependencies, configure the Gradle plugin, and set up the Apollo client with your AppSync endpoint and authentication.

4. Migrate DataStore to Apollo. Replace all DataStore operations with Apollo equivalents. Migrate save, query, delete, observe, and observeQuery.

5. Optional: Local caching. Set up a local cache using Apollo's normalized cache or a custom caching layer with Room.

6. Offline-first. Build full offline support with remote sync, live syncing, network detection, and offline mutations.

7. 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.

8. Helpful resources. Additional documentation, third-party packages, and references.

Migration checklist

Use this checklist to plan and track your migration:

1. Remove the DataStore dependency — Remove com.amplifyframework:aws-datastore from your build.gradle.kts (see Remove DataStore)
2. Remove the DataStore plugin — Remove AWSDataStorePlugin() from your Amplify.addPlugin() calls
3. Delete generated model files — Remove DataStore-generated model classes
4. Set up schema and operations — Retrieve your AppSync schema and define GraphQL operations (see Schema and GraphQL operations)
5. Set up Apollo Kotlin — Add dependencies and configure the Apollo client (see Set up Apollo Kotlin)
6. Migrate CRUD operations — Replace DataStore.save(), DataStore.query(), and DataStore.delete() with Apollo equivalents (see Migrate DataStore to Apollo)
7. Migrate real-time listeners — Replace DataStore.observe() and DataStore.observeQuery() with Apollo subscriptions and cache watchers
8. Test — Verify all CRUD operations, real-time subscriptions, and error handling
9. Disable conflict resolution — Once all clients are migrated (see Disable conflict resolution)