choosing & FAQ

An adapter is the persistence layer. It loads and stores policies, roles, role assignments, scoped assignments, and subject attributes. The engine owns evaluation, policy combination, explain traces, and decision logic.

No. It stores everything in process memory. Restarting the process resets policies, roles, assignments, and attributes, which is why it is best for tests, demos, and local development.

Not directly. Constructor assignment seeding is unscoped. For scoped assignments, create the adapter first and then call assignRole(subjectId, roleId, scope).

Yes. duck-iam only needs four storage areas for policies, roles, assignments, and subject attributes. Those can live alongside the rest of your application schema.

Prisma expects named models and lets Prisma handle JSON columns natively. Drizzle expects you to wire the tables and query operators explicitly, and the adapter serializes or parses JSON fields for you. Drizzle ships pre-built schema modules for Postgres, MySQL, and SQLite — Prisma ships a single reference schema.prisma snippet.

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.

The built-in adapters merge incoming attributes into the current subject attribute map. This lets you patch a few attributes without rewriting the entire stored object.

Memory and Redis are idempotent (in-memory check / set semantics). Drizzle uses onConflictDoNothing. Prisma currently uses create and will throw on a duplicate against the unique constraint — wrap in a try/catch or check existence first if you can't guarantee unique calls.

No. HttpAdapter fetches authorization data over HTTP, but the consuming engine still evaluates permissions locally. Use it when you want shared storage behind a service boundary, not when you want to outsource evaluation entirely.

Yes. The headers option can be a static object or an async function, which makes it suitable for short-lived bearer tokens and per-request auth state.

Yes. That is one of the intended adoption paths. The engine and builder APIs stay the same; the main migration work is moving your persisted roles, policies, assignments, and subject attributes into the new adapter's storage shape.

It should keep global role assignments and scoped assignments conceptually separate. Global assignments belong in getSubjectRoles(). Scope-bound assignments belong in getSubjectScopedRoles() so the engine can merge them only for matching request scopes.

It should return the subject's global role IDs only. Scoped assignments should be surfaced through getSubjectScopedRoles() so the engine can merge them only when the request scope matches.

Yes. A custom adapter can omit getSubjectScopedRoles() and still support the core engine. Add that method and scoped assignment storage once your application needs tenant-aware role resolution.

No. It is a useful management surface, but the HTTP adapter expects additional read endpoints and subject surfaces beyond the stock router. Treat the router as a starting point, not a drop-in backend for the full adapter contract.

No. Stored values are persistent. Engine-level caching is handled by the in-process LRU with its cacheTTL option — Redis is the source of truth, not a TTL cache. Configure Redis persistence (AOF/RDB) if you don't want data loss on restart.

Use keyPrefix per tenant. Two adapters with different prefixes cannot read each other's keys. Combine with separate Redis logical databases (SELECT n) for stronger isolation.