Cached-prisma NPM

Cached Prisma

A Prisma client abstraction that simplifies caching.

Review Version Downloads Size Quality Coverage

Motivation

Prisma bundles their caching features into Accelerate which is sold as a subscription.

Caching

It's unlikely they'll ever support caching outside of accelerate with services like Memcached and Redis. This package adds the caching logic to the prisma client for your choice of cache provider.

Performance

.-----------------------------.
|        Read x 10000         |
|-----------------------------|
|      Cache      |  time/s   |
|-----------------|-----------|
| LruCache        |  0.133111 |
| LfuCache        |  0.073968 |
| Memcached       |  0.118672 |
| Redis           |  0.071997 |
| Hazelcast       |  0.075136 |
| Without a cache | 10.554741 |
'-----------------------------'
.-----------------------------.
|  Read and overwrite x 1000  |
|-----------------------------|
|      Cache      |  time/s   |
|-----------------|-----------|
| LruCache        |  1.980747 |
| LfuCache        |  1.736129 |
| Memcached       |  1.661834 |
| Redis           |  1.650579 |
| Hazelcast       |  1.613310 |
| Without a cache |  1.562942 |
'-----------------------------'

Installing

npm install cached-prisma

Documentation

Documentation and more detailed examples are hosted on Github Pages.

Usage

import { Prisma } from "cached-prisma";

const { client } = new Prisma();

client.user.create({ data: { name: "Joel" } });

// This populates the cache
client.user.findFirst({ where: { name: "Joel" } });

// This is retrieved from the cache
client.user.findFirst({ where: { name: "Joel" } });

To control the object used for cache storage you can extend the Prisma class:

import { LruCache } from "cached-prisma";

class LruCachePrisma extends Prisma {
  static override cacheFactory = () => new LruCache(1000);
}

Caches are also provided for Memcached, Redis, and Hazelcast.

Minimal example

Create a prisma schema:

datasource db {
  url      = env("DATABASE_URL")
  provider = "postgresql"
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id   Int    @id @default(autoincrement())
  name String
}

Create a database. In this example we create a postgres container. You can switch the db, user and password for your environment.

docker run --rm -d              \
  -p 5432:5432                  \
  -e POSTGRES_DB=db             \
  -e POSTGRES_USER=user         \
  -e POSTGRES_PASSWORD=password \
  postgres

Define the DATABASE_URL environment variable mentioned in our prisma schema:

export DATABASE_URL=postgresql://user:password@localhost:5432/db

Generate the types for your client:

npx prisma generate

Migrate the database:

npx prisma migrate dev

Now we can create our client:

import { Prisma } from "cached-prisma";

const { client } = new Prisma();

client.user.create({ data: { name: "Joel" } });

Caches

LruCache

import { LruCache } from "cached-prisma";

class LruCachePrisma extends Prisma {
  static override cacheFactory = () => new LruCache(1000);
}

LfuCache

import { LfuCache } from "cached-prisma";

class LfuCachePrisma extends Prisma {
  static override cacheFactory = () => new LfuCache(1000);
}

Memcached

import { Memcached } from "cached-prisma";

class MemcachedPrisma extends Prisma {
  static override cacheFactory = () => new Memcached("0.0.0.0", 11211, 10);
}

Redis

import { Redis } from "cached-prisma";

class RedisPrisma extends Prisma {
  static override cacheFactory = () => new Redis("0.0.0.0", 6379, 10);
}

Hazelcast

import { Hazelcast } from "cached-prisma";

class HazelcastPrisma extends Prisma {
  static override cacheFactory = () => new Hazelcast("0.0.0.0", 5701, 10);
}

Design

To implement the cache we need to divert the prisma client's internals so that we can return cached values without hitting the database. To do this we can use a singleton instance for the client and cache objects.

import { Prisma } from "cached-prisma";

const client1 = new Prisma().client;
const client2 = new Prisma().client;

// These point to the same object
client1 === client2;

import { Prisma } from "cached-prisma";

const cache1 = new Prisma().cache;
const cache2 = new Prisma().cache;

// These point to the same object
cache1 === cache2;

Actions

Caches implement safe read and write methods:

export interface Cache {
  read: (key: string) => Promise<Maybe<string>>;
  write: (key: string, value: string) => Promise<void>;
  flush: () => Promise<void>;
}

We cache the following methods which do not mutate state:

findUnique
findMany
findFirst
queryRaw
aggregate
count

After any of the following state mutating methods we flush the cache:

create
createMany
delete
deleteMany
executeRaw
update
updateMany
upsert

Tooling

Dependencies

To install dependencies:

yarn install

Tests

To run tests:

Create a test database:

docker run --rm -d              \
  -p 5432:5432                  \
  -e POSTGRES_DB=db             \
  -e POSTGRES_USER=user         \
  -e POSTGRES_PASSWORD=password \
  postgres

Create test cache providers:

docker run --rm -d -p 11211:11211 memcached
docker run --rm -d -p 6379:6379 redis
docker run --rm -d -p 5701:5701 hazelcast/hazelcast

Apply the database migrations:

export DATABASE_URL=postgresql://user:password@localhost:5432/db
yarn prisma generate --schema ./test/schema.prisma
yarn prisma migrate dev --schema ./test/schema.prisma

yarn test

Documentation

To generate the documentation locally:

yarn docs

Linters

To run linters:

yarn lint

Formatters

To run formatters:

yarn format

Contributing

Please read this repository's Code of Conduct which outlines our collaboration standards and the Changelog for details on breaking changes that have been made.

This repository adheres to semantic versioning standards. For more information on semantic versioning visit SemVer.

Bump2version is used to version and tag changes. For example: