Configuring cache backends

⚠️ New in Apollo Server 3.9: We strongly recommend that all users pass cache: "bounded" or configure their cache in a manner that isn't unbounded (which is current default behavior). This protects your server from attacks that exhaust available memory, causing a DOS. See Ensuring a bounded cache immediately below for more details.

Many Apollo Server features take advantage of a cache backend (these features include automatic persisted queries, the response cache plugin, and RESTDataSource). Apollo Server uses an in-memory cache by default, but you can configure it to use a different backend, such as Redis or Memcached.

You can specify a cache backend by passing a cache option to the ApolloServer constructor. Your specified cache backend must implement the KeyValueCache interface from the @apollo/utils.keyvaluecache package.

There are many cache backend implementations to choose from, including several implementations provided by Apollo. For example, Apollo maintains an implementation of InMemoryLRUCache in the @apollo/utils.keyvaluecache package. Apollo also provides a wrapper class for the keyv package (which implements several cache backends) named KeyvAdapter in the @apollo/utils.keyvadapter package.

Ensuring a bounded cache

Unfortunately, the default configuration of Apollo Server exposes you to denial of service attacks. This is because APQs are enabled by default and the default cache in Apollo Server 3 is unbounded, meaning an attacker can exhaust your memory and crash your server. The default cache in Apollo Server 4 will be bounded; we recommend opting in to that behavior by providing the cache: "bounded" option to your Apollo Server constructor or configuring the cache yourself. Alternatively, you can disable APQs by passing persistedQueries: false or configure the APQ cache separately by passing a KeyValueCache to persistedQueries: { cache }.

Configuring in-memory caching

Apollo Server's default caching features use an unbounded cache, which is not safe for production use. If you want to configure the in-memory cache, Apollo provides the InMemoryLRUCache class from the @apollo/utils.keyvaluecache package.

The InMemoryLRUCache class is a wrapper around the lru-cache package and has a default maximum of approximately 30MiB of memory. You can configure an instance of InMemoryLRUCache with the same options as found in the lru-cache package, see the lru-cache documentation for more details. You can use Apollo's InMemoryLRUCache by passing it to the cache option of the ApolloServer constructor like so:

1import { InMemoryLRUCache } from '@apollo/utils.keyvaluecache';
2
3const server = new ApolloServer({
4  cache: new InMemoryLRUCache(),
5});

The equivalent of this is provided out-of-the-box by Apollo Server 3.9+ by passing cache: "bounded" and doesn't require you to install the @apollo/utils.keyvaluecache package.

In this example, we've increased the default size and provided a default TTL. For more information on these configuration options, see the lru-cache documentation.

1import { InMemoryLRUCache } from '@apollo/utils.keyvaluecache';
2
3const server = new ApolloServer({
4  // ...
5  cache: new InMemoryLRUCache({
6    // ~100MiB
7    maxSize: Math.pow(2, 20) * 100,
8    // 5 minutes (in milliseconds)
9    ttl: 300_000,
10  }),
11});

Configuring external caching

Apollo no longer maintains any caching backends directly. Instead, we recommend using the keyv package along with the KeyvAdapter class provided by the @apollo/utils.keyvadapter package. KeyvAdapter simply wraps a Keyv instance and implements the KeyValueCache interface which is required by Apollo Server. You can use the KeyvAdapter class to wrap a Keyv instance and provide it to the cache option of the ApolloServer constructor like so:

1. Install the required packages

1npm install keyv @apollo/utils.keyvadapter

2. Configure the Apollo Server cache

1import Keyv from 'keyv';
2import { KeyvAdapter } from '@apollo/utils.keyvadapter';
3
4const server = new ApolloServer({
5  // ...,
6  cache: new KeyvAdapter(new Keyv()),
7});

Implementing your own cache backend

If your requirements are specialized or you'd prefer to implement your own cache backend, you can implement the KeyValueCache interface and pass it to the ApolloServer constructor directly.

The KeyValueCache interface is shown below:

1interface KeyValueCache<V> {
2  get(key: string): Promise<V | undefined>;
3  // ttl is specified in seconds
4  set(key: string, value: V, options?: { ttl?: number | null }): Promise<void>;
5  delete(key: string): Promise<boolean | void>;
6}

Configuring Redis

The @keyv/redis package uses the ioredis package under the hood. The second options argument is passed through to the ioredis.Redis constructor. See the ioredis docs for a list of available options.

Start by installing the required packages:

1npm install keyv @keyv/redis @apollo/utils.keyvadapter

Single instance

1import Keyv from "keyv";
2import { KeyvAdapter } from "@apollo/utils.keyvadapter";
3
4const server = new ApolloServer({
5  typeDefs,
6  resolvers,
7  csrfPrevention: true,
8  cache: new KeyvAdapter(new Keyv("redis://user:pass@localhost:6379")),
9  plugins: [
10    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
11  ],
12});

Redis Sentinel

1import Keyv from "keyv";
2import { KeyvAdapter } from "@apollo/utils.keyvadapter";
3
4const server = new ApolloServer({
5  typeDefs,
6  resolvers,
7  csrfPrevention: true,
8  cache: new KeyvAdapter(
9    new Keyv("redis://user:pass@localhost:6379", {
10      sentinels: [
11        { host: "localhost", port: 26379 },
12        { host: "localhost", port: 26380 },
13      ],
14    })
15  ),
16  plugins: [
17    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
18  ],
19});

Redis Cluster

The @keyv/redis package doesn't support ioredis.Cluster out of the box. Instead, we can create our own ioredis.Cluster instance and pass that to keyv as the store object. See the ioredis.Cluster docs for a list of available options.

Start by installing the packages we'll need:

1npm install keyv @keyv/redis ioredis @apollo/utils.keyvadapter

1import Keyv from "keyv";
2import KeyvRedis from "@keyv/redis";
3import Redis from "ioredis";
4import { KeyvAdapter } from "@apollo/utils.keyvadapter";
5
6const cluster = new Redis.Cluster([
7  { host: "localhost", port: 26379 },
8  { host: "localhost", port: 26380 },
9]);
10
11const server = new ApolloServer({
12  typeDefs,
13  resolvers,
14  csrfPrevention: true,
15  cache: new KeyvAdapter(new Keyv({ store: new KeyvRedis(cluster) }), {
16    disableBatchReads: true,
17  }),
18  plugins: [
19    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
20  ],
21});

Note the disableBatchReads option. This disables batching which isn't supported by ioredis.Cluster.

Configuring Memcache

The @keyv/memcache package uses the memjs package under the hood. Its second options argument is passed to memjs.Client.create(). See the memjs docs for a list of available options.

Start by installing the required packages:

1npm install keyv @keyv/memcache @apollo/utils.keyvadapter

1import Keyv from "keyv";
2import KeyvMemcache from "@keyv/memcache";
3import { KeyvAdapter } from "@apollo/utils.keyvadapter";
4
5// servers is a comma-separated list of strings
6const servers = [
7  "user:pass@localhost:11211",
8  "user:pass@localhost:11222"
9].join(",");
10
11const memcache = new KeyvMemcache(servers, {
12  retries: 10,
13  expires: 60,
14});
15
16const server = new ApolloServer({
17  typeDefs,
18  resolvers,
19  csrfPrevention: true,
20  cache: new KeyvAdapter(new Keyv({ store: memcache })),
21  plugins: [
22    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
23  ],
24});

Legacy caching implementation

Versions of Apollo Server prior to 3.9 use the apollo-server-caching package to implement caching. The apollo-server-caching package is no longer maintained, and we do not recommend using it. The KeyValueCache interface has been moved and is now in the @apollo/utils.keyvaluecache package.

The InMemoryLRUCache class has also moved to the @apollo/utils.keyvaluecache package. The InMemoryLRUCache class now uses version 7 of lru-cache, accepting different configuration options and no longer allowing a cache to be unbounded.

The apollo-server-cache-redis and apollo-server-cache-memcached packages are no longer receiving updates; we recommend using keyv instead, as shown above.