Skip to main content
The DatabaseAdapter interface defines the contract that all database adapters must implement to work with Arraf Auth. It provides a consistent API for managing users, sessions, accounts, and verifications across different database systems.

​
Overview

The adapter pattern allows Arraf Auth to work with any database system by implementing a standardized interface. This decouples the authentication logic from the specific database implementation, making it easy to switch databases or use custom storage solutions.

​
Interface Definition

interface DatabaseAdapter {
  // User methods
  createUser(data: Omit<User, "id" | "createdAt" | "updatedAt">): Promise<User>
  findUserById(id: string): Promise<User | null>
  findUserByEmail(email: string): Promise<User | null>
  findUserByPhone(phone: string): Promise<User | null>
  updateUser(id: string, data: Partial<User>): Promise<User>
  deleteUser(id: string): Promise<void>
  
  // Session methods
  createSession(data: Omit<Session, "id" | "createdAt">): Promise<Session>
  findSession(token: string): Promise<Session | null>
  updateSession(token: string, data: Partial<Session>): Promise<Session>
  deleteSession(token: string): Promise<void>
  deleteUserSessions(userId: string): Promise<void>
  
  // Account methods
  createAccount(data: Omit<Account, "id" | "createdAt">): Promise<Account>
  findAccount(providerId: string, accountId: string): Promise<Account | null>
  findAccountsByUserId(userId: string): Promise<Account[]>
  
  // Verification methods
  createVerification(data: Omit<Verification, "id" | "createdAt">): Promise<Verification>
  findVerification(identifier: string, type: VerificationType): Promise<Verification | null>
  updateVerification(id: string, data: Partial<Verification>): Promise<Verification>
  deleteVerification(id: string): Promise<void>
  deleteExpiredVerifications(): Promise<void>
}

​
User Methods

​
createUser

Creates a new user in the database.
​
data
Omit<User, 'id' | 'createdAt' | 'updatedAt'>
required
User data to create. The adapter will generate id, createdAt, and updatedAt automatically.
​
user
User
The created user object with generated id, createdAt, and updatedAt fields.

​
findUserById

Finds a user by their unique ID.
​
id
string
required
The user’s unique identifier.
​
user
User | null
The user object if found, or null if no user exists with that ID.

​
findUserByEmail

Finds a user by their email address.
​
email
string
required
The email address to search for.
​
user
User | null
The user object if found, or null if no user exists with that email.

​
findUserByPhone

Finds a user by their phone number.
​
phone
string
required
The phone number to search for.
​
user
User | null
The user object if found, or null if no user exists with that phone number.

​
updateUser

Updates an existing user’s information.
​
id
string
required
The ID of the user to update.
​
data
Partial<User>
required
Partial user data to update. Only provided fields will be updated.
​
user
User
The updated user object.

​
deleteUser

Deletes a user from the database.
​
id
string
required
The ID of the user to delete.
​
void
void
This method returns nothing on success.
Deleting a user should cascade to delete their sessions and accounts. Implement this with database constraints or manual cleanup.

​
Session Methods

​
createSession

Creates a new session for a user.
​
data
Omit<Session, 'id' | 'createdAt'>
required
Session data to create. The adapter will generate id and createdAt automatically.
​
session
Session
The created session object.

​
findSession

Finds a session by its token.
​
token
string
required
The session token to search for.
​
session
Session | null
The session object if found, or null if no session exists with that token.

​
updateSession

Updates an existing session.
​
token
string
required
The token of the session to update.
​
data
Partial<Session>
required
Partial session data to update.
​
session
Session
The updated session object.

​
deleteSession

Deletes a session (used for logout).
​
token
string
required
The token of the session to delete.
​
void
void
This method returns nothing on success.

​
deleteUserSessions

Deletes all sessions for a specific user.
​
userId
string
required
The ID of the user whose sessions should be deleted.
​
void
void
This method returns nothing on success.

​
Account Methods

​
createAccount

Creates a new account linking a user to an authentication provider.
​
data
Omit<Account, 'id' | 'createdAt'>
required
Account data to create.
​
account
Account
The created account object.

​
findAccount

Finds an account by provider and account ID.
​
providerId
string
required
The provider identifier.
​
accountId
string
required
The account ID from the provider.
​
account
Account | null
The account object if found, or null.

​
findAccountsByUserId

Finds all accounts belonging to a user.
​
userId
string
required
The user’s ID.
​
accounts
Account[]
Array of account objects.

​
Verification Methods

​
createVerification

Creates a new verification record for OTP or email verification.
​
data
Omit<Verification, 'id' | 'createdAt'>
required
Verification data to create.
​
verification
Verification
The created verification object.

​
findVerification

Finds a verification record by identifier and type.
​
identifier
string
required
The email or phone number.
​
type
VerificationType
required
The verification type.
​
verification
Verification | null
The verification object if found, or null.

​
updateVerification

Updates a verification record (typically to increment attempts).
​
id
string
required
The verification ID.
​
data
Partial<Verification>
required
Partial verification data to update.
​
verification
Verification
The updated verification object.

​
deleteVerification

Deletes a verification record after successful verification.
​
id
string
required
The verification ID to delete.
​
void
void
This method returns nothing on success.

​
deleteExpiredVerifications

Cleans up expired verification records.
​
void
void
This method returns nothing on success.
This should be called periodically (e.g., via a cron job) to prevent database bloat.

​
Creating a Custom Adapter

To create a custom adapter for your database: 
import type { DatabaseAdapter } from "@arraf-auth/core"

export function myCustomAdapter(client: MyDBClient): DatabaseAdapter {
  return {
    async createUser(data) {
      // Implement user creation
    },
    async findUserById(id) {
      // Implement user lookup
    },
    // ... implement all other methods
  }
}

​
Official Adapters

Arraf Auth provides official adapters for popular databases:

​
Type Definitions

The adapter works with these core types: 
interface User {
  id: string
  email: string | null
  phone: string | null
  name: string | null
  emailVerified: boolean
  phoneVerified: boolean
  image: string | null
  createdAt: Date
  updatedAt: Date
}

interface Session {
  id: string
  userId: string
  token: string
  expiresAt: Date
  ipAddress?: string
  userAgent?: string
  createdAt: Date
}

interface Account {
  id: string
  userId: string
  providerId: string
  accountId: string
  accessToken?: string
  refreshToken?: string
  accessTokenExpiresAt?: Date
  createdAt: Date
}

interface Verification {
  id: string
  identifier: string
  token: string
  type: VerificationType
  expiresAt: Date
  attempts: number
  createdAt: Date
}

type VerificationType =
  | "phone-otp"
  | "email-otp"
  | "email-verification"
  | "password-reset"
  | "phone-change"

Build docs developers (and LLMs) love

Get started for freeTalk to us