Skip to main content
Version: v2.x

Enable Caching in Hasura Enterprise Edition

Introduction

To start using Hasura Caching with your Hasura Enterprise Edition GraphQL Engine you will need a Redis instance that is co-located with the Hasura GraphQL containers.

Once you provision a Redis instance, provide the URL to the Hasura GraphQL Engine docker configuration using the following environment variable:

HASURA_GRAPHQL_REDIS_URL=redis://username:password@redishostname:port

Enable Redis TLS

TLS connection information can be specified via the following environment variables:

  • HASURA_GRAPHQL_REDIS_USE_TLS: Opt-in flag that enables the use of TLS for the caching Redis instance, defaults to false.
  • HASURA_GRAPHQL_RATE_LIMIT_REDIS_USE_TLS: Opt-in flag that enables the use of TLS for the rate-limiting Redis instance, defaults to false.
  • HASURA_GRAPHQL_REDIS_TLS_HOSTNAME: TLS hostname to use for caching Redis instance.
  • HASURA_GRAPHQL_RATE_LIMIT_REDIS_TLS_HOSTNAME: TLS hostname to use for rate-limiting Redis instance.
  • HASURA_GRAPHQL_REDIS_TLS_SHARED_CA_STORE_PATH: path to the shared CA certificate store to use for both the caching and rate-limiting Redis instances. If unspecified, it defaults to the system CA store if available.

Example

HASURA_GRAPHQL_REDIS_USE_TLS="true"
HASURA_GRAPHQL_REDIS_URL="redis://username:password@redishostname:port"
HASURA_GRAPHQL_REDIS_TLS_HOSTNAME="redishostname"

For rate limit Redis:

HASURA_GRAPHQL_RATE_LIMIT_REDIS_USE_TLS="true"
HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL="redis://username:password@redishostname:port"
HASURA_GRAPHQL_RATE_LIMIT_REDIS_TLS_HOSTNAME="redishostname"

Tune caching parameters

You can tune the various caching parameters according to your use-case. For example, you can configure the maximum TTL allowed, the max entry size in the cache etc.

Env varFlagDescription
HASURA_GRAPHQL_CACHE_MAX_ENTRY_TTL--query-cache-max-ttlMaximum TTL allowed in seconds. Clients can request TTL via the @cached directive. But an upper limit can be set using this setting. Default: 3600 seconds
HASURA_GRAPHQL_CACHE_MAX_ENTRY_SIZE--query-cache-max-entry-sizeMaximum size of the response that is allowed to be cached (in MB). default: 1000 MB
HASURA_GRAPHQL_CACHE_BUCKET_RATE--query-cache-bucket-rateRecharge rate for the Query Response Cache token bucket. Default: 10,000,000 bytes/second (10 MB/s)
HASURA_GRAPHQL_CACHE_BUCKET_SIZE--query-cache-bucket-sizeMaximum capacity in bytes for the Query Response Cache token bucket algorithm. See https://hasura.io/docs/latest/queries/response-caching for more info. Default: 1000000000 bytes (1 GB)

How to tune these parameters

  • HASURA_GRAPHQL_CACHE_MAX_ENTRY_TTL - TTL is the only automatic way of invalidating cache entries in Hasura. Ideally, you would like to keep the TTL closer to the frequency of your data updates. In some use-cases, if you want to cache for large amounts of time (in the order of 10s of hours), you may set the max TTL to that, and have some way of using the cache clear APIs to invalidate the cache when you update your data.
  • HASURA_GRAPHQL_CACHE_MAX_ENTRY_SIZE - The default response size for a single cache entry is 1000MB. If you want to cache responses larger than 1000MB, configure this parameter accordingly.
  • HASURA_GRAPHQL_CACHE_BUCKET_RATE - The default bucket recharge rate is 10MB per second. Set this value to the total or cumulative response sizes across all your data sources during peak traffic. By setting this parameter appropriately, you guard your data sources, as well as the cache itself, from being overloaded by the caching mechanism. Changing this parameter is probably mainly important for non-standard workloads, in which case you can reach out to Hasura Support.
  • HASURA_GRAPHQL_CACHE_BUCKET_SIZE - Maximum size of the cache store. If your cache store exceeds this size, new items cannot be stored. So you should tune this such that at peak traffic, given your configured max entry size and TTL, you should have ample space to store all the items.