# Accessing Aurora DSQL with PostgreSQL-compatible clients
Accessing Aurora DSQL

Aurora DSQL uses the [PostgreSQL wire protocol](https://www.postgresql.org/docs/current/protocol.html). You can connect to PostgreSQL using a variety of tools and clients, such as AWS CloudShell, psql, DBeaver, and DataGrip. The following table summarizes how Aurora DSQL maps common PostgreSQL connection parameters:


| PostgreSQL | Aurora DSQL | Notes | 
| --- | --- | --- | 
| Role (also known as User or Group) | Database Role | Aurora DSQL creates a role for you named admin. When you create custom database roles, you must use the admin role to associate them with IAM roles for authenticating when connecting to your cluster. For more information, see [Using database roles and IAM authentication](using-database-and-iam-roles.md). | 
| Host (also known as hostname or hostspec) | Cluster Endpoint | Aurora DSQL single-Region clusters provide a single managed endpoint and automatically redirect traffic if there is unavailability within the Region. | 
| Port | N/A – use default 5432 | This is the PostgreSQL default. | 
| Database (dbname) | use postgres | Aurora DSQL creates this database for you when you create the cluster. | 
| SSL Mode | SSL is always enabled server-side | In Aurora DSQL, Aurora DSQL supports the require SSL Mode. Connections without SSL are rejected by Aurora DSQL. | 
| Password | Authentication Token | Aurora DSQL requires temporary authentication tokens instead of long-lived passwords. To learn more, see [Generating an authentication token in Amazon Aurora DSQL](SECTION_authentication-token.md). | 

When connecting, Aurora DSQL requires a signed IAM [authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) in place of a traditional password. These temporary tokens are generated using AWS Signature Version 4 and are used only during connection establishment. Once connected, the session remains active until it ends or the client disconnects.

If you attempt to open a new session with an expired token, the connection request fails and a new token must be generated. For more information, see [Generating an authentication token in Amazon Aurora DSQL](SECTION_authentication-token.md).

## Access Aurora DSQL using SQL clients
SQL clients

Aurora DSQL supports multiple PostgreSQL-compatible clients for connecting to your cluster. The following sections describe how to connect using PostgreSQL with AWS CloudShell or your local command line, as well as GUI-based tools like DBeaver and JetBrains DataGrip. Each client requires a valid authentication token as described in the previous section.

**Topics**
+ [

## Access Aurora DSQL using SQL clients
](#accessing-sql-clients)
+ [

# Use DBeaver to access Aurora DSQL
](accessing-dbeaver.md)
+ [

# Use JetBrains DataGrip to access Aurora DSQL
](accessing-datagrip.md)
+ [

# Use the PostgreSQL interactive terminal (psql) to access Aurora DSQL
](accessing-psql.md)
+ [

# Use Aurora DSQL driver for SQLTools
](accessing-vscode.md)
+ [

## Troubleshooting
](#accessing-troubleshooting)

# Use DBeaver to access Aurora DSQL
DBeaver

DBeaver is a universal SQL client that can be used to manage any database that has a JDBC driver. It is widely used among developers and database administrators because of its robust data viewing, editing, and management capabilities. Using DBeaver's cloud connectivity options, you can connect DBeaver to Aurora DSQL natively.

## DBeaver Pro
DBeaver Pro

DBeaver PRO products offer native integration with Aurora DSQL as of version 25.3. Follow the instructions from [DBeaver Documentation](https://dbeaver.com/docs/dbeaver/Database-driver-Aurora-DSQL/) to connect to your Aurora DSQL cluster.

## DBeaver Community Edition
DBeaver Community Edition

DBeaver Community Edition is the free and open-source version. Visit the [download page](https://dbeaver.io/download/) for installation instructions. In order to connect to DSQL from DBeaver Community Edition, you need to install the [Aurora DSQL Plugin for DBeaver](https://github.com/awslabs/aurora-dsql-dbeaver-plugin).

The [Aurora DSQL Plugin for DBeaver](https://github.com/awslabs/aurora-dsql-dbeaver-plugin) is built on top of the [Aurora DSQL Connector for JDBC](https://github.com/awslabs/aurora-dsql-jdbc-connector) and enables IAM authentication to Aurora DSQL clusters. It is conveniently installed through DBeaver UI and eliminates the need to write token generation code or manually supply a valid IAM token, simplifying the authentication while eliminating security risks associated with traditional user-generated passwords.

### Features
Features
+  IAM Authentication Support: Connect to Aurora DSQL clusters using AWS IAM credentials for secure, password-free authentication 
+  Automatic Driver Management: Seamlessly installs and configures the Aurora DSQL Connector for JDBC 
+  Flexible Connection Options: Choose between Host-based or JDBC URL-based connection configuration 

### Aurora DSQL Plugin for DBeaver Installation
Installation

1.  With DBeaver opened, Go to the Drop down menu **Help** → **Install New Software** 

1.  Click **Add** to add a new repository 

1.  Enter: 
   +  **Name**: `Aurora DSQL Plugin` 
   +  **Location**: `https://awslabs.github.io/aurora-dsql-dbeaver-plugin/update-site/` 

1.  Check **Aurora DSQL Connector for JDBC** 

1.  Click **Next**, accept the license, and complete the installation 

1.  Restart DBeaver when prompted 

### Create an Aurora DSQL Connection
Create Connection

1.  Click the **New Database Connection** 

1.  Select **Aurora DSQL** 

1.  Under **Server**, select one of the following for the **Connect by** setting 
   + **Host** 
     +  to enable the user interface text inputs for the following fields: 
       +  **Endpoint:** DSQL Cluster Endpoint 
       +  **Username:** DSQL username (e.g. admin) 
       +  **AWS Profile:** e.g. default - The standard profile used when no specific profile is specified 
       +  **AWS Region (Optional):** must match the region where your DSQL cluster exists, otherwise authentication will fail 
   +  **URL** 
     + JDBC URL in this format: 

       ```
       jdbc:aws-dsql:postgresql://{cluster_endpoint}/{database}?user=admin&profile=default&region=us-east-1
       ```
     +  Note: In this mode, only the URL input is enabled. In order to add parameters to the JDBC connection string, use the URL query parameters format starting with ? as the first parameter and append an & for subsequent parameters. 

1.  Click **Test Connection** to verify the Aurora DSQL connection works 

1.  Click **Finish** 

## Troubleshooting
Troubleshooting

### Windows Trust Store Issue
Windows Trust Store Issue

Windows users may encounter issues downloading the Aurora DSQL Connector for JDBC driver from Maven Central.

**Cause:** Windows Trust Store may not include the certificates required to access Maven Central repository.

**Solution:**

1. Run DBeaver as "Administrator"

1. Uncheck this setting - Windows > Preferences > Connections > "Use Windows Trust store"

### Missing Driver Error
Missing Driver Error

If you see a missing driver icon or connection errors, the Aurora DSQL (Community Plugin) may not be installed in your current DBeaver version. See below some examples of errors and how to fix them:
+ Creating a new connection with the missing driver:  
![\[Missing driver icon in DBeaver\]](http://docs.aws.amazon.com/aurora-dsql/latest/userguide/images/dbeaver-missing-driver-icon.png)
+ Attempting to connect without the driver:  
![\[Error dialog when driver is missing\]](http://docs.aws.amazon.com/aurora-dsql/latest/userguide/images/dbeaver-version-error-dialog.png)

**Cause:** When multiple DBeaver versions are installed, connection settings are shared but drivers are installed per application.

**Solution:** Reinstall the Aurora DSQL (Community plugin) by following the installation steps above.



**Important**  
The administrative features provided by DBeaver for PostgreSQL databases (such as **Session Manager** and **Lock Manager**) don't apply to Aurora DSQL databases due to their unique architecture. While accessible, these screens don't provide reliable information about database health or status.

# Use JetBrains DataGrip to access Aurora DSQL
JetBrains DataGrip

JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, including PostgreSQL. DataGrip includes a robust GUI with an intelligent SQL editor. To download DataGrip, go to the [download page](https://www.jetbrains.com/datagrip/download) on the *JetBrains* website.

**To set up a new Aurora DSQL connection in JetBrains DataGrip**

1. Choose **New Data Source** and choose PostgreSQL.

1. In the **Data Sources/General** tab, enter the following information:

   1. **Host** – Use your cluster endpoint.

     **Port** – Aurora DSQL uses the PostgreSQL default: `5432` 

     **Database** – Aurora DSQL uses the PostgreSQL default of `postgres` 

     **Authentication** – Choose `User & Password `.

     **Username** – Enter `admin`. 

     **Password** – [ Generate a token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) and paste it into this field.

     **URL** – Don't modify this field. It will be auto-populated based on the other fields.

1.  **Password** – Provide this by generating an authentication token. Copy the resulting output of the token generator and paste it into the password field. 
**Note**  
You must set SSL mode in the client connections. Aurora DSQL supports `PGSSLMODE=require and PGSSLMODE=verify-full`. Aurora DSQL enforces SSL communication on the server side and rejects non-SSL connections. For the `verify-full` option you will need to install the SSL certificates locally. For more information see [SSL/TLS certificates](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/configure-root-certificates.html).

1. You should be connected to your cluster and can start running SQL statements:

**Important**  
Some views provided by DataGrip for PostgreSQL databases (such as Sessions) don't apply to Aurora DSQL databases because of their unique architecture. While accessible, these screens don't provide reliable information about the actual sessions connected to the database.

# Use the PostgreSQL interactive terminal (psql) to access Aurora DSQL
Psql

## Use AWS CloudShell to access Aurora DSQL with the PostgreSQL interactive terminal (psql)
Access with AWS CloudShell

Use the following procedure to access Aurora DSQL with the PostgreSQL interactive terminal from AWS CloudShell. For more information, see [What is AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html).

**To connect using AWS CloudShell**

1. Sign in to the [Aurora DSQL console](https://console.aws.amazon.com/dsql).

1. Choose the cluster for which you would like to open in CloudShell. If you haven't yet created a cluster, follow the steps in [Step 1: Create an Aurora DSQL single-Region cluster](getting-started.md#getting-started-create-cluster) or [Create a multi-Region cluster](getting-started.md#getting-started-multi-region).

1. Choose **Connect with Query Editor** and then choose **Connect with CloudShell**.

1. Choose whether you want to connect as an admin or with a [custom database role](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html#authentication-authorization-iam-role-connect).

1. Choose **Launch in CloudShell** and choose **Run** in the following CloudShell dialog.

## Use the local CLI to access Aurora DSQL with the PostgreSQL interactive terminal (psql)
Access with the local CLI

Use `psql`, a terminal-based front-end to PostgreSQL utility, to interactively enter in queries, issue them to PostgreSQL, and view the query results.

**Note**  
To improve query response times, use the PostgreSQL version 17 client. If you use the CLI in a different environment, make sure you manually set up Python version 3.8\$1 and psql version 14\$1.

Download your operating system's installer from the [PostgreSQL Downloads](https://www.postgresql.org/download/) page. For more information about `psql`, see [PostgreSQL Client Applications](https://www.postgresql.org/docs/current/app-psql.htm) on the *PostgreSQL* website.

If you already have the AWS CLI installed, use the following example to connect to your cluster.

```
# Aurora DSQL requires a valid IAM token as the password when connecting.  
# Aurora DSQL provides tools for this and here we're using Python.  
export PGPASSWORD=$(aws dsql generate-db-connect-admin-auth-token \
  --region us-east-1 \
  --expires-in 3600 \
  --hostname your_cluster_endpoint)  
  
# Aurora DSQL requires SSL and will reject your connection without it.  
export PGSSLMODE=require  
  
# Connect with psql, which automatically uses the values set in PGPASSWORD and PGSSLMODE.  
# Quiet mode suppresses unnecessary warnings and chatty responses but still outputs errors.  
psql --quiet \
  --username admin \
  --dbname postgres \
  --host your_cluster_endpoint
```

# Use Aurora DSQL driver for SQLTools
VSCode

 The Aurora DSQL Driver for SQLTools is a Visual Studio Code extension for Amazon Aurora DSQL that integrates with SQLTools. It enables developers to connect to and query Aurora DSQL databases directly from VS Code. The driver is available for installation from [Visual Studio Marketplace](https://marketplace.visualstudio.com) and [Open VSX Registry](https://open-vsx.org/). Kiro, Cursor and other VSCode-based IDEs can use the [Open VSX Registry](https://open-vsx.org/) to install the driver following the standard installation procedure described in this page. 

## Features
Features
+  Automatic IAM Authentication 
+  Standard database operations like browsing schemas, tables, and executing SQL queries. 

## Installation
Installation

1.  Open the Extensions view. 

1.  Search for "Aurora DSQL Driver for SQLTools". 

1.  Click "Install". 

 **Note:** 

 The [SQLTools extension](https://vscode-sqltools.mteixeira.dev) will be automatically installed if not already present. 

## Authentication
Authentication

 In Aurora DSQL all connections use **IAM-based authentication** with time-limited tokens. The driver automatically handles Aurora DSQL authentication using the [Aurora DSQL Connector for node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres). 

 For more information on authentication in Aurora DSQL, see the [user guide](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html). 

## Create an Aurora DSQL Connection
Create an Aurora DSQL Connection

### Prerequisites
Prerequisites
+  AWS credentials configured (via AWS CLI, environment variables, or IAM roles) 

### Steps
Steps

1.  Click the SQLTools icon in the left sidebar. 

1.  In the SQLTools pane, hover over CONNECTIONS and click the Add New Connection icon. 

1.  In the SQLTools Settings tab select Aurora DSQL Driver from the list. 

1.  Fill in the connection parameters. 
   +  AWS Region 
     +  Optional - the region will be parsed from the Aurora DSQL cluster endpoint. 
     +  Required when only a cluster ID is specified in the DSQL Cluster field. 
   +  AWS Profile 
     +  Used for token generation. 
     +  Uses the default profile if not specified. 

1.  Click the "Test Connection button" to test the connection. 

1.  Click Save Connection. 

## Troubleshooting
Troubleshooting

**Authentication credentials expiration for the SQL Clients**

Established sessions remain authenticated for a maximum of 1 hour or until an explicit disconnect or a client-side timeout takes place. If new connections need to be established, a new authentication token must be generated and provided in the **Password** field of the connection. Trying to open a new session (for example, to list new tables, or open a new SQL console) forces a new authentication attempt. If the authentication token configured in the **Connection** settings is no longer valid, that new session will fail and all previously opened sessions will become invalid. Keep this in mind when choosing the duration of your IAM authentication token with the `expires-in` option, which can be set to 15 minutes by default and can be set to a maximum value of seven days.

Additionally, see the [Troubleshooting](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/troubleshooting.html) section of the Aurora DSQL documentation.