AWS appsync documentation change
Summary
Updated Aurora Serverless tutorial to use v2 configuration, added detailed setup steps, restructured documentation layout, and updated CLI commands/ARN examples
Security assessment
The changes primarily update technical implementation details (Aurora Serverless v2, PostgreSQL 16.6, CLI syntax) and improve documentation structure. While security best practices are mentioned (Secrets Manager usage), there's no evidence of addressing specific vulnerabilities or adding new security features. The --enable-http-endpoint flag is part of normal Data API setup rather than a security fix.
Diff
diff --git a/appsync/latest/devguide/aurora-serverless-tutorial-js.md b/appsync/latest/devguide/aurora-serverless-tutorial-js.md index 746bd670e..debf504c2 100644 --- a//appsync/latest/devguide/aurora-serverless-tutorial-js.md +++ b//appsync/latest/devguide/aurora-serverless-tutorial-js.md @@ -5 +5 @@ -Creating clustersEnabling data APICreating the database and tableCreating a GraphQL schemaResolvers for RDSDeleting your cluster +Set up your Aurora PostgreSQL databaseCreating the database and tableCreating a GraphQL schemaResolvers for RDSDeleting your cluster @@ -9 +9,3 @@ Creating clustersEnabling data APICreating the database and tableCreating a Grap -AWS AppSync provides a data source for executing SQL statements against Amazon Aurora clusters that are enabled with a Data API. You can use AWS AppSync resolvers to run SQL statements against the data API with GraphQL queries, mutations, and subscriptions. +Learn how to connect your GraphQL API to Aurora PostgreSQL databases using AWS AppSync. This integration enables you to build scalable, data-driven applications by executing SQL queries and mutations through GraphQL operations. AWS AppSync provides a data source for executing SQL statements against Amazon Aurora clusters that are enabled with a Data API. You can use AWS AppSync resolvers to run SQL statements against the data API with GraphQL queries, mutations, and subscriptions. + +Before starting this tutorial, you should have basic familiarity with AWS services and GraphQL concepts. @@ -15 +17,12 @@ This tutorial uses the `US-EAST-1` Region. -## Creating clusters +###### Topics + + * Set up your Aurora PostgreSQL database + + * Creating the database and table + + * Creating a GraphQL schema + + * Resolvers for RDS + + * Deleting your cluster + @@ -17 +29,0 @@ This tutorial uses the `US-EAST-1` Region. -Before adding an Amazon RDS data source to AWS AppSync, first enable a Data API on an Aurora Serverless cluster. You must also configure a secret using AWS Secrets Manager. To create an Aurora Serverless cluster, you can use the AWS CLI: @@ -19,0 +32,10 @@ Before adding an Amazon RDS data source to AWS AppSync, first enable a Data API +## Set up your Aurora PostgreSQL database + +Before adding an Amazon RDS data source to AWS AppSync, do the following. + + 1. Enable a Data API on an Aurora Serverless v2 cluster. + + 2. Configure a secret using AWS Secrets Manager + + 3. Create the cluster using the following AWS CLI command. + @@ -22,2 +44,3 @@ Before adding an Amazon RDS data source to AWS AppSync, first enable a Data API - --engine aurora-postgresql --engine-version 13.11 \ - --engine-mode serverless \ + --engine aurora-postgresql \ + --engine-version 16.6 \ + --serverless-v2-scaling-configuration MinCapacity=0,MaxCapacity=1 \ @@ -25 +48,4 @@ Before adding an Amazon RDS data source to AWS AppSync, first enable a Data API - --master-user-password COMPLEX_PASSWORD + --master-user-password COMPLEX_PASSWORD \ + --enable-http-endpoint + + @@ -27 +53,15 @@ Before adding an Amazon RDS data source to AWS AppSync, first enable a Data API -This will return an ARN for the cluster. You can check on the status of your cluster with the command: + +This will return an ARN for the cluster. After creating a cluster, you must add a Serverless v2 instance with the following AWS CLI command. + + + aws rds create-db-instance \ + --db-cluster-identifier appsync-tutorial \ + --db-instance-identifier appsync-tutorial-instance-1 \ + --db-instance-class db.serverless \ + --engine aurora-postgresql + +###### Note + +These endpoints take time to become activate. You can check their status in the RDS console in the **Connectivity & security** tab for the cluster. + +Check the cluster status with the following AWS CLI command. @@ -42 +82 @@ Create a Secret via the AWS Secrets Manager Console or the AWS CLI with an input -Pass this as a parameter to the CLI: +Pass this as a parameter to the AWS CLI: @@ -49,11 +89 @@ Pass this as a parameter to the CLI: -This will return an ARN for the secret. **Take note** of the ARN of your Aurora Serverless cluster and Secret for later when creating a data source in the AWS AppSync console. - -## Enabling data API - -Once your cluster status changes to `available`, enable the Data API by following the [Amazon RDS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html). The Data API must be enabled before adding it as an AWS AppSync data source. You can also enable the Data API using the AWS CLI: - - - aws rds modify-db-cluster \ - --db-cluster-identifier appsync-tutorial \ - --enable-http-endpoint \ - --apply-immediately +This will return an ARN for the secret. **Take note** of the ARN of your Aurora Serverless v2 cluster and Secret for later when creating a data source in the AWS AppSync console. @@ -63 +93 @@ Once your cluster status changes to `available`, enable the Data API by followin -After enabling your Data API, validate it works using the `aws rds-data execute-statement` command in the AWS CLI. This ensures that your Aurora Serverless cluster is configured properly before adding it to the AWS AppSync API. First, create a _TESTDB_ database with the `--sql` parameter: +First, create a database named `TESTDB`. In PostgreSQL, a database is a container that holds tables and other SQL objects. Validate that your Aurora Serverless v2 cluster is configured correctly before adding it to your AWS AppSync API. First, create a _TESTDB_ database with the `--sql` parameter as follows. @@ -67,3 +97,4 @@ After enabling your Data API, validate it works using the `aws rds-data execute- - --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:appsync-tutorial" \ - --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:appsync-tutorial-rds-secret" \ - --sql "create DATABASE \"testdb\"" + --resource-arn "arn:aws:rds:us-east-1:111122223333 ISN:cluster:appsync-tutorial" \ + --secret-arn "arn:aws:secretsmanager:us-east-1:111122223333 ISN:secret:appsync-tutorial-rds-secret" \ + --sql "create DATABASE \"testdb\"" \ + --database "postgres" @@ -75,2 +106,2 @@ If this runs without any errors, add two tables with the `create table` command: - --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:appsync-tutorial" \ - --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:appsync-tutorial-rds-secret" \ + --resource-arn "arn:aws:rds:us-east-1:111122223333 ISN:cluster:appsync-tutorial" \ + --secret-arn "arn:aws:secretsmanager:us-east-1:111122223333 ISN:secret:appsync-tutorial-rds-secret" \ @@ -81,2 +112,2 @@ If this runs without any errors, add two tables with the `create table` command: - --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:appsync-tutorial" \ - --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:appsync-tutorial-rds-secret" \ + --resource-arn "arn:aws:rds:us-east-1:111122223333 ISN:cluster:appsync-tutorial" \ + --secret-arn "arn:aws:secretsmanager:us-east-1:111122223333 ISN:secret:appsync-tutorial-rds-secret" \ @@ -86 +117 @@ If this runs without any errors, add two tables with the `create table` command: -If everything runs without issues, you can now add the cluster as a data source in your API. +If successful, add the cluster as a data source in your API. @@ -90 +121 @@ If everything runs without issues, you can now add the cluster as a data source -Now that your Aurora Serverless Data API is running with configured tables, we'll create a GraphQL schema. You can do this manually, but AWS AppSync lets you quickly get started by importing table configuration from an existing database using the API creation wizard. +Now that your Aurora Serverless v2 Data API is running with configured tables, we'll create a GraphQL schema. You can quickly create your API by importing table configurations from an existing database using the API creation wizard. @@ -130,2 +161,2 @@ To begin: - "arn:aws:rds:us-east-1:123456789012:cluster:appsync-tutorial", - "arn:aws:rds:us-east-1:123456789012:cluster:appsync-tutorial:*" + "arn:aws:rds:us-east-1:111122223333 ISN:cluster:appsync-tutorial", + "arn:aws:rds:us-east-1:111122223333 ISN:cluster:appsync-tutorial:*" @@ -140,2 +171,2 @@ To begin: - "arn:aws:secretsmanager:us-east-1:123456789012:secret:your:secret:arn:appsync-tutorial-rds-secret", - "arn:aws:secretsmanager:us-east-1:123456789012:secret:your:secret:arn:appsync-tutorial-rds-secret:*" + "arn:aws:secretsmanager:us-east-1:111122223333 ISN:secret:your:secret:arn:appsync-tutorial-rds-secret", + "arn:aws:secretsmanager:us-east-1:111122223333 ISN:secret:your:secret:arn:appsync-tutorial-rds-secret:*" @@ -156 +187 @@ Choose **Next** , review the configuration details, then choose **Create API**. -The API creation flow automatically created the resolvers to interact with our types. If you look at **Schema** page, you will find resolvers necessary to: +The API creation flow automatically created the resolvers to interact with our types. If you look at **Schema** page, you will find resolvers some of the follwoing resolvers. @@ -177 +208 @@ From the schema editor in the AWS AppSync console, on the right side, choose `te -Let's update the resolver to properly specify the `DATE` type of the `due` field: +Update the following resolver to properly specify the `DATE` type of the `due` field. @@ -209 +240 @@ Let's update the resolver to properly specify the `DATE` type of the `due` field -Save the resolver. The type hint marks the `due` properly in our input object as a `DATE` type. This allows the Postgres engine to properly interpret the value. Next, update your schema to remove the `id` from the `CreateTodo` input. Because our Postgres database can return the generated ID, we can rely on it for creation and returning the result as a single request: +Save the resolver. The type hint marks the `due` properly in our input object as a `DATE` type. This allows the Postgres engine to properly interpret the value. Next, update your schema to remove the `id` from the `CreateTodo` input. Because our Postgres database can return the generated ID, you can rely on it for creation and returning the result as a single request as follows. @@ -218 +249 @@ Save the resolver. The type hint marks the `due` properly in our input object as -Make the change and update your schema. Head to the **Queries** editor to add an item to the database: +Make the change and update your schema. Head to the **Queries** editor to add an item to the database as follows. @@ -230 +261 @@ Make the change and update your schema. Head to the **Queries** editor to add an -You get the result: +You get the following result. @@ -262 +293 @@ From the schema editor in the console, on the right side, choose `testdb` next t -We want to filter `todos` based on the `due` date. Let's update the resolver to cast `due` values to `DATE`. Update the list of imports and the request handler: +We want to filter `todos` based on the `due` date. Let's update the resolver to cast `due` values to `DATE`. Update the list of imports and the request handler as follows. @@ -309 +340 @@ We want to filter `todos` based on the `due` date. Let's update the resolver to -Let's try out the query. In the **Queries** editor: +In the **Queries** editor do the following. @@ -335 +366 @@ You can also `update` a `Todo`. From the **Queries** editor, let's update our fi -Note that you must specify the `id` of the item you are updating. You can also specify a condition to only update an item that meets specific conditions. For example, we may only want to edit the item if the description starts with `edits`: +Note that you must specify the `id` of the item you are updating. You can also specify a condition to only update an item that meets specific conditions. For example, we may only want to edit the item if the description starts with `edits` as follows. @@ -346 +377 @@ Note that you must specify the `id` of the item you are updating. You can also s -Just like how we handled our `create` and `list` operations, we can update our resolver to cast the `due` field to a `DATE`. Save these changes to `updateTodo`: +Just like how we handled our `create` and `list` operations, we can update our resolver to cast the `due` field to a `DATE`. Save these changes to `updateTodo` as follows. @@ -407 +438 @@ Now try an update with a condition: -You can `delete` a `Todo` with the `deleteTodo` mutation. This works like the `updateTodo` mutation, and you must specify the `id` of the item you want to delete: +You can `delete` a `Todo` with the `deleteTodo` mutation. This works like the `updateTodo` mutation, and you must specify the `id` of the item you want to delete as follows. @@ -428 +459 @@ We've used the `rds` module utilities to create our SQL statements. We can also -Next, create a couple of tasks. A task has a foreign key relationship with `Todo`: +Next, create a couple of tasks. A task has a foreign key relationship with `Todo`as follows. @@ -437 +468 @@ Next, create a couple of tasks. A task has a foreign key relationship with `Todo -Create a new field in your `Query` type called `getTodoAndTasks`: +Create a new field in your `Query` type called `getTodoAndTasks`as follows. @@ -442 +473 @@ Create a new field in your `Query` type called `getTodoAndTasks`: -Add a `tasks` field to the `Todo` type: +Add a `tasks` field to the `Todo` type as follows. @@ -453 +484 @@ Add a `tasks` field to the `Todo` type: -Save the schema. From the schema editor in the console, on the right side, choose **Attach Resolver** for `getTodosAndTasks(id: Int!): Todo`. Choose your Amazon RDS data source. Update your resolver with the following code: +Save the schema. From the schema editor in the console, on the right side, choose **Attach Resolver** for `getTodosAndTasks(id: Int!): Todo`. Choose your Amazon RDS data source. Update your resolver with the following code. @@ -474 +505 @@ Save the schema. From the schema editor in the console, on the right side, choos -In this code, we use the `sql` tag template to write a SQL statement that we can safely pass a dynamic value to at run time. `createPgStatement` can take up to two SQL requests at a time. We use that to send one query for our `todo` and another for our `tasks`. You could have done this with a `JOIN` statement or any other method for that matter. The idea is being able to write your own SQL statement to implement your business logic. To use the query in the **Queries** editor, we can try this: +In this code, we use the `sql` tag template to write a SQL statement that we can safely pass a dynamic value to at run time. `createPgStatement` can take up to two SQL requests at a time. We use that to send one query for our `todo` and another for our `tasks`. You could have done this with a `JOIN` statement or any other method for that matter. The idea is being able to write your own SQL statement to implement your business logic. To use the query in the **Queries** editor, do the following.