Accessing Aurora DSQL Using SQL Clients With IAM Roles
Learn how to access an Aurora DSQL cluster using SQL clients with IAM role-based authentication
Yossi Lagstein
Amazon Employee
Published Jun 8, 2025
Aurora DSQL is a new AWS relational database. Amazon Aurora DSQL is a serverless, distributed database with active-active architecture. Aurora DSQL is PostgreSQL-compatible, so you can use familiar drivers and some of the tools that work with PostgreSQL.
Aurora DSQL authentication and authorization are based on IAM roles. You associate IAM roles with PostgreSQL database roles for database authorization. Cluster authentication is done with IAM using a generated temporary authentication token. In the following sections, you will see an example of how to set up an IAM role that will allow you to access an Aurora DSQL cluster and run queries on a specific schema. The walkthrough will show what needs to be done to connect to an Aurora DSQL cluster with psql and with the GUI client DBeaver. The walkthrough is based on guidance provided in Aurora DSQL workshop.
In the walkthrough you will use CloudShell. You will use two terminals as you progress.
1/ Create an Aurora DSQL cluster by following the guidance here.
2/ Open CloudShell and connect to the Aurora DSQL cluster using psql with admin user:
[update with your Aurora DSQL cluster endpoint]
[update with your Aurora DSQL cluster endpoint]
3/ Create a schema and a table:
4/ Now insert data into the table:
Open another CloudShell terminal.
1/ Open an editor and copy the below JSON policy into BasketballClusterLogin.json file:
Tip: with vi use
Tip: with vi use
:set paste setting to allow you to copy/paste JSON content. [update the JSON file with your account ID and Aurora DSQL Cluster ID]
2/ Create IAM policy BasketballClusterLogin that will allow you to connect to the cluster:
3/ Let's see what is your current session role. Copy the role ARN and save it for next steps:
4/ Open an editor and copy the below JSON trust policy into BasketballTrustPolicy.json file. The trust policy will allow your session role to assume the role that is created in the following steps:
Tip: with vi use
Tip: with vi use
:set paste setting to allow you to copy/paste JSON content. [update the JSON file with your session role arn]
5/ Create IAM role BasketballRWAccess. You will use this role later on to connect to the Aurora DSQL cluster:
6/ Attach BasketballClusterLogin policy to the BasketballRWAccess role:
[Update the command with your account ID]
[Update the command with your account ID]
1/ In the first terminal, while still connected as admin user to the database, let's create database role basketball_rw:
2/ Link the basketball_rw database role to the BasketballRWAccess IAM role you created above:
[Update the command sample with your IAM role arn]
[Update the command sample with your IAM role arn]
1/ In the second terminal, you now assume the BasketballRWAccess IAM role, and once assumed, you are getting the credentials that allow you to connect to the cluster:
[Update the command with your account ID]
[Update the command with your account ID]
2/ Now you are set to connect to the database with basketball_rw user:
[update with your cluster endpoint]
[update with your cluster endpoint]
3/ Let's run a query:
You can also connect with GUI-based tools such as DBeaver. You will need to set up credentials on a terminal from which you will launch DBeaver.
Note 1: The following steps assume that you performed all previous sections including "Connecting using a role with psql".
Note 2: The example commands have Linux syntax, the same can be done in other operating systems, including Windows.
Note 1: The following steps assume that you performed all previous sections including "Connecting using a role with psql".
Note 2: The example commands have Linux syntax, the same can be done in other operating systems, including Windows.
1/ In your second CloudShell terminal exit from psql (\q) and run the following shell command to see your credentials:
2/ To access the Aurora DSQL cluster with a role, you should take the following steps on the machine you installed the DBeaver. Open a terminal:
[Use the values you got in the previous step]
[Use the values you got in the previous step]
3/ From the terminal go to DBeaver home directory and then launch it:
4/ In your second CloudShell terminal run the following command to see your authentication token:
5/ To set up a new Aurora DSQL connection in DBeaver:
- Choose New Database Connection.
- In the New Database Connection window, choose PostgreSQL.
- In the Connection settings/Main tab, choose Connect by: Host and enter the following information.
- Host – Use your cluster endpoint.
- Database – Enter
postgres - Authentication – Choose
Database Native - Username – Enter
basketball_rw - Password – Copy the authentication token from the previous step
Open new CloudShell terminal.
1/ Delete the IAM role BasketballRWAccess:
[Update the command with your account ID]
[Update the command with your account ID]
2/ Delete the IAM policy BasketballClusterLogin:
[Update the command with your account ID]
[Update the command with your account ID]
3/ Delete the Aurora DSQL Cluster.
Aurora DSQL leverages the combined capabilities of AWS IAM and PostgreSQL roles for robust security management. Instead of managing and rotating passwords, it uses generated short-lived tokens for authentication. The authorization system streamlines access control by allowing you to create precise policies and roles that restrict access to specific clusters and database objects based on application or user requirements.
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.