Skip to Content
better-auth-plugins

Database

The tables each plugin adds, how to create them, and the personal data they hold.

Plugins that store data declare their tables through better-auth's schema system, exactly like the official plugins. Every database adapter works, and the better-auth CLI creates the tables. The tests run on SQLite, and the tests of concurrent requests also on PostgreSQL, MySQL, and MongoDB.

Create the tables

After adding or upgrading a plugin, run the CLI:

npx auth@latest migrate

Creates the tables directly, with better-auth's built-in Kysely adapter.

Each plugin's schema option renames its tables and columns, like the official plugins:

auth.ts
waitlist({
  schema: {
    waitlistEntry: { modelName: "waitlist_entries", fields: { createdAt: "created_at" } },
  },
});

Tables

PluginTablesDetails
Audit logauditEvent, and auditChain with hashChainSchema
AuthenticationNone: users and accounts are better-auth's own-
BlocklistblocklistRuleSchema
ReferralreferralCode, referral, referralStep, referralSlotSchema
Security alertsknownDevice; links in better-auth's verificationSchema
WaitlistwaitlistEntrySchema

The audit log can keep its events elsewhere instead, with its storage option; then auditEvent isn't created.

Personal data

For your records of processing and privacy policy: what each plugin stores about people, and what happens to it when a user is deleted.

TablePersonal dataWhen the user is deleted
auditEventUser ids, IP address, user agent; in metadata, emails and identifiers of failed sign-insKept, with a user-deleted event. Removed by retention
blocklistRuleWhatever admins block, which can be an email or IP addressNot linked to users
referralCodeThe owner's user idDeleted with the user (also without foreign keys)
referralThe referrer's and the referred user's idsDeleted with either user (also without foreign keys)
referralStepStep metadata your server passesDeleted with its referral (also without foreign keys)
referralSlotThe referrer's user id (only with maxReferralsPerUser)Deleted with the user or its referral (also without foreign keys)
knownDeviceUser id; a keyed hash of browser, OS (and network), a label like "Chrome on macOS"Deleted with the user (also without foreign keys)
waitlistEntryEmail, your metadata, the approving admin's idDeleted with the user (found by email)
user.normalizedEmail (normalize)The normalized email address, e.g. ada@gmail.com for a.da+news@gmail.comDeleted with the user (it is a field of the user)
user (authentication)Placeholder emails (<account id>@steam.invalid), names and avatars from the providerbetter-auth's own deletion

Tokens and invite codes are stored only as hashes. "Deleted with the user" works on every adapter: SQL databases also delete through foreign keys (onDelete: "cascade"), and each plugin deletes its rows itself after a user is deleted, for MongoDB, SQLite without PRAGMA foreign_keys, and custom adapters. If that fails, the error is logged and the user stays deleted. The audit log is the exception: its events are kept, see its Privacy section.

See the audit log's Privacy and Retention and the waitlist's Privacy sections for what to tell your users and how long to keep data, and Compliance for the controls the plugins help with.

On this page