DataStore

Getting started

DataStore with Amplify

Amplify DataStore provides a programming model for leveraging shared and distributed data without writing additional code for offline and online scenarios, which makes working with distributed, cross-user data just as simple as working with local-only data.

Note: this allows you to start persisting data locally to your device with DataStore, even without an AWS account.

Goal

To setup and configure your application with Amplify DataStore and use it to persist data locally on a device.

Prerequisites

  • Install Amplify CLI version 4.21.0 or later by running:

npm install -g @aws-amplify/cli

npm install -g @aws-amplify/cli

Note: Because we’re installing the Amplify CLI globally, you might need to run the command above with sudo depending on your system policies.

curl -sL https://aws-amplify.github.io/amplify-cli/install | bash && $SHELL

curl -sL https://aws-amplify.github.io/amplify-cli/install | bash && $SHELL

curl -sL https://aws-amplify.github.io/amplify-cli/install-win -o install.cmd && install.cmd

curl -sL https://aws-amplify.github.io/amplify-cli/install-win -o install.cmd && install.cmd

Setup local development environment

In order to setup your local development environment, you have two options.

Option 1: Platform integration

The fastest way to get started is using the amplify-app npx script.


Start with Create React app:

npx create-react-app amplify-datastore --use-npm cd amplify-datastore npx amplify-app@latest

npx create-react-app amplify-datastore --use-npm cd amplify-datastore npx amplify-app@latest

Start with the React Native CLI:

npx react-native init AmplifyDataStoreRN cd AmplifyDataStoreRN npx amplify-app@latest npm install @react-native-community/netinfo @react-native-async-storage/async-storage

npx react-native init AmplifyDataStoreRN cd AmplifyDataStoreRN npx amplify-app@latest npm install @react-native-community/netinfo @react-native-async-storage/async-storage

You will also need to install the pod dependencies for iOS:

npx pod-install

npx pod-install

Option 2: Use Amplify CLI

Instead of using the platform integration, you can alternatively use the Amplify CLI on its own. This option is particularly useful for existing projects where Amplify is already configured and you want to add DataStore to it.

To use Amplify, you must first initialize it for use in your project. If you haven’t already done so, run this command:

amplify init

amplify init

The base structure for a DataStore app is created by adding a new GraphQL API to your app.

# For new APIs amplify add api # For existing APIs amplify update api

# For new APIs amplify add api # For existing APIs amplify update api

The CLI will prompt you to configure your API. Select GraphQL as the API type and reply to the questions as shown below. When prompted to configure advanced settings, respond Yes, I want to make some additional changes, and ensure that conflict detection is enabled. Conflict detection is required when using the DataStore to sync data with the cloud.

? Please select from one of the below mentioned services: `GraphQL` ? Provide API name: `BlogAppApi` ? Choose the default authorization type for the API `API key` ? Enter a description for the API key: `BlogAPIKey` ? After how many days from now the API key should expire (1-365): `365` ? Do you want to configure advanced settings for the GraphQL API `Yes, I want to make some additional changes.` ? Configure additional auth types? `No` ? Enable conflict detection? `Yes` ? Select the default resolution strategy `Auto Merge` ? Do you have an annotated GraphQL schema? `No` ? Choose a schema template `Single object with fields (e.g., “Todo” with ID, name, description)`

? Please select from one of the below mentioned services: `GraphQL` ? Provide API name: `BlogAppApi` ? Choose the default authorization type for the API `API key` ? Enter a description for the API key: `BlogAPIKey` ? After how many days from now the API key should expire (1-365): `365` ? Do you want to configure advanced settings for the GraphQL API `Yes, I want to make some additional changes.` ? Configure additional auth types? `No` ? Enable conflict detection? `Yes` ? Select the default resolution strategy `Auto Merge` ? Do you have an annotated GraphQL schema? `No` ? Choose a schema template `Single object with fields (e.g., “Todo” with ID, name, description)`

Troubleshooting: Cloud sync will fail without the conflict detection configuration. To enable it for an existing project, run amplify update api and choose Enable DataStore for entire API.

Idiomatic persistence

DataStore relies on platform standard data structures to represent the data schema in an idiomatic way. The persistence language is composed by data types that satisfies the Model interface and operations defined by common verbs such as save, query and delete.

Data schema

The first step to create an app backed by a persistent datastore is to define a schema. DataStore uses GraphQL schema files as the definition of the application data model. The schema contains data types and relationships that represent the app’s functionality.

Sample schema

For the next steps, let’s start with a schema for a small blog application. Currently, it has only a single model. New types and constructs will be added to this base schema as more concepts are presented.

Open the schema.graphql file located by default at amplify/backend/{api_name}/ and define a model Post as follows.

type Post @model { id: ID! title: String! status: PostStatus! rating: Int content: String } enum PostStatus { DRAFT PUBLISHED }

type Post @model { id: ID! title: String! status: PostStatus! rating: Int content: String } enum PostStatus { DRAFT PUBLISHED }

Now you will to convert the platform-agnostic schema.graphql into platform-specific data structures. DataStore relies on code generation to guarantee schemas are correctly converted to platform code.

Like the initial setup, models can be generated either using the IDE integration or Amplify CLI directly.

Code generation: Platform integration

When using npx amplify-app a NPM script named amplify-modelgen should be added to you package.json. You can generate model code with the following command.

npm run amplify-modelgen

npm run amplify-modelgen

The following files will be generated.

src/ |_ models/ |_ index.d.ts |_ index.js |_ schema.d.ts |_ schema.js

src/ |_ models/ |_ index.d.ts |_ index.js |_ schema.d.ts |_ schema.js

The .d.ts are TypeScript declaration files. If your project does not use TypeScript, do not worry, those files can still provide most editors a better developer experience, with a more accurate auto-complete and realtime type checking. Worst case scenario they will just be ignored.

Code generation: Amplify CLI

Models can also be generated using the Amplify CLI directly.

In your terminal, make sure you are in your project/root folder and execute the codegen command:

amplify codegen models

amplify codegen models

You can find the generated files at amplify/generated/models/.

Initialize Amplify DataStore

When the @aws-amplify/datastore dependency is added to the project, the plugin is automatic initialized when you start using.

Persistence operations

Now the application is ready to execute persistence operations. The data will be persisted to a local database, enabling offline-first use cases by default.

Even though a GraphQL API is already added to your project, the cloud synchronization will only be enabled when the API plugin is initialized and the backend provisioned. See the Next steps for more info.

Writing to the database

To write to the database, create an instance of the Post model and save it.

try { await DataStore.save( new Post({ title: "My First Post" }) ); console.log("Post saved successfully!"); } catch (error) { console.log("Error saving post", error); }

try { await DataStore.save( new Post({ title: "My First Post" }) ); console.log("Post saved successfully!"); } catch (error) { console.log("Error saving post", error); }

Reading from the database

To read from the database, the simplest approach is to query for all records of a given model type.

try { const posts = await DataStore.query(Post); console.log("Posts retrieved successfully!", JSON.stringify(posts, null, 2)); } catch (error) { console.log("Error retrieving posts", error); }

try { const posts = await DataStore.query(Post); console.log("Posts retrieved successfully!", JSON.stringify(posts, null, 2)); } catch (error) { console.log("Error retrieving posts", error); }

Next steps

Congratulations! You’ve created and retrieved data from the local database. Check out the following links to see other Amplify DataStore use cases and advanced concepts:

next

Manipulating data

Next Page
Discord Logo
Amplify open source, documentation and community are supported by Amazon Web Services © 2021, Amazon Web Services, Inc. and its affiliates. All rights reserved. View the site terms and privacy policy.
    Flutter and the related logo are trademarks of Google LLC. We are not endorsed by or affiliated with Google LLC.