Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createRlsExtension
✓ import { createRlsExtension } from 'prisma-rls';
✗ const { createRlsExtension } = require('prisma-rls');
Primary entry point for creating the RLS extension; `require()` is not supported for this ESM-first library.
PermissionsConfig
✓ import { PermissionsConfig } from 'prisma-rls';
✗ import type { PermissionsConfig } from 'prisma-rls';
This is a runtime value, not just a type, as it defines the structure for permissions at runtime.
ExtensionOptions
✓ import type { ExtensionOptions } from 'prisma-rls';
✗ import { ExtensionOptions } from 'prisma-rls';
This is a TypeScript type, so use `import type` for clarity and to avoid bundling issues.
This example demonstrates how to integrate `prisma-rls` with a Fastify server to apply row-level security based on user roles and context. It defines permissions for 'User' and 'Guest' roles, creates a dynamic Prisma client extension per request, and applies RLS to `Post` and `User` model queries. Authorization is simulated via a bearer token.
import { Prisma, PrismaClient } from "@prisma/client";
import Fastify, { FastifyRequest } from "fastify";
import { createRlsExtension, PermissionsConfig } from "prisma-rls";
// Define shared types for roles and permissions context
export type Role = "User" | "Guest";
export type PermissionsContext = { userId: string | null };
export type RolePermissions = PermissionsConfig<Prisma.TypeMap, PermissionsContext>;
export type PermissionsRegistry = Record<Role, RolePermissions>;
// Define user permissions
const userPermissions: RolePermissions = {
Post: {
read: { published: { equals: true } },
create: true,
update: (ctx) => ({ authorId: { equals: ctx.userId } }),
delete: (ctx) => ({ authorId: { equals: ctx.userId } })
},
User: {
read: (ctx) => ({ id: { equals: ctx.userId } }),
create: false,
update: (ctx) => ({ id: { equals: ctx.userId } }),
delete: false
}
};
// Define guest permissions
const guestPermissions: RolePermissions = {
Post: {
read: { published: { equals: true } },
create: false,
update: false,
delete: false
},
User: {
read: false,
create: false,
update: false,
delete: false
}
};
// Combine permissions into a registry
export const permissionsRegistry = {
User: userPermissions,
Guest: guestPermissions
} satisfies PermissionsRegistry;
(async () => {
const prisma = new PrismaClient();
const server = Fastify();
// Dummy function to resolve user from auth header
const resolveUser = async (authorizationHeader?: string | string[] | undefined) => {
if (authorizationHeader === 'Bearer user-token') {
return { id: 'user-123', role: 'User' };
}
return null;
};
server.decorateRequest('db', null);
server.addHook('onRequest', async (request: any, reply) => {
const user = await resolveUser(request.headers.authorization);
const userRole: Role = user ? user.role : "Guest";
const permissionsContext: PermissionsContext = { userId: user?.id ?? null };
const rlsExtension = createRlsExtension({
dmmf: Prisma.dmmf,
permissionsConfig: permissionsRegistry[userRole],
context: permissionsContext,
});
request.db = prisma.$extends(rlsExtension);
});
server.get("/posts", async function handler(request: any, reply) {
// Assuming a user with 'user-token' can only see their own posts
// and public posts. Guests can only see public posts.
return await request.db.post.findMany();
});
server.get("/profile", async function handler(request: any, reply) {
// A user can only see their own profile, guests see nothing.
return await request.db.user.findMany(); // Will apply RLS based on `userId`
});
await server.listen({ port: 8080, host: "0.0.0.0" });
console.log('Server listening on http://0.0.0.0:8080');
})();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'id')
The `PermissionsContext` object or a property within it (e.g., `user` or `user.id`) is `null` or `undefined` when a permission function tries to access it.
fixEnsure that your `PermissionsContext` object is always fully populated with expected values, or add null-checking/optional chaining within your permission functions, for example: `permissionContext.user?.id`.
PrismaClientKnownRequestError: Argument 'where' must not be empty.
A permission function evaluated to an empty `where` object when a non-empty `where` clause was expected, potentially due to a context issue or a misconfigured permission that disallows access entirely (e.g., `false`).
fixReview the permission definition for the specific model and operation. Ensure the permission function returns a valid `where` object or `true` for allowed access, or `false` for explicit denial, rather than an implicitly empty object.
Audit
Dependencies
@prisma/clientrequiredRequired Prisma Client for extension functionality and type generation.