choosing & FAQ

Pick the right adapter for your stack and answer common questions about persistence, scoped roles, idempotency, and migration.

Quick comparison

Adapter	Use case	Persistence	Peer dep	Idempotent assign	Native scoped roles
Memory	Dev, testing	None	None	yes (in-memory check)	yes
File	CLIs, dev fixtures, single-process	JSON on disk	`node:fs/promises` (pluggable)	yes (in-memory check)	yes
Prisma	Prisma apps	Any DB	`@prisma/client`	no (throws on dup)	yes
Drizzle	Drizzle apps	PG/MySQL/SQLite	`drizzle-orm`	yes (`onConflictDoNothing`)	yes
Redis	Distributed deploys	Redis	`ioredis` or `redis`	yes (set semantics)	yes
HTTP	Microservice split	Remote API	None	depends on backend	yes

All adapters are interchangeable. Engine, builder, and middleware code stays the same - migration is data movement only.

Decision tree

Are you in production?
|
+- No
|  +- Need persistence between runs? -> IamFileAdapter
|  +- Otherwise                      -> IamMemoryAdapter
|
+- Yes
   |
   +- CLI / single-process daemon? -> IamFileAdapter
   +- Already use Prisma?           -> IamPrismaAdapter
   +- Already use Drizzle?          -> IamDrizzleAdapter
   +- Need distributed cache + multi-instance? -> IamRedisAdapter
   +- Splitting auth across services? -> IamHttpAdapter (consume centrally)
   +- Custom backend?               -> Implement IamAdapter.IAdapter (see "Custom" doc)

FAQ

What does an adapter actually do in duck-iam?

Does IamMemoryAdapter persist anything?

Can I seed scoped assignments in IamMemoryAdapter constructor input?

Can I use my existing database instead of a dedicated auth database?

How do IamPrismaAdapter and IamDrizzleAdapter differ in practice?

When should I pick IamRedisAdapter over Prisma or Drizzle?

Redis is best when you need distributed cache semantics - multiple app instances reading the same authorization state with sub-millisecond latency. For tens of thousands of policies or complex audit/history requirements, relational adapters scale better. Many production deployments use both: Redis as the engine adapter for hot reads, Postgres as a separate audit/source-of-truth store synced via background jobs.

Do adapters merge subject attributes or replace them?

How are duplicate role assignments handled?

Does IamHttpAdapter move policy evaluation to the server?

Can IamHttpAdapter attach auth headers dynamically?

Can I start with IamMemoryAdapter and move to Prisma, Drizzle, Redis, or HTTP later?

What should a scoped-role capable adapter guarantee?

What exactly should getSubjectRoles() return when a subject has both global and scoped assignments?

Can I implement only unscoped roles first and add multi-tenant support later?

Does the Express admin router fully satisfy IamHttpAdapter?

No. The admin router exposes /policies, /roles, and subject role-assignment endpoints, but IamHttpAdapter also expects subject-attribute reads (/subjects/:id/attributes) and scoped-role reads (/subjects/:id/scoped-roles). Treat the router as a starting point and add the remaining endpoints yourself. Same applies to the Hono bindAdminRouter, Next.js createAdminHandlers, and NestJS createAdminOperations factories.

Does IamRedisAdapter set a TTL on stored keys?

How do I isolate tenants in a shared Redis?