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 migrateCreates 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:
waitlist({
schema: {
waitlistEntry: { modelName: "waitlist_entries", fields: { createdAt: "created_at" } },
},
});Tables
| Plugin | Tables | Details |
|---|---|---|
| Audit log | auditEvent, and auditChain with hashChain | Schema |
| Authentication | None: users and accounts are better-auth's own | - |
| Blocklist | blocklistRule | Schema |
| Referral | referralCode, referral, referralStep, referralSlot | Schema |
| Security alerts | knownDevice; links in better-auth's verification | Schema |
| Waitlist | waitlistEntry | Schema |
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.
| Table | Personal data | When the user is deleted |
|---|---|---|
auditEvent | User ids, IP address, user agent; in metadata, emails and identifiers of failed sign-ins | Kept, with a user-deleted event. Removed by retention |
blocklistRule | Whatever admins block, which can be an email or IP address | Not linked to users |
referralCode | The owner's user id | Deleted with the user (also without foreign keys) |
referral | The referrer's and the referred user's ids | Deleted with either user (also without foreign keys) |
referralStep | Step metadata your server passes | Deleted with its referral (also without foreign keys) |
referralSlot | The referrer's user id (only with maxReferralsPerUser) | Deleted with the user or its referral (also without foreign keys) |
knownDevice | User id; a keyed hash of browser, OS (and network), a label like "Chrome on macOS" | Deleted with the user (also without foreign keys) |
waitlistEntry | Email, your metadata, the approving admin's id | Deleted with the user (found by email) |
user.normalizedEmail (normalize) | The normalized email address, e.g. ada@gmail.com for a.da+news@gmail.com | Deleted with the user (it is a field of the user) |
user (authentication) | Placeholder emails (<account id>@steam.invalid), names and avatars from the provider | better-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.