AWS aurora-dsql documentation change
Summary
Restructured getting started guide with numbered steps, expanded prerequisites, detailed connection instructions with IAM authentication, and multi-region cluster creation process
Security assessment
Added documentation about IAM authentication requirements ('dsql:DbConnectAdmin' permission) and authentication token validity (15-minute expiration). While security-related features are documented, there's no evidence of addressing a specific vulnerability.
Diff
diff --git a/aurora-dsql/latest/userguide/getting-started.md b/aurora-dsql/latest/userguide/getting-started.md index 7ea950ba4..a2712159e 100644 --- a//aurora-dsql/latest/userguide/getting-started.md +++ b//aurora-dsql/latest/userguide/getting-started.md @@ -5 +5 @@ -PrerequisitesGetting startedSQL commands Multi-Region +PrerequisitesCreate a single-Region clusterConnect to a clusterRun SQL commandsCreate a multi-Region cluster @@ -11 +11 @@ Amazon Aurora DSQL is provided as a Preview service. To learn more, see [Betas a -Use the following steps to get started with Aurora DSQL. +In the following sections, you’ll learn how to create single-Region and multi-Region Aurora DSQL clusters, connect to them, and create and load a sample schema. You will access clusters with the AWS Management Console and interact with your database using the psql utility. @@ -17 +17 @@ Use the following steps to get started with Aurora DSQL. - * Create a cluster and connect with IAM authentication + * Step 1: Create an Aurora DSQL single-Region cluster @@ -19 +19 @@ Use the following steps to get started with Aurora DSQL. - * Run SQL commands in Aurora DSQL + * Step 2: Connect to your Aurora DSQL cluster @@ -21 +21,3 @@ Use the following steps to get started with Aurora DSQL. - * Create a multi-Region linked cluster + * Step 3: Run sample SQL commands in Aurora DSQL + + * Step 4: Create a multi-Region linked cluster @@ -28 +30 @@ Use the following steps to get started with Aurora DSQL. - * Your IAM identity must have permissions to [sign in to the AWS Management Console](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html). +Before you can begin using Aurora DSQL, make sure you meet the following prerequisites: @@ -30 +32 @@ Use the following steps to get started with Aurora DSQL. - * Your IAM identity must have access to perform any action on any resource in your AWS account, or you must be able to get access to the following IAM policy action: `dsql:*`. + * Your IAM identity must have permission to [sign in to the AWS Management Console](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html). @@ -31,0 +34 @@ Use the following steps to get started with Aurora DSQL. + * Your IAM identity must meet either of the following criteria: @@ -32,0 +36 @@ Use the following steps to get started with Aurora DSQL. + * Access to perform any action on any resource in your AWS account @@ -33,0 +38 @@ Use the following steps to get started with Aurora DSQL. + * The ability to get access to the following IAM policy action: `dsql:*` @@ -35 +40,8 @@ Use the following steps to get started with Aurora DSQL. -###### Note + * If you use the AWS CLI in a Unix-like environment, make sure that Python v3.8+ and psql v14+ are installed. To check your application versions, run the following commands. + + python3 --version + psql --version + +If you use the AWS CLI in a different environment, make sure that you manually set up Python v3.8+ and psql v14+. + + * If you intend to access Aurora DSQL using AWS CloudShell, Python v3.8+ and psql v14+ are provided with no extra setup. For more information about AWS CloudShell, see [What is AWS CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html). @@ -37 +49 @@ Use the following steps to get started with Aurora DSQL. -This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS CloudShell provides Python v3.8+ and psql v14+ with no extra setup. You can also use the AWS CLI in a different environment, but you must manually set up Python v3.8+ and psql v14+. If you prefer a GUI, you can [Access Aurora DSQL with DBeaver](./accessing-sql-clients.html#accessing-sql-clients-dbeaver) or [Access Aurora DSQL with JetBrains DataGrip](./accessing-sql-clients.html#accessing-sql-clients-datagrip). + * If you intend to access Aurora DSQL using a GUI, use DBeaver or JetBrains DataGrip. For more information, see [Accessing Aurora DSQL with DBeaver](./accessing.html#accessing-sql-clients-dbeaver) and [Accessing Aurora DSQL with JetBrains DataGrip](./accessing.html#accessing-sql-clients-datagrip). @@ -39 +51,6 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS -## Create a cluster and connect with IAM authentication + + + +## Step 1: Create an Aurora DSQL single-Region cluster + +The basic unit of Aurora DSQL is the cluster, which is where you store your data. In this task, you create a cluster in a single Region. @@ -45 +62,3 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS - 2. Choose **Create cluster**. Configure any of the settings that you want, such as deletion protection or tags. + 2. Choose **Create cluster**. + + 3. Configure any settings that you want, such as deletion protection or tags. @@ -47 +66 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS - 3. Choose **Create cluster**. + 4. Choose **Create cluster**. @@ -51,0 +71,4 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS +## Step 2: Connect to your Aurora DSQL cluster + +Authentication is managed using IAM so you don't need to store credentials in the database. An authentication token is a unique string of characters that is generated dynamically. The token is only used for authentication and doesn't affect the connection after it is established. Before attempting to connect, make sure that your IAM identity has the `dsql:DbConnectAdmin` permission, as described in Prerequisites. + @@ -54 +77,7 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS - 1. Choose the cluster that you want to connect to. Choose **Connect**. + 1. In the Aurora DSQL console, choose the cluster that you want to connect to. + + 2. Choose **Connect**. + + 3. Copy the endpoint from **Endpoint (Host)**. + + 4. Make sure that you **Connect as admin** is chosen in the **Authentication token (Password)** section. @@ -56 +85 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS - 2. Copy the endpoint. + 5. Copy the generated authentication token. This token is valid for 15 minutes. @@ -58 +87 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS - 3. Use the following command to use psql to start a connection to your cluster. Replace ``your_cluster_endpoint`` with the cluster endpoint. + 6. On the command line, use the following command to start psql and connect to your cluster. Replace ``your_cluster_endpoint`` with the cluster endpoint that you copied previously. @@ -65 +94 @@ This guide assumes a Unix-like environment with Python v3.8+ and psql v14+. AWS -You should see a prompt to provide a password. Generate an authentication token and use it as your password. +When prompted for a password, enter the authentication token that you copied previously. 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). @@ -67,5 +96 @@ You should see a prompt to provide a password. Generate an authentication token - 4. Make sure that you chose **Connect as admin**. - - 5. Copy the generated authentication token and paste it into the prompt to connect to Aurora DSQL from your SQL client. - - 6. Press **Enter**. You should see a PostgreSQL prompt. + 7. Press **Enter**. You should see a PostgreSQL prompt. @@ -80 +105 @@ If you get an access denied error, make sure that your IAM identity has the `dsq -## Run SQL commands in Aurora DSQL +## Step 3: Run sample SQL commands in Aurora DSQL @@ -82 +107 @@ If you get an access denied error, make sure that your IAM identity has the `dsq -The following steps provide some SQL commands that you can run in Aurora DSQL. +Test your Aurora DSQL cluster by running SQL statements. The following sample statements require the data files named `department-insert-multirow.sql` and `invoice.csv`, which you can download from the [ aws-samples/aurora-dsql-samples](https://github.com/aws-samples/aurora-dsql-samples/tree/main/quickstart_data) repository on GitHub. @@ -84 +109,3 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - 1. Start by creating a schema named example. +###### To run sample SQL commands in Aurora DSQL + + 1. Create a schema named `example`. @@ -90 +117,5 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - CREATE TABLE example.invoice(id UUID PRIMARY KEY DEFAULT gen_random_uuid(), created timestamp, purchaser int, amount float); + CREATE TABLE example.invoice( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + created timestamp, + purchaser int, + amount float); @@ -94 +125 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - CREATE INDEX invoice_created_idx on example.invoice(created); + CREATE INDEX ASYNC invoice_created_idx on example.invoice(created); @@ -100 +131 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - 5. Use `psql \copy` to load in some data. Download the data files named `department-insert-multirow.sql` and `invoice.csv` from the [ aws-samples/aurora-dsql-samples](https://github.com/aws-samples/aurora-dsql-samples/tree/main/quickstart_data) repository on GitHub. + 5. Use the command `psql \include` to load the file named `department-insert-multirow.sql` that you downloaded from the [ aws-samples/aurora-dsql-samples](https://github.com/aws-samples/aurora-dsql-samples/tree/main/quickstart_data) repository on GitHub. Replace `my-path` with the path to your local copy. @@ -102 +133 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - 6. Use the command `psql \include` to load the files. These operations create tables and insert sample data. + \include my-path/department-insert-multirow.sql @@ -104 +135 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - \include samples/department-insert-multirow.sql + 6. Use the command `psql \copy` to load the file named `invoice.csv` that you downloaded from the [ aws-samples/aurora-dsql-samples](https://github.com/aws-samples/aurora-dsql-samples/tree/main/quickstart_data) repository on GitHub. Replace `my-path` with the path to your local copy. @@ -106 +137 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - \copy example.invoice(created, purchaser, amount) from aurora-dsql-samples/quickstart_data/invoice.csv csv + \copy example.invoice(created, purchaser, amount) from my-path/invoice.csv csv @@ -108 +139 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. - 7. You can then list departments that are sorted by their total sales. + 7. Query the departments and sort them by their total sales. @@ -116 +147 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. -**Example output:** +The following sample output shows that Department Three has the most sales. @@ -133 +164,14 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. -## Create a multi-Region linked cluster +## Step 4: Create a multi-Region linked cluster + +When you create a multi-Region linked cluster, you specify the following Regions: + + * The linked cluster Region + +This is a separate Region in which you create a second cluster. Aurora DSQL replicates all writes on the original cluster to the linked cluster. You can read and write on any linked cluster. + + * The witness Region + +This Region receives all data that is written to linked clusters, but you can't write to it. The witness Region stores a limited window of encrypted transaction logs. Aurora DSQL uses these capabilities to provide multi-Region durability and availability. + + + @@ -135 +179 @@ The following steps provide some SQL commands that you can run in Aurora DSQL. -These steps guide you through how to create a multi-Region linked cluster. They also demonstrate cross-Region write replication and consistent reads from both Regional endpoints. +The following example demonstrates cross-Region write replication and consistent reads from both Regional endpoints. @@ -139 +183 @@ These steps guide you through how to create a multi-Region linked cluster. They - 1. From the **Aurora DSQL Clusters** page, choose **Create cluster**. + 1. In the Aurora DSQL console, go to the **Clusters** page. @@ -141 +185 @@ These steps guide you through how to create a multi-Region linked cluster. They - 2. Choose **Add linked Regions** and choose a Region for your linked cluster Region. The linked cluster Region is a separate Region to create another cluster in. Aurora DSQL replicates all writes to this cluster as well, so you can read and write from any linked cluster. + 2. Choose **Create cluster**. @@ -143 +187,5 @@ These steps guide you through how to create a multi-Region linked cluster. They - 3. Choose a witness Region. The witness Region receives all data that is written to linked clusters, but you can't write to it. The witness Region stores a limited window of encrypted transaction logs. Aurora DSQL uses these capabilities to provide multi-Region durability and availability. + 3. Choose **Add linked Regions**. + + 4. Choose a Region for your linked cluster from **Linked cluster Region**. + + 5. Choose a witness Region. During the preview, you can only choose **us-west-2** as the witness Region. @@ -147 +195 @@ These steps guide you through how to create a multi-Region linked cluster. They -Witness Regions don't host client endpoints and don't provide user data access. A limited window of the encrypted transaction log is maintained in witness Regions. This facilitates recovery and supports transactional quorum in the event of Region unavailability. During preview, you can only choose us-west-2 as the witness Region. +Witness Regions don't host client endpoints and don't provide user data access. A limited window of the encrypted transaction log is maintained in witness Regions. This facilitates recovery and supports transactional quorum in the event of Region unavailability. @@ -149 +197 @@ Witness Regions don't host client endpoints and don't provide user data access. - 4. Choose **Create**. + 6. Choose any additional settings, such as deletion protection or tags. @@ -151 +199 @@ Witness Regions don't host client endpoints and don't provide user data access. - 5. While Aurora DSQL is creating your cluster, open two instances of AWS CloudShell in different Regions. Open one in the environment in us-east-1 and another one in us-east-2. + 7. Choose **Create cluster**. @@ -157 +205,9 @@ During preview, creating linked clusters takes additional time. - 6. Connect to your cluster in us-east-2. + 8. Open the AWS CloudShell console at [https://console.aws.amazon.com/cloudshell](https://console.aws.amazon.com/cloudshell) in two browser tabs. Open one environment in us-east-1 and another in us-east-2. + + 9. In the Aurora DSQL console, choose the linked cluster that you created. + + 10. Choose the link in the **Linked Regions** column. + + 11. Copy the endpoint to your linked cluster. + + 12. In your us-east-2 CloudShell environment, start psql and connect to your linked cluster. @@ -169 +225 @@ During preview, creating linked clusters takes additional time. - 1. In your us-east-2 CloudShell environment, go through the steps in Run SQL commands in Aurora DSQL. + 1. In your us-east-2 CloudShell environment, create a sample schema by following the steps in Step 3: Run sample SQL commands in Aurora DSQL. @@ -178,2 +234 @@ During preview, creating linked clusters takes additional time. - - 2. Use PSQL meta commands to load data. For more information, see Run SQL commands in Aurora DSQL. + 2. Use psql meta commands to load sample data. For more information, see Step 3: Run sample SQL commands in Aurora DSQL. @@ -204 +257 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Core components +What is Amazon Aurora DSQL?