> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anotherwrapper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase PostgreSQL + Better Auth

> Recommended auth and database setup for the boilerplate

<Info>
  **Recommended default:** Supabase PostgreSQL for the database host, with Better Auth inside the app for authentication and sessions. This is the fastest, most supported path.
</Info>

<Tip>
  Recommended path: run `pnpm bootstrap` first. The setup wizard writes `.env.local`, generates `BETTER_AUTH_SECRET`, runs `pnpm db:migrate`, and can also walk you through Google OAuth and email-provider config. The tabs below are the manual equivalent.
</Tip>

## The Mental Model

Here's how the pieces fit together:

* **PostgreSQL + Drizzle** = your data layer (schema, migrations, queries)
* **Better Auth** = your auth layer (sessions, sign-in, OAuth, magic links)
* **Supabase** = the recommended managed Postgres host

Better Auth runs *inside* your app. Supabase just hosts the database. You're not locked into Supabase -- any PostgreSQL provider that supports `pgcrypto` and `pgvector` will work.

## Quick Setup

<Tabs>
  <Tab title="Email/Password Only">
    The fastest path. No OAuth, no magic links -- just email and password.

    <Steps>
      <Step title="Set your env vars">
        Add these to your `.env.local`:

        ```env theme={null}
        NEXT_PUBLIC_APP_URL=http://localhost:3000
        BETTER_AUTH_SECRET=your-secret-here
        DATABASE_URL=postgresql://...
        ```

        <Warning>
          If you copy the connection string from Supabase, replace the literal `[YOUR-PASSWORD]` placeholder with your real database password before pasting.
        </Warning>
      </Step>

      <Step title="Run migrations">
        ```bash theme={null}
        pnpm db:migrate
        ```
      </Step>

      <Step title="Start the app">
        ```bash theme={null}
        pnpm dev
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="With Google OAuth">
    Email/password plus Google sign-in. A bit more setup, but a much better user experience.

    <Steps>
      <Step title="Set your core env vars">
        ```env theme={null}
        NEXT_PUBLIC_APP_URL=http://localhost:3000
        BETTER_AUTH_SECRET=your-secret-here
        DATABASE_URL=postgresql://...
        ```
      </Step>

      <Step title="Set up Google OAuth">
        In Google Cloud Console, add these callback URLs:

        * `http://localhost:3000/api/auth/callback/google`
        * `https://yourdomain.com/api/auth/callback/google`

        Then add your Google credentials to `.env.local`:

        ```env theme={null}
        GOOGLE_CLIENT_ID=...
        GOOGLE_CLIENT_SECRET=...
        NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true
        ```

        <Tip>
          Set `NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true` so the Google button shows up in the UI. The backend only enables Google when `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are also set.
        </Tip>
      </Step>

      <Step title="Optional: Enable magic links and password reset">
        If you want these flows, you'll need an email provider on both the client and server side:

        ```env theme={null}
        NEXT_PUBLIC_EMAIL_PROVIDER=resend
        EMAIL_PROVIDER=resend
        AUTH_EMAIL_FROM="AnotherWrapper <auth@example.com>"
        RESEND_API_KEY=...
        ```

        <Note>
          `resend` is just the shortest example. `loops` and `brevo` are also supported.
        </Note>
      </Step>

      <Step title="Run migrations">
        ```bash theme={null}
        pnpm db:migrate
        ```
      </Step>

      <Step title="Start the app">
        ```bash theme={null}
        pnpm dev
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## What Better Auth Handles

* Sign-in and session cookies
* Email/password accounts
* Google OAuth
* Magic link and forgot password
* Profile bootstrap via database hooks

Email/password works without an email provider. Magic link and forgot password need a real email provider plus auth-email config once you enable those flows.

## What Drizzle Handles

* Schema definition in `lib/db/schema/*`
* SQL migration history in `drizzle/*`
* App-side database access in `lib/db/*`

When you change `lib/db/schema/*`, generate a new SQL migration with `pnpm db:generate`.

<Note>
  The RAG/document search features depend on the `pgvector` extension. The repo enables it in `drizzle/0000_better_auth_baseline.sql`, so your database host must support `CREATE EXTENSION vector`.
</Note>

## Can You Use Another PostgreSQL Provider?

Yes. The main requirements are:

* `pgcrypto` support
* `pgvector` support
* Standard Drizzle/Postgres features used by the schema

Supabase is the recommended default because it gives you managed PostgreSQL plus `pgvector` out of the box.

## Auth Helpers in the Repo

The main server-side auth helpers live in `lib/auth/server.ts`. Here's the pattern:

| Helper                    | Use When                 |
| ------------------------- | ------------------------ |
| `getAuthContext()`        | Auth is optional         |
| `requireUser()`           | Server pages and layouts |
| `requireApiUser()`        | API routes               |
| `signOutCurrentSession()` | Logout flows             |

## Verify It Works

<Check>
  Your auth and database setup is correct if you can:

  * Sign in on `/auth`
  * Reach `/`
  * See a profile row created for your user
  * Use at least one authenticated app flow
</Check>

<CardGroup cols={2}>
  <Card title="Authentication Setup" icon="shield" href="/setup/authentication">
    Need the exact auth flow, magic link setup, forgot password, and Google OAuth steps?
  </Card>

  <Card title="Database Overview" icon="database" href="/database/overview">
    Read the PostgreSQL + Drizzle layer underneath the Better Auth setup.
  </Card>
</CardGroup>