Overview

An adapter is the only place VeguiPerms touches persistence. It stores and retrieves subjects and grants; it performs no validation, resolution, inheritance or evaluation. That guarantees identical authorization behavior across every backend.

Every adapter implements the same six-method contract from @vperms/core — see Writing a custom adapter.

Design rules

• Dependency injection. An adapter receives an already-created database client (or Drizzle instance). It never opens or closes connections.
• Explicit migration. Database adapters expose migrate(), which the application calls once at startup. Nothing touches the database implicitly.
• Upserts. grantPermission replaces the value for an existing (workspaceId, subjectId, permission); saveSubject replaces the record.
• Plain data. Subjects and grants are JSON-safe objects.

const adapter = new VeguiPermsSqliteAdapter({ db });
await adapter.migrate();

const vperms = new VeguiPermsService({ adapter });

Official adapters

Adapter	Backend	Tier
VeguiPermsMemoryAdapter	In-process memory	Reference
@vperms/drizzle-adapter/sqlite	SQLite (better-sqlite3)	SQL
@vperms/drizzle-adapter/mysql	MySQL	SQL
@vperms/drizzle-adapter/postgres	Postgres	SQL
@vperms/mongodb-adapter	MongoDB	Document

• In-memory adapter
• SQL base adapter
• Drizzle adapters
• MongoDB adapter

Contract testing

All official adapters run the same shared contract suite from the private @vperms/adapter-contract package, so behavior stays identical across backends. Unit tests include SQLite and an in-memory MongoDB; integration tests run against real databases:

bun run test             # unit tests
docker compose up -d     # MySQL, Postgres, MongoDB
bun run test:integration # same contract against real databases

Integration tests are skipped unless RUN_INTEGRATION=1 is set (the test:integration script sets it).