prisma-redis-middleware

prisma-redis-middleware

This is a Prisma middleware used for caching and storing of Prisma queries in Redis (uses an in-memory LRU cache as fallback storage).

Uses async-cache-dedupe.

Features

• Cache Invalidation
• Supports custom cache keys
• Cache persistance with Redis (uses an in-memory LRU cache as fallback)
• Caching multiple Prisma models each with a specific cache time
• Excluding certain Prisma models from being cached
• Excluding certain Prisma queries from being cached across all models

Supported Node.js versions

The latest versions of the following Node.js versions are tested and supported.

• 12
• 14
• 16

Default Cached Methods

Here is a list of all the Prisma methods that are currently cached by default in prisma-redis-middleware.

• findUnique
• findFirst
• findMany
• count
• aggregate
• groupBy
• findRaw
• aggregateRaw

queryRaw is not cached as it's executed against the Prisma db itself and not a model. This Prisma middleware is used for caching queries based on the models that they are executed against.

Quick Start

Install the package using npm:

npm i --save-exact prisma-redis-middleware

or yarn:

yarn add prisma-redis-middleware

or pnpm:

pnpm add prisma-redis-middleware

You will also need to install and configure an external dependency for Redis (for example: ioredis or one that uses a similar API) if you don't already have a Redis Client in your project.

npm i --save-exact ioredis

Code Example (ESM / Import)

import Prisma from "@prisma/client";
import { createPrismaRedisCache } from "prisma-redis-middleware";
import Redis from "ioredis";

const redis = new Redis(); // Uses default options for Redis connection

const prismaClient = new Prisma.PrismaClient();

prismaClient.$use(
  createPrismaRedisCache({
    models: [
      { model: "User", cacheTime: 60, excludeCacheMethods: "findMany" },
      { model: "Post", cacheTime: 180, cacheKey: "article" },
    ],
    storage: { type: "redis", options: { client: redis, invalidation: { referencesTTL: 300 }, log: console } },
    defaultCacheTime: 300,
    defaultExcludeCacheModels: ["Product", "Cart"],
    defaultExcludeCacheMethods: ["count", "groupby"],
    onDedupe: (key) => {
      console.log("deduped", key);
    },
    onHit: (key) => {
      console.log("hit", key);
    },
    onMiss: (key) => {
      console.log("miss", key);
    },
    onError: (key) => {
      console.log("error", key);
    },
  }),
);

Code Example (Common JS / Require)

const { PrismaClient } = require("@prisma/client");
const { createPrismaRedisCache } = require("prisma-redis-middleware");
const Redis = require("ioredis");

const redis = new Redis(); // Uses default options for Redis connection

const prismaClient = new PrismaClient();

prismaClient.$use(
  createPrismaRedisCache({
    models: [
      { model: "User", cacheTime: 60 },
      { model: "Post", cacheTime: 180 },
    ],
    storage: { type: "memory", options: { invalidation: true, log: console } },
    defaultCacheTime: 300,
    onDedupe: (key) => {
      console.log("deduped", key);
    },
    onHit: (key) => {
      console.log("hit", key);
    },
    onMiss: (key) => {
      console.log("miss", key);
    },
    onError: (key) => {
      console.log("error", key);
    },
  }),
);

API

createPrismaRedisCache(opts)

Options:

• onDedupe: (optional) a function that is called every time a query is deduped.

• onError: (optional) a function that is called every time there is a cache error.

• onHit: (optional) a function that is called every time there is a hit in the cache.

• onMiss: (optional) a function that is called every time the result is not in the cache.

• defaultCacheTime: (optional) (number) the default time (in ms) to use for models that don't have a cacheTime value set. Default is 0.

• defaultExcludeCacheModels: (optional) (string) an array of models to exclude from being cached.

• defaultExcludeCacheMethods: (optional) (string) an array of Prisma methods to exclude from being cached for all models.

• models: (optional) an array of Prisma models. Models options are:

  • model: (required) string.

  • cacheKey: (optional) string. Default is the model value.

  • cacheTime: (optional) number (in ms).

  • excludeCacheMethods: (optional) (string) an array of Prisma methods to exclude from being cached for this model.

    Example:

    createPrismaRedisCache({
      models: [
        { model: "User", cacheTime: 60 },
        { model: "Post", cacheKey: "article", excludeCacheMethods: ["findFirst"] },
      ],
      defaultCacheTime: 300,
    });
    

• storage: (optional) the storage options; default is { type: "memory" }. Storage options are:

  • type: memory (default) or redis

  • options: by storage type

    • for memory type

      • size: (optional) maximum number of items to store in the cache. Default is 1024.
      • invalidation: (optional) enable invalidation. Default is disabled.
      • log: (optional) logger instance pino compatible, or console, default is disabled.

      Example:

      createPrismaRedisCache({
        storage: { type: "memory", options: { size: 2048 }, log: console },
      });
      

    • for redis type

      • client: a redis client instance, mandatory. Should be an ioredis client or compatible.
      • invalidation: (optional) enable invalidation. Default is disabled.
      • invalidation.referencesTTL: (optional) references TTL in seconds, it means how long the references are alive; it should be set at the maximum of all the caches ttl.
      • log: (optional) logger instance pino compatible, or console, default is disabled.

      Example

      createPrismaRedisCache({
        storage: {
          type: "redis",
          options: { client: new Redis(), invalidation: { referencesTTL: 60 }, log: console },
        },
      });
      

Debugging

You can pass functions for onMiss, onHit, onError and onDedupe to createPrismaRedisCache which can then be used to debug whether a Prisma query is being cached or not.

You can also pass a custom log (pino or console) to the storage option and async-cache-dedupe will print debug info as it queries, sets, expires and invalidates the cache. Note that the log option can print out very verbose output.