Add GraphQL Edge Caching to Fauna

GraphQL performance is critical for web and mobile apps. With GraphQL, clients fetch specific data through HTTP POST requests, making caching more complex compared to REST APIs.

Fauna is a distributed relational database with a document data model delivered as a cloud API. It offers advanced querying capabilities, robust consistency guarantees, and comprehensive support for data operations. These attributes make Fauna an ideal fit for secure multi-tenant apps, distributed real-time apps, user-centric apps, or stateful serverless apps.

Developers can leverage its strongly typed database language, FQL v10, to express complex business logic in transactions. With multi-region, active-active compute and a distributed transaction engine, Fauna ensures fast, reliable, and secure performance.

In this guide, we will concentrate on improving performance by implementing Grafbase's GraphQL Edge Caching on top of Fauna GraphQL API. This approach aims to further optimize the GraphQL layer, enhancing overall application performance.

You should already have a Fauna GraphQL schema to follow along, otherwise, you can get started here.

Get started locally

Begin by executing the following command inside a new or existing project's directory:

npx grafbase init --template graphql-fauna

This will generate a new folder grafbase with the file grafbase.config.ts that looks something like this:

import { config, connector, g } from '@grafbase/sdk'

const fauna = connector.GraphQL({
  url: 'https://graphql.fauna.com/graphql',
  headers: headers => {
    headers.set('Authorization', { forward: 'Authorization' })
  }
})

g.datasource(fauna)

export default config({
  schema: g,
  cache: {
    rules: [
      {
        types: ['Query'],
        maxAge: 60
      }
    ]
  }
})

This configuration will:

Add Fauna as a data source
Cache all queries for 60 seconds
Enable public access to the Grafbase Edge Gateway
Forward Authorization header to Fauna

💡

If you plan to add other data sources, you should use a namespace to prevent schema conflicts.

If you'd prefer not to pass the Authorization header with requests from the client, you can also set the Authorization to use an environment variable stored by Grafbase:

const fauna = connector.GraphQL({
  url: 'https://graphql.fauna.com/graphql',
  headers: headers => {
    headers.set('Authorization', `Bearer ${g.env('FAUNA_API_KEY')}`)
  }
})

If you don't use header forwarding, make sure to add your FAUNA_API_KEY to the file grafbase/.env:

# Only if you set the Authorization header with a static value
# FAUNA_API_KEY=

Finally, use the Grafbase CLI to start the development server and automatically generate a GraphQL API for Tinybird:

npx grafbase dev

You now have a GraphQL API running locally that acts as a proxy to Fauna! 🎉

You can execute any GraphQL query using the new endpoint: http://127.0.0.1:4000/graphql.

💡

Grafbase Pathfinder can be found at http://127.0.0.1:4000 where you can explore the Grafbase Edge Gateway API and schema.

💡

Make sure to commit the grafbase folder with the rest of your application.

Deploy to Production

You can continue to use the Grafbase CLI when building locally to proxy your Fauna GraphQL API but you will need to deploy to production to take advantage of GraphQL Edge Caching.

Follow these steps to deploy to production:

Signup for an account at grafbase.com
Visit grafbase.com/new to create a new project
Connect and deploy your application where the grafbase was added
Make sure to add your FAUNA_API_KEY when deploying, unless you made it optional
Update your host (Netlify, Vercel, Fly, etc.) with the new GraphQL API endpoint that Grafbase supplied for your new project.

That's it!

Grafbase is programmed to autonomously deploy a fresh gateway each time it identifies a change to grafbase/grafbase.config.ts. Consequently, if you need to adjust any cache settings, including parameters like maxAge, staleWhileRevalidate, and mutationInvalidation, you’re free to do so.

Grafbase will handle the rest of the process seamlessly. We'll explore extending the Fauna GraphQL API with custom fields in another post.

#GrafbaseHackathon