Applications across the globe access performant databases that scale and process data based on schemas. Amazon Web Services (AWS) provides a unique and accessible database solution through Amplify, called DataStore.
Accessing create, update, delete, and query methods for connecting to your cloud database is simplified through REST APIs with multi-language support. Following repeatable and programmatic steps, you can connect applications with databases around the globe.
Amazon Web Services (AWS) has various methods of documentation for this process, which I will illuminate to provide further explanation of downstream choices.
https://aws.amazon.com/amplify/
Installing the Amplify CLI
To begin integrating, there are a few preliminary steps to create a stage for Amplify & DataStore on your local machine. First is installing the Command Line Interface (CLI) for accessing Amplify from your terminal.
In your terminal, paste and enter the below snippet to install the CLI.
npm install -g @aws-amplify/cliIf there are issues installing the CLI or any of the following packages, you can run these commands with the sudo prefix; to enable root permissions for the command line in the terminal. NPM has a guide for EACCES permissions as well.
Setting up Amplify & DataStore packages in React
Create an Amplify DataStore application with the create-react-app template, which will be used for accessing DataStore within the JavaScript SDK. Navigate to a folder where you often store local applications, such as documents, you can do this in the terminal with cd documents .
In your terminal, paste and enter the below snippet to create a React application from the create-react-app template.
npx create-react-app my-appAfter the NPX tool runs and processes the package binaries, you will now implement Amplify within the newly created application. Change directories to the recently created React application directory, with cd my-app. In your terminal, paste and enter the below snippet to implement Amplify within your React application.
In your terminal, paste and enter the below snippet to implement Amplify within your React application.
npx amplify-app@latestOnce the amplify packages are processed into your newly created application, you can begin the process of implementing Amplify services, after they are setup, and their respective packages are installed.
In your terminal, paste and enter the below snippet to install the required packages for implementing Amplify & DataStore.
npm install aws-amplify @aws-amplify/datastoreGenerating IAM users, groups, and access keys
Identity and Access Management (IAM) Users allow for authorization-based control over resources through configured access policies, that can be set and removed within AWS console.
Users generated with IAM access can also be organized into IAM Groups, where larger Groups of Users can access resources through a shared policy that is applied at a group level.
Access keys are a universal method of authorization for accessing AWS services. Keys can be used for short term, long term, and rotational purposes in managing the connection between your cloud resources and applications. These keys are attached to a user and can provide authorization to a IAM User and their groups resource policies.
To start creating an IAM User you can access the IAM service within AWS. In the left navigation bar, under “Access management”, choose users, on the users page in the top navigation, click the button “Add users”.
On the “Specify user details” page, enter a “User name” for example AmplifyUserand then select next.
For the user’s permissions on the “Set permissions” page, select the “Add user to group” option and in the secondary “User groups” navigation bar, click the button, “Create group”.
For the field “User group name”, enter a group name, for example AmplifyGroup , then click the button “Create user group”.
It is recommended to separate users, groups, and limit their access policies to only the minimally required permissions.
As this use-case represents the Amplify user connected to your Amplify enabled application, you need to add your user to your newly created group for Amplify.
Select your recently created Amplify group name on the “Set permissions” step, then click “Next”, to proceed in creating the user. On the next page “Review and create”, click “Create user”, this will create the AmplifyUser within the AmplifyGroup. Now that there is an Amplify Group and Amplify User in that group, go to the “Users group” page and select the tab titled “Permissions”.
In the drop-down menu labeled “Add permissions” click “Attach policies”, then in the search bar, search for AdministratorAccess-Amplify , select this policy, then click the button “Add permissions”.
Your user now has Amplify Admin access through the Amplify group, the last step is generating access for the CLI to access Amplify through the users access policies.
Again, click on “Users” in the left sidebar under “Access management”, click on the user’s name, once on the user’s IAM profile, select the “Security credentials” tab and scroll down to “Access keys”. Click the button “Create access key” to begin the access key generation process.
When the access key form appears, select “Command Line Interface (CLI)”, read and check the box, “I understand the above recommendation and want to proceed to create an access key.” and click “Next”. On the following page, click “Create access key”, then click, “Download .csv file” and then “Done”.
Save the recently generated access key .csv file for the next step in the Amplify integration process.
Establishing and deploying DataStore schemas
Amplify’s DataStore uses models to provide GraphQL and REST operations — these models are schematic references to GraphQL Mutations, Types & Schemas, and functionally create a structured Amplify schema.
To begin the process of initializing the application you can start the Amplify setup process to connect your application from your local computer to AWS and the cloud.
In your terminal, paste and enter the below snippet to initialize Amplify within your application.
amplify initThe command line will proceed with a series of questions, to finish this process answer the following questions:
Enter a name for the environment: <Project Name>
Choose your default editor: <Default Editor>
Select the authentication method you want to use: <AWS Access Keys>
accessKeyId: <accessKeyId>
secretAccessKey: <secretAccessKey>
region: <Your Cloud Region>The process should take a minute to a few to complete, while it installs the binary files and completes the setup of Amplify within your application files.
Once Amplify is implemented within the application, the schema is developed in GraphQL, this schema can be adapted and updated in your application, the file in reference is the schema.graphql file found at amplify/backend/api/amplifyDatasource/schema.graphql . You can find our more about setting up GraphQL schemas in the package’s documentation.
You can continue with the generated starter schema from Amplify and update the data models later. After your have your schema set, you can create data models in your application with an Amplify CLI command.
In your terminal, paste and enter the below snippet to generate Amplify data models within your application.
npm run amplify-modelgenOnce the models are generated and your data structure is establish you can now establish these resources in the cloud and begin building content for your application.
In your terminal, paste and enter the below snippet to deploy your data models to Amplify.
amplify pushThe command line will proceed with a series of questions, to finish this process answer the following questions:
Do you want to generate code for your newly created GraphQL API: NoOnce this process runs, your local configuration will be deployed to the cloud through the Amplify CLI and you can begin to utilize the Amplify packages with DataStore to connect to your data, through RESTful services.
Wiring up Amplify DataStore with REST in React JavaScript
Now that your Amplify data models are deployed to the cloud, you can begin writing the code to create, update, delete and query the data. In the index.js file within the src/ folder of your React application. Adding these imports, will setup the API configuration for Amplify — this will access the exported configuration downloaded when you initialized the application.
import { Amplify } from "aws-amplify";
import awsconfig from "./aws-exports";
Amplify.configure(awsconfig);https://github.com/heyitsjoealongi/react-amplify-datastore/blob/main/src/index.js
For the next step, you will need to write the function to fetch and access the data content from your data models, using async/await within a try/catch block, call the query, based on the data model generated locally from the amplify-modelgen script.
import { DataStore } from '@aws-amplify/datastore';
import { Task } from './models';
try {
const models = await DataStore.query(Task);
console.log('Models retrieved successfully!', JSON.stringify(models, null, 2));
} catch (error) {
console.log('Error retrieving posts', error);
}https://github.com/heyitsjoealongi/react-amplify-datastore/blob/main/src/App.js
You can extend these REST operations and the async function with components written in React JavaScript. You can find the example code, which was written when writing this tutorial, to see how these APIs can be used within the React lifecycle.
Populating DataStore content for application views
Amplify provides various methods for the input of data, whether your application use-case favors loading your data upfront, as you would with a Content Management System (CMS) or allowing for user-driven data, there are methods for either.
In example fashion and for development best practices, a good place to start is by creating mock data. You can create mock data with Amplify Studio. In the AWS console, go to the Amplify service, and click on the name of the application you deployed in the previous step.
Once you are on the app page, click the toggle next to “Enable Amplify Studio” to on, so that AWS partitions a studio environment. After the studio is spun up, click on the “Launch Studio” button to open the studio environment.
In the left side menu, click on “Content” under “Management” and proceed to the content page. If you kept the data model, from the example schema, generated in the Amplify setup, the top right button should say “Create task”, click the button to add a task.
In the “Create Task” modal form, enter a “Title”, “Description”, and “Status”, then click “Submit”. This form’s input generates your content — similarly to how a user’s input would generate content or as CMS would host it; which then reads the input and stores the result.
You can now start your local application with npm startor refresh the page and the query should process and log the output of the models array. In the models array you should now see, included an object with this recently created task and it’s data.
To update the data model, you can use the Amplify studio UI, deploy and follow the commands to update the local code, or update the GraphQL schema, generate the models locally, and push the new data structure from the command line.
You can find the example code for this project on GitHub, which is a combination of the Amazon Web Services (AWS) example code, Create React App, and React JavaScript code written for this blog.