AWS aurora-dsql documentation change
Summary
Restructured access methods documentation with expanded sections for console access, programmatic access, SQL clients, and PostgreSQL protocol. Added detailed instructions for connecting with psql, DBeaver, and DataGrip including IAM authentication tokens and SSL requirements.
Security assessment
Added documentation emphasizes using IAM authentication tokens (temporary credentials) instead of passwords and enforces SSL connections. While these are security best practices, there's no indication they address a specific vulnerability.
Diff
diff --git a/aurora-dsql/latest/userguide/accessing.md b/aurora-dsql/latest/userguide/accessing.md index 360354597..70b8ead21 100644 --- a//aurora-dsql/latest/userguide/accessing.md +++ b//aurora-dsql/latest/userguide/accessing.md @@ -5 +5 @@ -Console +Console accessProgrammatic accessSQL clientsPostgreSQL protocol @@ -15 +15 @@ You can access Aurora DSQL through the following methods. - * [Using the PostgreSQL protocol with Aurora DSQL](./accessing-postgresql-endpoints.html) + * Accessing Aurora DSQL through the AWS Management Console @@ -17 +17 @@ You can access Aurora DSQL through the following methods. - * Access Aurora DSQL through the AWS Management Console + * Accessing Amazon Aurora DSQL programmatically @@ -19 +19 @@ You can access Aurora DSQL through the following methods. - * [Using SQL clients with Aurora DSQL](./accessing-sql-clients.html) + * Using SQL clients with Aurora DSQL @@ -21 +21 @@ You can access Aurora DSQL through the following methods. - * [Understanding programmatic access to Amazon Aurora DSQL](./accessing-programmatic.html) + * Using the PostgreSQL protocol with Aurora DSQL @@ -26 +26 @@ You can access Aurora DSQL through the following methods. -## Access Aurora DSQL through the AWS Management Console +## Accessing Aurora DSQL through the AWS Management Console @@ -28 +28 @@ You can access Aurora DSQL through the following methods. -Follow the steps below to access Aurora DSQL through the AWS Management Console. +Follow the steps below to access Aurora DSQL through the AWS Management Console: @@ -30 +30 @@ Follow the steps below to access Aurora DSQL through the AWS Management Console. - 1. Sign in to the AWS Management Console and open the Aurora DSQL at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql) + 1. Sign in to the AWS Management Console and open Aurora DSQL at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql) @@ -36,0 +37,160 @@ Follow the steps below to access Aurora DSQL through the AWS Management Console. +## Accessing Amazon Aurora DSQL programmatically + +Aurora DSQL provides you with the following tools to manage your Aurora DSQL resources programmatically: + +**AWS Command Line Interface (AWS CLI)** + + +You can create and manage your resources by using the AWS CLI in a command-line shell. The AWS CLI provides direct access to the APIs for AWS services, such as Aurora DSQL. For syntax and examples for the commands for Aurora DSQL, see [dsql](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_CreateCluster.html) in the _AWS CLI Command Reference_. + +**AWS software development kits (SDKs)** + + +AWS provides SDKs for many popular technologies and programming languages. They make it easier for you to call AWS services from within your applications in that language or technology. For more information about these SDKs, see [Tools for developing and managing applications on AWS](https://aws.amazon.com/developer/tools/). + +**Aurora DSQL API** + + +This API is another programming interface for Aurora DSQL. When using this API, you must format every HTTPS request correctly and add a valid digital signature to every request. For more information, see [Aurora DSQL API reference](./CHAP_api_reference.html). + +**AWS CloudFormation** + + +During Preview, Aurora DSQL doesn't support AWS CloudFormation. + +## Using SQL clients with Aurora DSQL + +Aurora DSQL uses the PostgreSQL protocol, so you can use your preferred interactive client by providing a signed IAM [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) as the password when connecting to your cluster. An authentication token is a unique string of characters that is generated dynamically. Authentication tokens are generated using AWS Signature Version 4. The token is only used for authentication and doesn't affect the connection after it is established. If you try to re-connect using an expired token, the connection request is denied. For more information, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html). + +###### Topics + + * Accessing Aurora DSQL with psql (PostgreSQL interactive terminal) + + * Accessing Aurora DSQL with DBeaver + + * Accessing Aurora DSQL with JetBrains DataGrip + + + + +### Accessing Aurora DSQL with psql (PostgreSQL interactive terminal) + +The psql utility is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. For more information about psql, see [https://www.postgresql.org/docs/current/app-psql.htm](https://www.postgresql.org/docs/current/app-psql.htm). To download the PostgreSQL-provided installers, see [PostgreSQL Downloads](https://www.postgresql.org/download/). + +If you already have the AWS CLI installed, use the following example to connect to your cluster. You can also use AWS CloudShell which comes with psql preinstalled, or, you can install psql directly. + + + # 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 will automatically use the values set in PGPASSWORD and PGSSLMODE. + # Quiet mode will suppress unnecessary warnings and chatty responses. Still outputs errors. + psql --quiet \ + --username admin \ + --dbname postgres \ + --host your_cluster_endpoint + +### Accessing Aurora DSQL with DBeaver + +DBeaver is an open-source, GUI-based database tool. You can use it to connect to and manage your database. To download DBeaver, see the [download page](https://dbeaver.io/download/) on the DBeaver Community website. The following steps explain how to connect to your cluster using DBeaver. + +###### To set up a new Aurora DSQL connection in DBeaver + + 1. Choose **New Database Connection**. + + 2. In the **New Database Connection** window, choose PostgreSQL. + + 3. In the **Connection settings/Main** tab, choose **Connect by: Host** and enter the following information. + + 1. **Host** \- Use your cluster endpoint. + +**Database** \- Enter `postgres` + +**Authentication** \- Choose `Database Native` + +**Username** \- Enter `admin` + +**Password** \- Generate an [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html). Copy the generated token and use it as your password. + + 4. Ignore any warnings and paste your authentication token into the **DBeaver Password** field. + +###### Note + +You must set SSL mode in the client connections. Aurora DSQL supports `SSLMODE=require`. Aurora DSQL enforces SSL communication on the server side and rejects non-SSL connections. + + 5. You should be connected to your cluster and can start running SQL statements. + + + + +###### Important + +The administrative features provided by DBeaver for the PostgreSQL databases (such as **Session Manager** and **Lock Manager**) don't apply to a database, due to its unique architecture. While accessible, these screens don't provide reliable information on the database health or status. + +**Authentication credentials expiry** + +Established sessions will 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 valid Authentication token must be provided in the **Password** field of the **Connection settings**. Trying to open a new session (for example, to list new tables, or a new SQL console) will force a new authentication attempt. If the authentication token configured in the **Connection settings** is no longer valid, that new session will fail and all the previously opened sessions will get invalidated at that point in time too. Have this in mind when choosing the duration of your IAM authentication token with the `expires-in` option. + +### Accessing Aurora DSQL with 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. + + 2. 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. + + 3. **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`. Aurora DSQL enforces SSL communication on the server side and will reject non-SSL connections. + + 4. You should be connected to your cluster and can start running SQL statements: + + + + +###### Important + +Some views provided by DataGrip for the PostgreSQL databases (such as Sessions) don't apply to a database because of its unique architecture. While accessible, these screens don't provide reliable information on the actual sessions connected to the database. + +**Authentication credentials expiration** + +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 **Data Source Properties**. Trying to open a new session (for example, to list new tables, or 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. + +## Using the PostgreSQL protocol with Aurora DSQL + +PostgreSQL uses a message-based protocol for communication between clients and servers. The protocol is supported over TCP/IP and also over Unix-domain sockets. The following table shows how Aurora DSQL supports the [PostgreSQL protocol](https://www.postgresql.org/docs/current/protocol.html). + +PostgreSQL | Aurora DSQL | Notes +---|---|--- +Role (also known as User or Group) | Database Role | Aurora DSQL creates a role for you named `admin`. If 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 [Configure custom database roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). +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.html). + @@ -45 +205 @@ Using database roles with IAM roles -PostgreSQL protocol +Working with Aurora DSQL