Relational Database Service (RDS)

Relational Database Service (RDS)

LocalStack supports a basic version of the Relational Database Service (RDS) for testing.

Supported DB engines

Currently, it is possible to spin up PostgreSQL, MySQL, and MSSQL (SQL Server) databases on the local machine.

Note

In order to use MSSQL databases, you need to explicitly accept the Microsoft SQL Server End-User Licensing Agreement (EULA) by setting MSSQL_ACCEPT_EULA=Y in the LocalStack container environment.

Postgres versions

When creating an RDS DB cluster or instance with postgres/aurora-postgresql DB engine, by default Postgres version 11 is used. In order to use custom versions, make sure to configure the environment variable RDS_PG_CUSTOM_VERSIONS=1, which then causes LocalStack to install and start up the respective Postgres version on demand. Currently, versions 11/12/13 can be installed - when selecting a major version outside of this range, the default version 11 is used as fallback.

End-to-end example (Postgres)

The local RDS service also supports the RDS Data API, which allows executing data queries against RDS clusters over a JSON/REST interface. Below is a simple example that illustrates (1) creation of an RDS cluster, (2) creation of a SecretsManager secret with the DB password, and (3) running a simple SELECT 123 query via the RDS Data API.

  1. $ awslocal rds create-db-cluster --db-cluster-identifier db1 --engine aurora-postgresql --database-name test
  2. {
  3.     "DBCluster": {
  4.         ...
  5.         "Endpoint": "localhost:4510",
  6.         "Port": 4510,  # may vary
  7.         "DBClusterArn": "arn:aws:rds:us-east-1:000000000000:cluster:db1",
  8.         ...
  9.     }
  10. }
  13. $ awslocal secretsmanager create-secret --name dbpass --secret-string test
  14. {
  15.     "ARN": "arn:aws:secretsmanager:eu-central-1:1234567890:secret:dbpass-cfnAX",
  16.     "Name": "dbpass",
  17.     "VersionId": "fffa1f4a-2381-4a2b-a977-4869d59a16c0"
  18. }
  20. $ awslocal rds-data execute-statement --database test --resource-arn arn:aws:rds:us-east-1:000000000000:cluster:db1 --secret-arn arn:aws:secretsmanager:eu-central-1:1234567890:secret:dbpass-cfnAX --include-result-metadata --sql 'SELECT 123'
  21. {
  22.     "columnMetadata": [
  23.         {
  24.             "arrayBaseColumnType": 0,
  25.             "isAutoIncrement": false,
  26.             "isCaseSensitive": false,
  27.             "isCurrency": false,
  28.             "isSigned": true,
  29.             "label": "?column?",
  30.             "name": "?column?",
  31.             "nullable": 0,
  32.             "precision": 10,
  33.             "scale": 0,
  34.             "schemaName": "",
  35.             "tableName": "",
  36.             "type": 4,
  37.             "typeName": "int4"
  38.         }
  39.     ],
  40.     "numberOfRecordsUpdated": 0,
  41.     "records": [
  42.         [
  43.             {
  44.                 "longValue": 123
  45.             }
  46.         ]
  47.     ]
  48. }

You can also use other clients like psql to interact with the database. The hostname and port of your created instance can be found in the output from above or by running awslocal rds describe-db-instances.

  1. $ psql -d test -U test -p 4513 -h localhost -W
  2. Password: <enter "test">

Default usernames and passwords

Please consider the following notes regarding default usernames/passwords and database names:

  • The default for master-username and db-name is “test”. The default master-user-password is “test” - except for MSSQL DBs, which uses “Test123!” as the default master password.
  • You can use any master-username, except “postgres”, for creating a new RDS instance. The user will automatically be created.
  • The user “postgres” is special, and it is not possible to create a new RDS instance with this user name.
  • Do not use db-name “postgres” as it is already in use by LocalStack.

Last modified July 21, 2022: add notes around custom Postgres versions and RDS_PG_CUSTOM_VERSIONS (#210) (09f508d1)