In this module, you provision an Amazon Aurora Serverless database and learn how to use the Data API for fast access via HTTPS.
Time to Complete Module: 20 Minutes
Amazon Aurora Serverless is a configuration for Amazon Aurora that offers on-demand automatic scaling capabilities. Amazon Aurora Serverless automatically increases capacity as your database load increases, and you can configure it to shut down entirely during times of low usage, such as overnight.
Amazon Aurora Serverless has a feature called the Data API which allows you to query your database via HTTP rather than the persistent TCP connection that is typically used for relational databases. This makes it easier to access your database from managed services, such as AWS Lambda or AWS AppSync.
In the following steps, you first provision an Amazon Aurora Serverless database. Then, you save your database credentials in AWS Secrets Manager as required for Data API usage. Finally, you learn how to connect to the Data API with the AWS SDK for JavaScript in Node.js.
-
Step 1. Provision an Amazon Aurora Serverless database
Go to the RDS section in the AWS Management Console and choose Create database.
(Click to enlarge)
In the Choose a database creation method box, choose Standard Create.
(Click to enlarge)
In the Engine options box, for Engine type, choose Amazon Aurora.
For Edition, choose Amazon Aurora with MySQL compatibility.
(Click to enlarge)
In the Database features box, choose Serverless. This option enables you to use the Data API.
(Click to enlarge)
In the Settings box, change the database name to leaderboard.
Then, enter a password and confirm the password in the respective boxes. Make sure to save this password because you need it to connect to your database.
(Click to enlarge)
The Capacity Settings box sets the configuration for how far your Amazon Aurora Serverless instance scales up and down. By default, it is configured to scale up to maximum capacity. Since you are just testing, set the maximum value to 1 capacity unit to limit any potential charges.
(Click to enlarge)
In the Connectivity box, choose Additional connectivity configuration, and then select the Data API check box.
(Click to enlarge)
Finally, choose Additional configuration, and for Initial database name, type leaderboard. Then, clear the Enable deletion protection check box. Clearing this option makes it easier to clean up your database at the end of this lab. However, in production environments, keep delection protection enabled to prevent accidental loss of your database.
(Click to enlarge)
You're ready to create your database! Choose Create database to begin provisioning your database.
While your database is provisioning, you can store your database credentials in AWS Secrets Manager.
(Click to enlarge)
-
Step 2. Store your database credentials in AWS Secrets Manager
When using the Data API with Amazon Aurora Serverless, your database credentials are stored in AWS Secrets Manager. AWS Secrets Manager is a fully managed service to easily manage your application secrets.
To get started, navigate to the Secrets Manager section of your AWS Management Console and choose Store a new secret.
In the Select secret type box, choose Credentials for RDS database. Then, type the user name and password that you used when creating your database.
(Click to enlarge)
In the Select which RDS database this secret will access section, choose the leaderboard database that you created, and then choose Next.
(Click to enlarge)
In the Secret name and description section, give your secret a name and description so that you can easily find it later. Then, choose Next.
(Click to enlarge)
AWS Secrets Manager allows you to configure automatic secret rotation for your secrets. This is a smart, easy way to enhance the security of your application. For more information, see Rotating Your AWS Secrets Manager Secrets.
Setting up secret rotation is outside the scope of this tutorial, so choose the Disable automatic rotation option, and then choose Next.
(Click to enlarge)
The Secrets Manager console shows you the configuration settings for your secret and some sample code that demonstrates how to use your secret. Scroll to the bottom of the page and choose Store to save your secret.
After creating the secret, the Secrets Manager page displays your created secrets. Choose your leaderboard-database secret.
In the Secret details box, it displays the ARN of your secret. Copy this value, as you need it later in this tutorial.
(Click to enlarge)
In this step, you saved your database credentials to AWS Secrets Manager. In the next step, you learn how to use your stored secret to access your database with the Data API.
-
Step 3. Connect to your database with the Data API
Now that you have your database provisioned and secrets stored, let’s try accessing your database with the Data API.
First, you need to get the ARNs of your resources. Navigate to the RDS section of the AWS Management Console, choose Databases, and then choose your leaderboard database.
Choose the Configuration tab and then copy the ARN value for your database.
(Click to enlarge)
At this point, you should have your Database ARN from the previous instructions and your Secret ARN from the end of Step 2. You use these values to access your database.
Navigate to the terminal in your AWS Cloud9 instance. Enter the following commands to set your ARN values as environment variables.
Be sure to substitute your ARN values for yourDatabaseArn and yourSecretArn.
echo "export DATABASE_ARN=<yourDatabaseArn>" >> env.sh echo "export SECRET_ARN=<yourSecretArn>" >> env.sh source env.sh
In the scripts/ directory, there is a testDatabase.js file that you can use to test your connection. The contents of that file are as follows:
const AWS = require('aws-sdk') const rdsdataservice = new AWS.RDSDataService(); const params = { resourceArn: process.env.DATABASE_ARN, secretArn: process.env.SECRET_ARN, database: ‘leaderboard’, sql: 'SELECT 1' } rdsdataservice.executeStatement(params, function(err, data) { if (err) { console.log(err, err.stack) } else { console.log(JSON.stringify(data, null, 2)) } })In this script, you construct an RDSDataService client from the AWS SDK. Then, you set up the method parameters, including the resourceArn, our secretArn, the database, and the SQL you want to execute. This example uses a simple SQL statement of SELECT 1 just to show you can connect.
Run the script in your AWS Cloud9 terminal with the following command:
node scripts/testDatabase.js
You should see the following output in your terminal:
{ "numberOfRecordsUpdated": 0, "records": [ [ { "longValue": 1 } ] ] }Success! You received the value of 1 in your only returned record. This shows you were able to connect to your database successfully.
Note: If an error message appears stating BadRequestException: FATAL: password authentication failed for user, it may indicate that you configured your AWS Secrets Manager secret incorrectly. Return to the Secrets Manager console and confirm the user name and password you entered.
In this module, you provisioned your Amazon Aurora Serverless database. Additionally, you saved your database credentials to AWS Secrets Manager for use with the Data API. Finally, you ensured you were able to connect to your database with the Data API.
In the next module, you plan your data model for your application, use the Data API to create your tables, and load some sample data.