Relational Database Service (RDS)
Get started with Relational Database Service (RDS) on LocalStack
Introduction
RDS (Relational Database Service) is a managed database service provided by Amazon Web Services (AWS) that allows users to setup, operate, and scale relational databases in the cloud. RDS allows you to deploy and manage various relational database engines like MySQL, PostgreSQL, MariaDB, and Microsoft SQL Server. RDS handles routine database tasks such as provisioning, patching, backup, recovery, and scaling.
LocalStack supports RDS via the Pro/Team offering, allowing you to use the RDS APIs in your local environment to create and manage RDS clusters and instances for testing & integration purposes. The supported APIs are available on our API coverage page, which provides information on the extent of RDS’s integration with LocalStack.
Getting started
This guide is designed for users new to RDS and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.
Start your LocalStack container using your preferred method. We will demonstrate the following with the AWS CLI:
- Creating an RDS cluster.
- Generating a
SecretsManager secret containing the database password. - Executing a basic
SELECT 123 query through the RDS Data API.
LocalStack’s RDS implementation also supports the RDS Data API, which allows executing data queries against RDS clusters over a JSON/REST interface.
Create an RDS cluster
Note
The Endpoint for cluster on Localstack currently follows the pattern <host>:<port> for legacy reasons, which is not in parity in AWS.
+To force the correct pattern (e.g. returning only the host for the Endpoint) you can use the configuration RDS_CLUSTER_ENDPOINT_HOST_ONLY=1 to start LocalStack.To create an RDS cluster, you can use the CreateDBCluster API.
The following command creates a new cluster with the name db1 and the engine aurora-postgresql.
Instances for the cluster must be added manually.
$ awslocal rds create-db-cluster \
--db-cluster-identifier db1 \
@@ -365,7 +366,7 @@
--enable-iam-database-authentication \
--db-instance-class db.t3.small
Connect to the database
You can retrieve the hostname and port of your created instance either from the preceding output or by using the DescribeDbInstances API. Run the following command to retrieve the host and port of the instance:
$ PORT=$(awslocal rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Port")
$ HOST=$(awslocal rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Address")
Next, you can connect to the database using the master username and password:
$ PGPASSWORD=$MASTER_PW psql -d $DB_NAME -U $MASTER_USER -p $PORT -h $HOST -w -c 'CREATE USER myiam WITH LOGIN'
-$ PGPASSWORD=$MASTER_PW psql -d $DB_NAME -U $MASTER_USER -p $PORT -h $HOST -w -c 'GRANT rds_iam TO myiam'
Create a token
You can create a token for the user you generated using the generate-db-auth-token command:
$ TOKEN=$(awslocal rds generate-db-auth-token --username myiam --hostname $HOST --port $PORT)
You can now connect to the database utilizing the user you generated and the token obtained in the previous step as the password:
$ PGPASSWORD=$TOKEN psql -d $DB_NAME -U myiam -w -p $PORT -h $HOST
Global Database Support
LocalStack extends support for Aurora Global Database with certain limitations:
- Creating a global database will result in the generation of a single local database. All clusters and instances associated with the global database will share a common endpoint.
- It’s important to note that clusters removed from a global database lose their ability to function as standalone clusters, differing from their intended behavior on AWS.
- At present, the capability for persistence within global databases is not available.
Resource Browser
The LocalStack Web Application provides a Resource Browser for managing RDS instances and clusters. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the Resources section, and then clicking on RDS under the Database section.
The Resource Browser allows you to perform the following actions:
- Create Instance: Create a new RDS instance by specifying the instance name, engine, DBInstance Class & Identifier, and other parameters.
- Create Cluster: Create a new RDS cluster by specifying the database name, engine, DBCluster Identifier, and other parameters.
- View Instance & Cluster: View an existing RDS instance or cluster by clicking the instance/cluster name.
- Edit Instance & Cluster: Edit an existing RDS instance or cluster by clicking the instance/cluster name and clicking the EDIT INSTANCE or EDIT CLUSTER button.
- Remove Instance & Cluster: Remove an existing RDS instance or cluster by clicking the instance/cluster name and clicking the ACTIONS followed by Remove Selected button.
Examples
The following code snippets and sample applications provide practical examples of how to use RDS in LocalStack for various use cases: