December 19, 2022

Prisma Client Just Became a Lot More Flexible: Prisma Client Extensions (Preview)

stephenking
Stephen King
@stephenkingdev

Prisma Client extensions (in Preview) enable many new use cases. This article will explore various ways you can use extensions to add custom functionality to Prisma Client.

Table Of Contents

Introduction

Prisma Client extensions provide a powerful new way to add functionality to Prisma in a type-safe manner. With them, you'll be able to create simple, flexible solutions to problems that aren't natively supported by the ORM (yet). You can define extensions in TypeScript or JavaScript, compose them, and even create multiple lightweight Prisma Client instances with different extensions.

When you're ready, you can share your extensions with the community as code snippets or by packaging them and publishing them to npm. This article will show you what's possible with extensions and hopefully inspires you to create and share your own!

Note: We believe Prisma Client extensions will open up many new possibilities when working with Prisma. However, just because a problem can be solved with an extension doesn't mean it won't ever be addressed with a first-class feature. One of our goals is to experiment and explore solutions with our community before integrating them into Prisma natively.

Using Prisma Client extensions

To use Prisma Client extensions, you'll need to first enable the clientExtensions preview feature in your Prisma schema file:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["clientExtensions"]
}

Then, you can call the $extends method on a Prisma Client instance. This will return a new, "extended" client instance without modifying the original instance. You can chain calls to $extends to use multiple extensions, and create separate instances with different extensions:

const prisma = new PrismaClient();
const extendedPrisma = prisma.$extends(myExtensionA).$extends(myExtensionB);

The components of an extension

There are four different types of components that can be included in an extension:

  • Model components allow you to add new methods to models. This is a convenient way to add new operations alongside default methods like findMany, create, etc. You can use this as a repository of common query methods, encapsulate business logic for models, or do anything you might do with a static method on a class.
  • Client components can be used to add new top-level methods to Prisma Client itself. Use this to extend the client with functionality that isn't tied to specific models.
  • Query components let you hook into the query lifecycle and perform side effects, modify query arguments, or alter the results in a type-safe way. These are an alternative to middleware that provide full type safety and can be applied ad-hoc to different extended client instances.
  • Result components add custom fields and methods to query result objects. These allow you to implement virtual / computed fields, define business logic for model instances in a single place, and transform the data returned by your queries.

A single extension can include one or more components, as well as an optional name to display in error messages:

const prisma = new PrismaClient().$extends({
  name: "myExtension",
  model: { /* ... */ },
  client: { /* ... */ },
  query: { /* ... */ },
  result: { /* ... */ },
});

To see the full syntax for defining each type of extension component, please refer to the docs.

Sharing an extension

You can use the Prisma.defineExtension utility to define an extension that can be shared with other users:

import { Prisma } from "@prisma/client";


export default Prisma.defineExtension({
  model: {
    $allModels: {
      // new method
      findOrCreate(...) { } // code for the new method goes inside the brackets
    },
  },
});

When publishing shared extensions to npm, we recommend using the prisma-extension-<package-name> convention. This will make it easier for users to find and install your extension in their apps.

For example, if you publish an extension with the package name prisma-extension-find-or-create, users can install it like:

npm install prisma-extension-find-or-create

And then use the extension in their app:

import { PrismaClient } from "@prisma/client";
import findOrCreate from "prisma-extension-find-or-create";


const prisma = new PrismaClient().$extends(findOrCreate);
const user = await prisma.user.findOrCreate({ /* ... */ });

Read our documentation on sharing extensions for more details.

Sample use cases

We have compiled a list of use cases that might be solved with extensions, and we've created some examples of how these extensions could be written. Let's take a look at these use cases and their implementations:

Note: Prisma Client extensions are still in Preview, and some of the examples below may have some limitations. Where known, caveats are listed in the example README files on GitHub.

Example: Computed fields

View full example on GitHub

This example demonstrates how to create a Prisma Client extension that adds virtual / computed fields to a Prisma model. These fields are not included in the database, but rather are computed at runtime.

Computed fields are type-safe and may return anything from simple values to complex objects, or even functions that can act as instance methods for your models. Computed fields must specify which other fields they depend on, and they may be composed / reused by other computed fields.

import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient()
  .$extends({
    result: {
      user: {
        fullName: {
          needs: { firstName: true, lastName: true },
          compute(user) {
            return `${user.firstName} ${user.lastName}`;
          },
        },
      },
    },
  })
  .$extends({
    result: {
      user: {
        displayName: {
          needs: { fullName: true, email: true },
          compute(user) {
            return `${user.fullName} <${user.email}>`;
          },
        },
      },
    },
  });

Example: Transformed fields

View full example on GitHub

This example shows how to use a Prisma Client extension to transform fields in results returned by Prisma queries. In the example, a date field is transformed to a relative string for a specific locale.

This shows a way to implement internationalization (i18n) at the data access layer in your application. However, this technique could allow you to implement any kind of custom transformation or serialization/deserialization of fields on your query results.

import { formatDistanceToNow } from "date-fns";
import { de } from "date-fns/locale";
import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient().$extends({
  result: {
    post: {
      createdAt: {
        needs: { createdAt: true },
        compute(post) {
          return formatDistanceToNow(post.createdAt, {
            addSuffix: true,
            locale: de,
          });
        },
      },
    },
  },
});

Example: Obfuscated fields

View full example on GitHub

This example is a special case for the previous Transformed fields example. It uses an extension to hide a sensitive password field on a User model. The password column is not included in selected columns in the underlying SQL queries, and it will resolve to undefined when accessed on a user result object. It could also resolve to any other value, such as an obfuscated string like "********".

import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient().$extends({
  result: {
    user: {
      password: {
        needs: {},
        compute() {
          return undefined;
        },
      },
    },
  },
});

Example: Instance methods

View full example on GitHub

This example shows how to add an Active Record-like interface to Prisma result objects. It uses a result extension to add save and delete methods directly to User model objects returned by Prisma Client methods.

This technique can be used to customize Prisma result objects with behavior, analogous to adding instance methods to model classes.

import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient().$extends({
  result: {
    user: {
      save: {
        needs: { id: true, email: true },
        compute({ id, email }) {
          return () => prisma.user.update({ where: { id }, data: { email } });
        },
      },


      delete: {
        needs: { id: true },
        compute({ id }) {
          return () => prisma.user.delete({ where: { id } });
        },
      },
    },
  },
});

Example: Static methods

View full example on GitHub

This example demonstrates how to create a Prisma Client extension that adds signUp() and findManyByDomain() methods to a User model.

This technique can be used to abstract the logic for common queries / operations, create repository-like interfaces, or do anything you might do with a static class method.

import bcrypt from "bcryptjs";
import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient().$extends({
  model: {
    user: {
      async signUp(email: string, password: string) {
        const hash = await bcrypt.hash(password, 10);
        return prisma.user.create({
          data: {
            email,
            password: {
              create: {
                hash,
              },
            },
          },
        });
      },


      async findManyByDomain(domain: string) {
        return prisma.user.findMany({
          where: { email: { endsWith: `@${domain}` } },
        });
      },
    },
  },
});

Example: Model filters

View full example on GitHub

This example demonstrates a Prisma Client extension which adds reusable filters for a model that can be composed and passed to a query's where condition. Complex, frequently used filtering conditions can be written once and accessed in many queries through the extended Prisma Client instance.

import { PrismaClient } from "@prisma/client";


const prisma = new PrismaClient().$extends({
  model: {
    post: {
      unpublished: () => ({ published: false }),
      published: () => ({ published: true }),
      byAuthor: (authorId: string) => ({ authorId }),
      byAuthorDomain: (domain: string) => ({
        author: { email: { endsWith: `@${domain}` } },
      }),
      hasComments: () => ({ comments: { some: {} } }),
      hasRecentComments: (date: Date) => ({
        comments: { some: { createdAt: { gte: date } } },
      }),
      titleContains: (search: string) => ({ title: { contains: search } }),
    } satisfies Record<string, (...args: any) => Prisma.PostWhereInput>,
  },
});

Example: Readonly client

View full example on GitHub

This example creates a client that only allows read operations like findMany and count, not write operations like create or update. Calling write operations will result in an error at runtime and at compile time with TypeScript.

import { Prisma, PrismaClient } from "@prisma/client";


const WRITE_METHODS = [
  "create",
  "update",
  "upsert",
  "delete",
  "createMany",
  "updateMany",
  "deleteMany",
] as const;


const ReadonlyClient = Prisma.defineExtension({
  name: "ReadonlyClient",
  model: {
    $allModels: Object.fromEntries(
      WRITE_METHODS.map((method) => [
        method,
        function (args: never) {
          throw new Error(
            `Calling the \`${method}\` method on a readonly client is not allowed`
          );
        },
      ])
    ) as {
      [K in typeof WRITE_METHODS[number]]: (
        args: `Calling the \`${K}\` method on a readonly client is not allowed`
      ) => never;
    },
  },
});


const prisma = new PrismaClient();
const readonlyPrisma = prisma.$extends(ReadonlyClient);

Example: Input transformation

View full example on GitHub

This example creates an extended client instance which modifies query arguments to only include published posts.

Since query extensions allow modifying query arguments, it's possible to apply various kinds of default filters with this approach.

const prisma = new PrismaClient().$extends({
  query: {
    post: {
      $allOperations({ args, query, operation }) {
        // Do nothing for `create`
        if (operation === "create") {
          return query(args);
        }


        // Refine the type - methods other than `create` accept a `where` clause
        args = args as Extract<typeof args, { where: unknown }>;


        // Augment the `where` clause with `published: true`
        return query({
          ...args,
          where: {
            ...args.where,
            published: true,
          },
        });
      },
    },
  },
});

Example: Input validation

View full example on GitHub

This example uses Prisma Client extensions to perform custom runtime validations when creating and updating database objects. It uses a Zod runtime schema to check that the data passed to Prisma write methods is valid.

This could be used to sanitize user input or otherwise deny mutations that do not meet some criteria defined by your business logic rules.

import { Prisma, PrismaClient } from "@prisma/client";
import { ProductCreateInput } from "./schemas";


const prisma = new PrismaClient().$extends({
  query: {
    product: {
      create({ args, query }) {
        args.data = ProductCreateInput.parse(args.data);
        return query(args);
      },
      update({ args, query }) {
        args.data = ProductCreateInput.partial().parse(args.data);
        return query(args);
      },
      updateMany({ args, query }) {
        args.data = ProductCreateInput.partial().parse(args.data);
        return query(args);
      },
      upsert({ args, query }) {
        args.create = ProductCreateInput.parse(args.create);
        args.update = ProductCreateInput.partial().parse(args.update);
        return query(args);
      },
    },
  },
});

Example: JSON Field Types

View full example on GitHub

This next example combines the approaches shown in the Input validation and Transformed fields examples to provide static and runtime types for a Json field. It uses Zod to parse the field data and infer static TypeScript types.

This example includes a User model with a JSON profile field, which has a sparse structure that may vary between users. The extension has two parts:

  • A result extension that adds a computed profile field. This field uses the Profile Zod schema to parse the underlying untyped profile field. TypeScript infers the static data type from the parser, so query results have both static and runtime type safety.
  • A query extension that parses the profile field on input data for the User model's write methods like create and update.
import { Prisma, PrismaClient } from "@prisma/client";
import { Profile } from "./schemas";


const prisma = new PrismaClient().$extends({
  result: {
    user: {
      profile: {
        needs: { profile: true },
        compute({ profile }) {
          return Profile.parse(profile);
        },
      },
    },
  },


  query: {
    user: {
      create({ args, query }) {
        args.data.profile = Profile.parse(args.data.profile);
        return query(args);
      },
      createMany({ args, query }) {
        const users = Array.isArray(args.data) ? args.data : [args.data];
        for (const user of users) {
          user.profile = Profile.parse(user.profile);
        }
        return query(args);
      },
      update({ args, query }) {
        if (args.data.profile !== undefined) {
          args.data.profile = Profile.parse(args.data.profile);
        }
        return query(args);
      },
      updateMany({ args, query }) {
        if (args.data.profile !== undefined) {
          args.data.profile = Profile.parse(args.data.profile);
        }
        return query(args);
      },
      upsert({ args, query }) {
        args.create.profile = Profile.parse(args.create.profile);
        if (args.update.profile !== undefined) {
          args.update.profile = Profile.parse(args.update.profile);
        }
        return query(args);
      },
    },
  },
});

Example: Query logging

View full example on GitHub

This example shows how to use Prisma Client extensions to perform similar tasks to middleware. In this example, a query extension tracks the time it takes to fulfill each query, and logs the results along with the query and arguments themselves.

This technique could be used to perform generic logging, emit events, track usage, etc.

Note: You may be interested in the OpenTelemetry tracing and Metrics features (both in Preview), which provide detailed insights into performance and how Prisma interacts with the database.

import { PrismaClient } from "@prisma/client";
import { performance } from "perf_hooks";
import * as util from "util";


const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ operation, model, args, query }) {
        const start = performance.now();
        const result = await query(args);
        const end = performance.now();
        const time = end - start;
        console.log(
          util.inspect(
            { model, operation, args, time },
            { showHidden: false, depth: null, colors: true }
          )
        );
        return result;
      },
    },
  },
});

Example: Retry transactions

View full example on GitHub

This example shows how to use a Prisma Client extension to automatically retry transactions that fail due to a write conflict / deadlock timeout. Failed transactions will be retried with exponential backoff and jitter to reduce contention under heavy traffic.

import { backOff, IBackOffOptions } from "exponential-backoff";
import { Prisma, PrismaClient } from "@prisma/client";


function RetryTransactions(options?: Partial<IBackOffOptions>) {
  return Prisma.defineExtension((prisma) =>
    prisma.$extends({
      client: {
        $transaction(...args: any) {
          return backOff(() => prisma.$transaction.apply(prisma, args), {
            retry: (e) => {
              // Retry the transaction only if the error was due to a write conflict or deadlock
              // See: https://www.prisma.io/docs/orm/reference/error-reference#p2034
              return e.code === "P2034";
            },
            ...options,
          });
        },
      } as { $transaction: typeof prisma["$transaction"] },
    })
  );
}


const prisma = new PrismaClient().$extends(
  RetryTransactions({
    jitter: "full",
    numOfAttempts: 5,
  })
);

Example: Callback-free interactive transactions

View full example on GitHub

This example shows a Prisma Client extension which adds a new API for starting interactive transactions without callbacks.

This gives you the full power of interactive transactions (such as read–modify–write cycles), but in a more imperative API. This may be more convenient than the normal callback-style API for interactive transactions in some scenarios.

import { Prisma, PrismaClient } from "@prisma/client";


type FlatTransactionClient = Prisma.TransactionClient & {
  $commit: () => Promise<void>;
  $rollback: () => Promise<void>;
};


const ROLLBACK = { [Symbol.for("prisma.client.extension.rollback")]: true };


const prisma = new PrismaClient().$extends({
  client: {
    async $begin() {
      const prisma = Prisma.getExtensionContext(this);
      let setTxClient: (txClient: Prisma.TransactionClient) => void;
      let commit: () => void;
      let rollback: () => void;


      // a promise for getting the tx inner client
      const txClient = new Promise<Prisma.TransactionClient>((res) => {
        setTxClient = (txClient) => res(txClient);
      });


      // a promise for controlling the transaction
      const txPromise = new Promise((_res, _rej) => {
        commit = () => _res(undefined);
        rollback = () => _rej(ROLLBACK);
      });


      // opening a transaction to control externally
      if (
        "$transaction" in prisma &&
        typeof prisma.$transaction === "function"
      ) {
        const tx = prisma.$transaction((txClient) => {
          setTxClient(txClient);


          return txPromise.catch((e) => {
            if (e === ROLLBACK) return;
            throw e;
          });
        });


        // return a proxy TransactionClient with `$commit` and `$rollback` methods
        return new Proxy(await txClient, {
          get(target, prop) {
            if (prop === "$commit") {
              return () => {
                commit();
                return tx;
              };
            }
            if (prop === "$rollback") {
              return () => {
                rollback();
                return tx;
              };
            }
            return target[prop as keyof typeof target];
          },
        }) as FlatTransactionClient;
      }


      throw new Error("Transactions are not supported by this client");
    },
  },
});

Example: Audit log context

View full example on GitHub

This example shows how to use a Prisma Client extension to provide the current application user's ID as context to an audit log trigger in Postgres. User IDs are included in an audit trail tracking every change to rows in a table.

A detailed explanation of this solution can be found in the example's README on GitHub.

import { Prisma, PrismaClient } from "@prisma/client";


function forUser(userId: number) {
  return Prisma.defineExtension((prisma) =>
    prisma.$extends({
      query: {
        $allModels: {
          async $allOperations({ args, query }) {
            const [, result] = await prisma.$transaction([
              prisma.$executeRaw`SELECT set_config('app.current_user_id', ${userId.toString()}, TRUE)`,
              query(args),
            ]);
            return result;
          },
        },
      },
    })
  );
}

Example: Row level security

View full example on GitHub

This example shows how to use a Prisma Client extension to isolate data between tenants in a multi-tenant app using Row Level Security (RLS) in Postgres.

A detailed explanation of this solution can be found in the example's README on GitHub.

import { Prisma, PrismaClient } from "@prisma/client";


function bypassRLS() {
  return Prisma.defineExtension((prisma) =>
    prisma.$extends({
      query: {
        $allModels: {
          async $allOperations({ args, query }) {
            const [, result] = await prisma.$transaction([
              prisma.$executeRaw`SELECT set_config('app.bypass_rls', 'on', TRUE)`,
              query(args),
            ]);
            return result;
          },
        },
      },
    })
  );
}


function forCompany(companyId: string) {
  return Prisma.defineExtension((prisma) =>
    prisma.$extends({
      query: {
        $allModels: {
          async $allOperations({ args, query }) {
            const [, result] = await prisma.$transaction([
              prisma.$executeRaw`SELECT set_config('app.current_company_id', ${companyId}, TRUE)`,
              query(args),
            ]);
            return result;
          },
        },
      },
    })
  );
}

Tell us what you think

We hope you are as excited as we are about the possibilities that Prisma Client extensions create!

💡 You can share your feedback with us in this GitHub issue.

🌍 We also invite you to join our Slack where you can discuss all things Prisma, share general product feedback in the #product-feedback channel and get help from the community.

ReleasePrisma ORM

Don’t miss the next post!

Sign up for the Prisma Newsletter

Key takeaways from the Discover Data DX virtual event

December 13, 2023

Explore the insights from the Discover Data DX virtual event held on December 7th, 2023. The event brought together industry leaders to discuss the significance and principles of the emerging Data DX category.

Announcement

Prisma Accelerate now in General Availability

October 26, 2023

Now in General Availability: Dive into Prisma Accelerate, enhancing global database connections with connection pooling and edge caching for fast data access.

AnnouncementData Platform

Support for Serverless Database Drivers in Prisma ORM Is Now in Preview

October 06, 2023

Prisma is releasing Preview support for serverless database drivers from Neon and PlanetScale. This feature allows Prisma users to leverage the existing database drivers for communication with their database without long-lived TCP connections!

Prisma ORMServerlessRelease

Product

ClientMigrate
Accelerate
PulseEarly Access
Pricing

Developers

DocsGet StartedPrisma ExamplesData GuidePrisma in your StackSupportCommunityData Platform StatusVS Code Extension

Use Cases

Customer StoriesEnterprise

Company

AboutBlogCareers EventsCausesTerms & PrivacyService Level Agreement

Newsletter

prisma_logo
© 2024 Prisma Data, Inc.