Better Auth keeps everything it knows about your users in four database tables: user, session, account and verification. This guide shows each table exactly as PostgreSQL describes it, and explains every column in plain words, so you know what’s stored where.
| Table | One row is | Created when |
|---|---|---|
user | a person | someone signs up |
session | a signed-in browser or device | someone signs in |
account | one way a person signs in, such as a password or GitHub | a sign-in method is added |
verification | a short-lived value, such as an email verification link | Better Auth sends such a link or code |
Prerequisites
- a Better Auth project whose tables are already created, such as the one from Part 2 of the Better Auth Tutorial
- its PostgreSQL running in Docker Compose, with a service named
db. The commands below use Part 2’s user and database, both namedbookshop.
How to Look at a Table
psql, PostgreSQL’s command-line tool, describes a table with \d. This command runs psql inside the database container and describes the user table:
docker compose exec db psql -U bookshop -d bookshop -c '\d "user"'
docker compose exec dbruns a command inside thedbcontainer.psql -U bookshop -d bookshopconnects as the userbookshopto the databasebookshop.-c '\d "user"'runs one psql command: describe the table nameduser. The double quotes matter, becauseuseris also a word with its own meaning in SQL.
Run it from your project folder, and swap user for session, account or verification to see the other tables.
The user Table
One row for each person who signs up:
Table "public.user"
Column | Type | Collation | Nullable | Default
---------------+--------------------------+-----------+----------+-------------------
id | text | | not null |
name | text | | not null |
email | text | | not null |
emailVerified | boolean | | not null |
image | text | | |
createdAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
updatedAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
Indexes:
"user_pkey" PRIMARY KEY, btree (id)
"user_email_key" UNIQUE CONSTRAINT, btree (email)
Referenced by:
TABLE "account" CONSTRAINT "account_userId_fkey" FOREIGN KEY ("userId") REFERENCES "user"(id) ON DELETE CASCADE
TABLE "session" CONSTRAINT "session_userId_fkey" FOREIGN KEY ("userId") REFERENCES "user"(id) ON DELETE CASCADE

id: the user’s unique ID, made by Better Auth. Every other table points to a user with this value.name: the display name the person chose.email: the email address used to sign in. Theuser_email_keyindex makes it unique, so two people can’t sign up with the same address.emailVerified:trueonce the person has confirmed their email address.image: an optional picture address, for example from a social sign-in.createdAtandupdatedAt: when the row was created and last changed.
Referenced by lists the tables that point to a user. ON DELETE CASCADE means that deleting a user also deletes their sessions and accounts.
The session Table
One row for each signed-in browser or device:
docker compose exec db psql -U bookshop -d bookshop -c '\d "session"'
Table "public.session"
Column | Type | Collation | Nullable | Default
-----------+--------------------------+-----------+----------+-------------------
id | text | | not null |
expiresAt | timestamp with time zone | | not null |
token | text | | not null |
createdAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
updatedAt | timestamp with time zone | | not null |
ipAddress | text | | |
userAgent | text | | |
userId | text | | not null |
Indexes:
"session_pkey" PRIMARY KEY, btree (id)
"session_token_key" UNIQUE CONSTRAINT, btree (token)
"session_userId_idx" btree ("userId")
Foreign-key constraints:
"session_userId_fkey" FOREIGN KEY ("userId") REFERENCES "user"(id) ON DELETE CASCADE
token: the random value in the session cookie. It’s unique, and it’s how Better Auth recognises a signed-in browser.expiresAt: when the session ends, unless Better Auth extends it while it’s used.ipAddressanduserAgent: optional details of the device, useful for a “your sessions” page.userId: the user this session belongs to. Thesession_userId_idxindex finds a user’s sessions quickly.
The account Table
One row for each way a person signs in. Someone with a password and a GitHub sign-in has two rows here, but only one in user:
docker compose exec db psql -U bookshop -d bookshop -c '\d "account"'
Table "public.account"
Column | Type | Collation | Nullable | Default
-----------------------+--------------------------+-----------+----------+-------------------
id | text | | not null |
accountId | text | | not null |
providerId | text | | not null |
userId | text | | not null |
accessToken | text | | |
refreshToken | text | | |
idToken | text | | |
accessTokenExpiresAt | timestamp with time zone | | |
refreshTokenExpiresAt | timestamp with time zone | | |
scope | text | | |
password | text | | |
createdAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
updatedAt | timestamp with time zone | | not null |
Indexes:
"account_pkey" PRIMARY KEY, btree (id)
"account_userId_idx" btree ("userId")
Foreign-key constraints:
"account_userId_fkey" FOREIGN KEY ("userId") REFERENCES "user"(id) ON DELETE CASCADE
providerId: the sign-in method. Email and password accounts usecredential; social sign-ins use the provider’s name.accountId: the person’s ID at that provider. For acredentialaccount it’s the user’s ownid.password: only for email and password accounts. Better Auth stores a scrypt hash of the password here, never the password itself.accessToken,refreshToken,idToken,scopeand the two…ExpiresAtcolumns: what a social provider returns at sign-in, empty for password accounts.userId: the user this sign-in method belongs to.
The verification Table
Short-lived values that prove something, such as an email verification link or a password-reset code:
docker compose exec db psql -U bookshop -d bookshop -c '\d "verification"'
Table "public.verification"
Column | Type | Collation | Nullable | Default
------------+--------------------------+-----------+----------+-------------------
id | text | | not null |
identifier | text | | not null |
value | text | | not null |
expiresAt | timestamp with time zone | | not null |
createdAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
updatedAt | timestamp with time zone | | not null | CURRENT_TIMESTAMP
Indexes:
"verification_pkey" PRIMARY KEY, btree (id)
"verification_identifier_idx" btree (identifier)
identifier: what the value is for. Theverification_identifier_idxindex looks it up quickly.value: the value to check.expiresAt: when it stops working, so old links and codes can’t be reused.
This table has no userId: Better Auth finds each value by its identifier.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
| Renaming tables or columns by hand | Better Auth can’t find them | Use the modelName and fields options, then migrate |
| Changing rows by hand, for example to sign someone out | Better Auth’s own checks and hooks don’t run | Use Better Auth’s functions, such as sign-out |
| Adding your own columns in SQL | Better Auth doesn’t know them | Declare them with additionalFields in lib/auth.ts |
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
psql says Did not find any relation named … | The tables aren’t created yet, or the name is misspelled | Run npx auth@latest migrate, and check the name |
psql shows a screen that ends with (END) | The output is wider or longer than your Terminal | Press q, or make the window bigger |
FAQ
Can I give the tables my own names?
Yes. The modelName and fields options in lib/auth.ts rename tables and columns; your code keeps using Better Auth’s field names.
Do plugins add tables?
Some do, such as two-factor authentication and organizations. Running npx auth@latest migrate after adding a plugin creates them.
Is it safe to read these tables?
Reading is fine. Treat session.token and the account tokens as secrets, and never copy them anywhere public.
Conclusion
user holds people, session holds signed-in devices, account holds the ways each person signs in, and verification holds short-lived links and codes. Every row points back to a user through userId, except verification values.
Additional Resources
- Core schema (opens in a new tab) in the Better Auth database documentation
- Custom tables and additional fields (opens in a new tab)
- psql (opens in a new tab) in the PostgreSQL 18 documentation
Related
- Better Auth Tutorial — Part 2: Set Up Better Auth in Next.js with PostgreSQL, which creates these tables
Better Auth, Next.js and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Better Auth, Inc. or Vercel.
0 comments