How do I notify AWS AppSync subscribers of external database updates that client-side mutations don't perform?

7 minute read

I need my app's clients to update in real time when external database changes are made that aren't performed through client-side mutations. How do I use AWS AppSync to notify subscribers of these changes?

Short description

Use local resolvers to notify subscribers of external database changes in real time, without making a data source call. For example, local resolvers are useful for apps that regularly update information, such as an airline app.

Complete the steps in the Resolution section to create an example GraphQL API. The GraphQL API updates subscribers in real time when data is written to an Amazon DynamoDB table data source.

Resolution

Create a GraphQL API using the wizard

Use the AWS AppSync guided schema wizard to create a new GraphQL API. For more information, see Designing a GraphQL API.

1. Open the AWS AppSync console.

2. Choose Create API.

3. On the Getting Started page, under Customize your API or import from Amazon DynamoDB, choose Create with wizard, and then choose Start.

4. On the Create a model page:
Under Name the model, enter a name for your model. For this example, Book is the name.
Under Configure model fields, define the data types for your app. For this example setup, keep the default field names (id and title) and types.
(Optional) Expand Configure model table (optional) to add an index.
Choose Create.

5. On the Create resources page, enter a name for your API. Then, choose Create. AWS AppSync creates your API and opens the Queries page of your API.

Create a test subscription

1. Open the AWS AppSync console.

2. Navigate to the Queries page of your API, and then, open a duplicate browser tab or window.

3. In the duplicate browser tab or window, clear the contents of the query editor and put in the following query:

subscription onCreateBook {
  onCreateBook {
    id
    title
  }
}

The preceding query creates a subscription to createBook mutations.

4. Choose the play button (Execute Query). The duplicate browser tab or window is subscribed to createBook mutations.

5. In the original browser tab or window, choose the play button (Execute Query), and then choose createBook to run the mutation. The results show in both the original and duplicate (subscription) browser tabs or windows.

6. After you see the subscription, close the duplicate browser tab or window.

Create a None-type data source

The None data source type passes the request mapping template directly to the response mapping template.

1. In the original browser tab or window, open the AWS AppSync console.

2. In the left navigation pane, choose Data Sources.

3. Choose Create Data Source.

4. On the New Data Source page, under Create new Data Source, complete the following steps:
For Data source name, enter a name. For example, real_time_data.
For Data source type, choose None.

5. Choose Create.

For more information, see Attaching a data source.

Add a mutation to the schema

Create a second mutation for an administrator to use, or to set off when you update the schema.

Update the schema with a mutation that passes database updates to the None type data source.

1. Open the AWS AppSync console.

2. In the left navigation pane, choose Schema.

3. In the schema editor, under type Mutation {, add the following command to create the new mutation type for external updates:

createBookExt(input: CreateBookInput!): Book

4. In the schema editor, under type Subscription {, locate the following line:

onCreateBook(id: ID, title: String): Book
        @aws_subscribe(mutations: ["createBook"])

5. Add "createBookExt" to the list of mutations:

onCreateBook(id: ID, title: String): Book
        @aws_subscribe(mutations: ["createBook", "createBookExt"])

6. Choose Save Schema.

For more information, see Designing your schema.

Attach a resolver to the mutation

1. Open the AWS AppSync console.

2. On the Schema page of your API, under Resolvers, scroll down to Mutation. Or, for Filter types, enter Mutation.

3. Next to createBookExt(...): Book, under Resolver, choose Attach.

4. On the Create new Resolver page, for Data source name, choose the name of the None type data source that you created. For example, real_time_data.

5. Under Configure the request mapping template, locate the request function:

export function request(ctx) {
    return {};
}

6. Modify the function to return ctx.args:

export function request(ctx) {
    return ctx.args;
}

7. Choose Create.

For more information, see Configuring resolvers (VTL).

Create a new test subscription

1. Open the AWS AppSync console.

2. In the left navigation pane, choose Queries.

3. On the Queries page of your API, open a duplicate browser tab or window.

4. In the duplicate browser tab or window, clear the contents of the query editor, and put in the following query:

subscription onCreateBook {
  onCreateBook {
    id
    title
  }
}

5. Choose the play button (Execute Query). The duplicate browser tab or window is now subscribed to both the createBook and createBookExt mutations.

Create a new test mutation

1. In the original browser tab or window, on the Queries page of your API, clear the contents of the query editor. Then, put in the following query:

mutation createBook($createbookinput: CreateBookInput!) {
  createBook(input: $createbookinput) {
    id
    title
  }
}

In the Query Variables section at the bottom of the editor, clear the contents and put in the following query:

{
  "createbookinput": {
    "title": "My New Book"
  }
}

The preceding query creates a new Book with the createBook mutation.

2. Choose the play button (Execute Query).

3. In the duplicate (subscription) browser tab or window, note that the subscriber receives the update in real time.

(Optional) Refer to example use cases

As you build your client app and apply these concepts, you can use the following example of building an airline app that provides pricing and flight times.

The following steps demonstrate how to notify subscribed clients when flight details change in a DynamoDB table:

1. Create an AWS Lambda function that uses a DynamoDB stream as the trigger. When the DynamoDB table updates, it invokes the Lambda function. For more information, see Using AWS Lambda with Amazon DynamoDB.

2. In the Lambda function code, include logic to filter the appropriate updates and perform a mutation call to AWS AppSync. This causes AWS AppSync to notify subscribers through the subscription. For more information, see Tutorial: AWS Lambda resolvers.

3. In AWS AppSync, add a new mutation field (for example, named publishPrice) with a local resolver.

4. Subscribe to that mutation in a subscription field (for example, named onPriceUpdate).

Example schema

type flightDetails {
  id: ID!
  src: String!
  destn: String!
  price : Int
}

type Mutation {
   # A local resolver targeting a None data source that publishes the message to subscribed clients.
  publishPrice(price: Int): flightDetails
}

type Subscription {
  # Notified whenever *publishPrice* is called.
  onPriceUpdate: Message
    @aws_subscribe(mutations: ["publishPrice"])
}

type Query { ... }

For more information, see Designing your schema.

5. Create another AWS Lambda function that uses a DynamoDB stream as the activation. In this function, call the publishPrice mutation. Because the publishPrice mutation has a local resolver, the data isn't written to DynamoDB again. With this method, you can use AWS AppSync as a PubSub broker.

For more information and another example use case, see Tutorial: Local resolvers.