Skip to main content
The database isn’t just there for auth. It stores chats, generations, purchases, credits, recordings, documents, embeddings, and more. It’s the backbone of every app in the repo.

​
The Mental Model

Here’s how to think about the data layer:
  • Better Auth owns the auth tables and browser session flow
  • PostgreSQL + Drizzle own the application data layer
  • Supabase PostgreSQL is the recommended managed host
Application queries run through Drizzle, while authentication lives inside the app through Better Auth — not through provider-specific database primitives.

​
Schema Workflow

1

Edit schema files

Define tables, indexes, and relationships in lib/db/schema/*.
2

Generate SQL migrations

Run pnpm db:generate to produce migration files from your schema changes.
3

Apply migrations

Run pnpm db:migrate to apply the generated SQL to your database.
The drizzle/* folder is the SQL history produced by this workflow. The current baseline starts with drizzle/0000_better_auth_baseline.sql and drizzle/0001_rag_functions.sql.

​
Table Families

Schema files: lib/db/schema/auth.ts, lib/db/schema/profiles.tsHandles:
  • Better Auth users, sessions, accounts, and verifications
  • User profile data
  • Credit tracking
  • Connecting app-owned records to the authenticated user ID
Schema file: lib/db/schema/generations.tsHandles:
  • Outputs from AI apps (images, videos, audio, structured data)
  • Input/output payloads
  • Reusable generation history across multiple apps
Schema file: lib/db/schema/chat.tsHandles:
  • Chat conversations
  • Messages within conversations
  • Chat document versioning
Schema file: lib/db/schema/pdf.tsHandles:
  • Uploaded PDFs
  • Embeddings (via pgvector)
  • Document-to-chat links
  • Similarity search functions
Schema file: lib/db/schema/audio.tsHandles:
  • Recordings
  • Transcripts
  • AI-generated summaries
Schema file: lib/db/schema/purchases.tsHandles:
  • Purchase records
  • Provider metadata
  • Credit packs and plan purchases

​
Important Database Behaviors

​
Ownership Checks

Most user-owned data access is enforced through authenticated server helpers plus user-scoped queries inside the lib/db/* modules. Records are filtered or updated by the current user ID — not by database-vendor-specific auth helpers.

​
Credits

Credit logic isn’t just a frontend number. The repo uses transactional update queries and ownership checks in the database layer to keep credit changes safe. The PDF system uses pgvector plus retrieval functions so the chat app can do document-aware answers with citations. The extension setup and retrieval function live in focused custom Drizzle migrations.
Important details about pgvector:
  • It’s enabled at the database level, not per-table
  • Once the extension exists, any table can define vector(...) columns
  • Your database host still needs to support the extension

​
Good First Files to Read

  • lib/db/schema/auth.ts
  • lib/db/schema/profiles.ts
  • lib/db/schema/generations.ts
  • lib/db/schema/chat.ts
  • lib/db/schema/pdf.ts
  • lib/db/schema/audio.ts
  • lib/db/schema/purchases.ts
  • drizzle/0000_better_auth_baseline.sql
  • drizzle/0001_rag_functions.sql
When customizing the product, understanding these table families helps you avoid a common mistake: bolting new features onto random existing tables instead of working with the repo’s actual data model.

Better Auth + PostgreSQL

Learn how auth and persistence fit together in the default setup.

Vector RAG

Learn how embeddings and retrieval use the database.