Prisma adapter
@anievo-id/rbac-evolution-prisma stores roles and permissions through your existing Prisma client. It works with every relational connector Prisma supports. MongoDB is the exception.
Install
npm i @anievo-id/rbac-evolution @anievo-id/rbac-evolution-prismapnpm add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-prismayarn add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-prismabun add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-prismaPrisma itself (@prisma/client and the prisma CLI) is a peer dependency, and a Prisma project already has it installed.
Prisma version
Use @prisma/client 5.12 or later, or 6. Prisma 7 is not supported yet. Older versions don't support createMany on SQLite, and the adapter needs it.
1. Add the models to your schema
Copy these five models into schema.prisma. If your schema is split into a folder (prismaSchemaFolder), you can instead copy the file that ships with the package, node_modules/@anievo-id/rbac-evolution-prisma/schema/rbac.prisma, into that folder unchanged.
model RbacPermission {
id Int @id @default(autoincrement())
name String
guardName String @map("guard_name")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
roles RbacRoleHasPermission[]
subjects RbacModelHasPermission[]
@@unique([name, guardName])
@@map("permissions")
}
model RbacRole {
id Int @id @default(autoincrement())
teamId String @default("") @map("team_id")
name String
guardName String @map("guard_name")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
permissions RbacRoleHasPermission[]
subjects RbacModelHasRole[]
@@unique([name, guardName, teamId])
@@index([teamId])
@@map("roles")
}
model RbacRoleHasPermission {
permissionId Int @map("permission_id")
roleId Int @map("role_id")
permission RbacPermission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
role RbacRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
@@id([roleId, permissionId])
@@index([permissionId])
@@map("role_has_permissions")
}
model RbacModelHasRole {
roleId Int @map("role_id")
subjectType String @map("subject_type")
subjectId String @map("subject_id")
teamId String @default("") @map("team_id")
role RbacRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
@@id([roleId, subjectType, subjectId, teamId])
@@index([subjectType, subjectId, teamId])
@@map("model_has_roles")
}
model RbacModelHasPermission {
permissionId Int @map("permission_id")
subjectType String @map("subject_type")
subjectId String @map("subject_id")
teamId String @default("") @map("team_id")
permission RbacPermission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
@@id([permissionId, subjectType, subjectId, teamId])
@@index([subjectType, subjectId, teamId])
@@map("model_has_permissions")
}What you may rename
- Model names: keep them. The adapter calls
prisma.rbacPermission,prisma.rbacRole,prisma.rbacRoleHasPermission,prisma.rbacModelHasRoleandprisma.rbacModelHasPermissionby name. - Field names: keep them. The adapter queries
name,guardName,teamId,subjectTypeand the rest. - Table and column names: change them freely. Edit the
@@mapand@mapvalues, for example@@map("rbac_roles")if you already have arolestable.
2. Create the tables
npx prisma migrate dev --name rbacnpx prisma db pushBoth commands also run prisma generate, so the new delegates show up on your client.
3. Use it
// lib/rbac.ts
import { PrismaClient } from '@prisma/client'
import { createRbac } from '@anievo-id/rbac-evolution'
import { PrismaAdapter } from '@anievo-id/rbac-evolution-prisma'
export const prisma = new PrismaClient()
export const rbac = createRbac({ adapter: new PrismaAdapter(prisma) })import { rbac } from './lib/rbac'
await rbac.createPermission('edit articles')
await rbac.createRole('writer')
await rbac.role('writer').givePermissionTo('edit articles')
const user = rbac.for({ type: 'user', id: currentUser.id })
await user.assignRole('writer')
await user.can('edit articles') // trueThe adapter doesn't import @prisma/client itself. It accepts any object that has the five delegates and $transaction, which means it also works with:
- a custom generator
outputpath (import { PrismaClient } from './generated/client'), - a schema with many other models,
- clients extended with
$extends(...).
Teams
const rbac = createRbac({ adapter: new PrismaAdapter(prisma), teams: true })
await rbac.createRole('admin') // global role
await rbac.for(user, { team: org.id }).assignRole('admin')See Teams for how global roles and team roles work together.
Options
new PrismaAdapter(prisma, options?)| Option | Type | Default | Description |
|---|---|---|---|
skipDuplicates | boolean | false | Use createMany({ skipDuplicates: true }) for every attach, so it runs as a single race-free INSERT ... ON CONFLICT DO NOTHING / INSERT IGNORE. Only supported on PostgreSQL, CockroachDB, MySQL and MariaDB. |
With the default (false), each attach reads the links that already exist and inserts only the missing ones. If another request inserts the same link in the meantime (Prisma error P2002), the adapter reads again and retries. This mode works on every connector.
// PostgreSQL / MySQL / MariaDB / CockroachDB
const adapter = new PrismaAdapter(prisma, { skipDuplicates: true })How values come back
| Value | Stored as | Returned as |
|---|---|---|
Role / permission id | autoincrement Int | number. Numeric strings like '42' are accepted as input. |
| Subject id | subject_id text | Reverse lookups return strings. 1 and '1' are the same subject. |
Role.teamId | team_id text, '' = global | null for global roles, otherwise a string ('7') |
When the engine passes an id that isn't an integer to an attach method, the adapter throws a TypeError (PrismaAdapter: invalid role id ...). Lookups and detaches skip such ids instead.
Database notes
| Database | Notes |
|---|---|
| PostgreSQL / CockroachDB | String maps to text, no changes needed. Turn on skipDuplicates: true. |
| MySQL / MariaDB | String maps to VARCHAR(191), which keeps the composite keys under InnoDB's 3072-byte index limit with utf8mb4. Don't change these fields to @db.Text, because MySQL can't index a whole TEXT column. Turn on skipDuplicates: true. The columns use the database's default collation, which is usually case- and accent-insensitive. The adapter compares every row it reads exactly, so a subject 'ABC' or 'abc ' never gets the roles of 'abc'. The unique keys still follow the collation, though: 'Edit' next to 'edit', or a role for 'ABC' while 'abc' holds it, is rejected or skipped. If your names or ids are case-sensitive, give the database or tables a binary collation without padding: utf8mb4_0900_bin (MySQL 8) or utf8mb4_nopad_bin (MariaDB). utf8mb4_bin still ignores trailing spaces. |
| SQLite | Keep the default skipDuplicates: false. The connector doesn't support it. |
| SQL Server | Keep the default skipDuplicates: false. The connector doesn't support it. |
| MongoDB | Not supported. The schema relies on autoincrement ids and composite primary keys. |
More things to know:
- Deletes are transactional.
deleteRoleanddeletePermissionremove the link rows and the row itself in one$transaction. Because of this, theonDelete: Cascaderelations are only a safety net, and the adapter also works withrelationMode = "prisma". - Uniqueness. The engine checks names before inserting, and the unique constraints enforce them. If two requests race to create the same name, the second one fails with Prisma's
P2002error. - Interactive transactions. The adapter calls
$transaction([...])with an array, and the client you get insideprisma.$transaction(async (tx) => ...)has no$transactionmethod. Build the adapter on the root client.
Cache across instances
The default cache lives in process memory. If you run several app instances against one database, read Cache: multiple processes.
How it's tested
The adapter runs the shared conformance suite (runAdapterTests from @anievo-id/rbac-evolution/testing) against clients generated from the shipped schema/rbac.prisma:
| Database | When |
|---|---|
| SQLite | every test run |
| PostgreSQL 16 | when PG_URL is set (CI databases job) |
| MySQL 8 | when MYSQL_URL is set (CI databases job) |
PostgreSQL and MySQL are tested with both skipDuplicates: false and skipDuplicates: true. Without the variables, those suites show up as skipped. To run them locally, point the variables at a server you can create databases on; the schema is pushed into a dedicated rbac_evolution_prisma_test database, which is reset on every run:
PG_URL=postgresql://postgres:postgres@localhost:5432/postgres \
MYSQL_URL=mysql://root:root@127.0.0.1:3306/mysql \
pnpm --filter @anievo-id/rbac-evolution-prisma testThe other connectors (MariaDB, SQL Server, CockroachDB) use the same models but aren't covered by CI.
Seeding
Seed scripts can run more than once if you use the findOrCreate* helpers:
// prisma/seed.ts
import { rbac, prisma } from '../lib/rbac'
const permissions = ['view articles', 'edit articles', 'delete articles']
for (const name of permissions) await rbac.findOrCreatePermission(name)
await rbac.findOrCreateRole('writer')
await rbac.role('writer').syncPermissions('view articles', 'edit articles')
await rbac.findOrCreateRole('admin')
await rbac.role('admin').syncPermissions(permissions)
await prisma.$disconnect()