Updated Nov 6, 2026

Set up Better Auth with Supabase Declarative Schema

Store Better Auth users and sessions in Supabase Postgres. Create the tables with the Supabase CLI and declarative schemas, then deploy them to your project.

This tutorial demonstrates how to set up Better Auth with Supabase and manage its tables using declarative schemas. Better Auth and Supabase work well together, because every Supabase project is a full Postgres database that Better Auth connects to directly.

In this guide, you build a TanStack Start app with email and password sign-in. The database setup works the same in any framework. Only the route handler and client code change. Better Auth documents those for each framework in its installation guide.

Prerequisites

Node.js 22 or later
pnpm installed
A Supabase project, to deploy to
A container runtime on your machine.

This guide uses Supabase CLI v3. It installs as a development dependency, so you run it with pnpm supabase.

Set up the project

Create the app, start a local Supabase stack, and set the environment variables that Better Auth reads.

Create the app

Create a TanStack Start app and move into its directory:
```
1
pnpm dlx @tanstack/cli@latest create my-app --package-manager pnpm --yes --no-intent
2
cd my-app
```
The --yes flag accepts the default options instead of prompting for them. The --no-intent flag skips TanStack’s optional setup for AI coding agents.
Install Better Auth, the Postgres driver, Kysely, and the Supabase CLI. Better Auth uses Kysely to connect to Postgres:
```
1
pnpm add better-auth pg kysely
2
pnpm add -D @types/pg supabase
```

Start Supabase locally

First, start your container runtime.

Then, initialize Supabase in your project and start the local stack:

1
pnpm supabase init
2
pnpm supabase start

When the stack is running, the CLI prints its connection details. The local database URL is:

1
postgresql://postgres:postgres@127.0.0.1:54322/postgres

Set environment variables

Generate a secret that Better Auth uses to sign session cookies:
```
1
pnpm dlx auth@latest secret
```

In your project root, create a .env file with the secret, the local database URL, and your app’s URL:

1
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
2
BETTER_AUTH_SECRET=<your-generated-secret>
3
BETTER_AUTH_URL=http://localhost:3000

Create the Better Auth tables

Declarative schema files in supabase/schemas/ describe the state you want your database to be in. The Supabase CLI compares them with your migrations and writes the difference as a new migration.

Configure Better Auth

Create src/lib/auth.ts. This file configures Better Auth with the Kysely PostgresDialect and keeps its tables in a better_auth schema:

1
import { betterAuth } from 'better-auth'
2
import { tanstackStartCookies } from 'better-auth/tanstack-start'
3
import { PostgresDialect } from 'kysely'
4
import { Pool } from 'pg'
5
6
export const auth = betterAuth({
7
  database: {
8
    dialect: new PostgresDialect({
9
      pool: new Pool({
10
        connectionString: process.env.DATABASE_URL,
11
      }),
12
    }),
13
    type: 'postgres',
14
    schemaName: 'better_auth',
15
  },
16
  emailAndPassword: {
17
    enabled: true,
18
  },
19
  plugins: [tanstackStartCookies()],
20
})

The schemaName option keeps the tables in their own schema, outside the database’s default schema. Better Auth qualifies every query with the schema name, such as "better_auth"."user".

The tanstackStartCookies plugin sets cookies through TanStack Start. Other frameworks don’t need it.

Generate the Better Auth schema

Use the Better Auth CLI to write its tables to a schema file:

1
pnpm dlx auth@latest generate --output supabase/schemas/better_auth.sql --yes

You can ignore the Database schema mismatch error that the command logs. It lists the Better Auth tables that don’t exist yet, which the generated file creates.

The generated file in supabase/schemas/better_auth.sql creates the schema and each table with a schema-qualified name:

1
create schema if not exists "better_auth";
2
3
create table "better_auth"."user" ( ... );
4
5
create table "better_auth"."session" ( ... );
6
7
create table "better_auth"."account" ( ... );
8
9
create table "better_auth"."verification" ( ... );

If your local database already has Better Auth tables, generate writes only what’s missing, and the schema file is incomplete. With the Kysely adapter, the command compares against your live database. To add changes later, see Update the schema.

Generate and apply the migration

Generate a migration from your schema files, then apply it to your local database:

1
pnpm supabase db schema declarative sync -f add_better_auth --name add_better_auth --no-apply
2
pnpm supabase migration up

Confirm that the database matches what Better Auth expects:
```
1
pnpm dlx auth@latest check schema
```
The command prints Schema check passed against the live database.
Commit supabase/schemas/better_auth.sql and the migration.

Connect your app to Better Auth with a server route, a client, and a sign-in page.

Mount the auth handler

Better Auth serves its endpoints, such as /api/auth/sign-up/email, through a single handler. In TanStack Start, mount it as a server route.

Create src/routes/api/auth/$.ts:

1
import { createFileRoute } from '@tanstack/react-router'
2
3
import { auth } from '@/lib/auth'
4
5
export const Route = createFileRoute('/api/auth/$')({
6
  server: {
7
    handlers: {
8
      GET: ({ request }) => auth.handler(request),
9
      POST: ({ request }) => auth.handler(request),
10
    },
11
  },
12
})

Create src/lib/auth-client.ts with the Better Auth client:

1
import { createAuthClient } from 'better-auth/react'
2
3
export const authClient = createAuthClient()

In src/lib/auth.functions.ts, create a server function that reads the current session from the request cookies:

1
import { createServerFn } from '@tanstack/react-start'
2
import { getRequestHeaders } from '@tanstack/react-start/server'
3
4
import { auth } from '@/lib/auth'
5
6
export const getSession = createServerFn({ method: 'GET' }).handler(async () => {
7
  const headers = getRequestHeaders()
8
  return auth.api.getSession({ headers })
9
})

Replace src/routes/index.tsx with a page that loads the session on the server. The page shows a sign-up and sign-in form, or the signed-in user’s email. It uses Tailwind CSS classes, which the TanStack Start starter includes:

1
import { createFileRoute, useRouter } from '@tanstack/react-router'
2
import { useState } from 'react'
3
4
import { authClient } from '@/lib/auth-client'
5
import { getSession } from '@/lib/auth.functions'
6
7
export const Route = createFileRoute('/')({
8
  loader: () => getSession(),
9
  component: Home,
10
})
11
12
const inputClass = 'w-full rounded-md border border-neutral-300 px-3 py-2 text-sm'
13
const buttonClass = 'flex-1 rounded-md px-4 py-2 text-sm font-medium'
14
15
function Home() {
16
  const session = Route.useLoaderData()
17
  const router = useRouter()
18
  const [name, setName] = useState('')
19
  const [email, setEmail] = useState('')
20
  const [password, setPassword] = useState('')
21
  const [error, setError] = useState<string | null>(null)
22
23
  if (session) {
24
    return (
25
      <main className="mx-auto my-16 max-w-sm rounded-lg border border-neutral-200 bg-white p-6 text-neutral-900 shadow-sm">
26
        <p className="text-sm text-neutral-600">Signed in as</p>
27
        <p className="mt-1 font-medium">{session.user.email}</p>
28
        <button
29
          className={`${buttonClass} mt-6 w-full border border-neutral-300 hover:bg-neutral-100`}
30
          onClick={async () => {
31
            await authClient.signOut()
32
            router.invalidate()
33
          }}
34
        >
35
          Sign out
36
        </button>
37
      </main>
38
    )
39
  }
40
41
  async function handleSignUp() {
42
    const { error } = await authClient.signUp.email({ name, email, password })
43
    if (error) return setError(error.message ?? 'Sign-up failed')
44
    router.invalidate()
45
  }
46
47
  async function handleSignIn() {
48
    const { error } = await authClient.signIn.email({ email, password })
49
    if (error) return setError(error.message ?? 'Sign-in failed')
50
    router.invalidate()
51
  }
52
53
  return (
54
    <main className="mx-auto my-16 flex max-w-sm flex-col gap-3 rounded-lg border border-neutral-200 bg-white p-6 text-neutral-900 shadow-sm">
55
      <h1 className="mb-2 text-lg font-semibold">Sign in or create an account</h1>
56
      <input
57
        className={inputClass}
58
        placeholder="Name"
59
        value={name}
60
        onChange={(e) => setName(e.target.value)}
61
      />
62
      <input
63
        className={inputClass}
64
        placeholder="Email"
65
        value={email}
66
        onChange={(e) => setEmail(e.target.value)}
67
      />
68
      <input
69
        className={inputClass}
70
        placeholder="Password"
71
        type="password"
72
        value={password}
73
        onChange={(e) => setPassword(e.target.value)}
74
      />
75
      {error && <p className="text-sm text-red-600">{error}</p>}
76
      <div className="mt-2 flex gap-3">
77
        <button
78
          className={`${buttonClass} bg-neutral-900 text-white hover:bg-neutral-700`}
79
          onClick={handleSignIn}
80
        >
81
          Sign in
82
        </button>
83
        <button
84
          className={`${buttonClass} border border-neutral-300 hover:bg-neutral-100`}
85
          onClick={handleSignUp}
86
        >
87
          Sign up
88
        </button>
89
      </div>
90
    </main>
91
  )
92
}

For how to protect routes and server functions, see Protecting resources in the Better Auth TanStack Start guide.

Test the sign-up flow against your local Supabase stack:

Start the dev server:
```
1
pnpm dev
```
Open your app at http://localhost:3000, and sign up with a name, email, and password. The page shows Signed in as with your email.
Check that the user is stored in the better_auth schema:
```
1
pnpm supabase db query 'select id, email from better_auth."user"'
```
You can also view the tables in your local Supabase Studio at http://127.0.0.1:54323. In the Table Editor, select the better_auth schema.

Deploy and update the schema

Push the tables to your hosted project. When the Better Auth schema changes later, update the schema file and deploy again.

Deploy to your Supabase project

Sign in to the Supabase CLI and link your project:
```
1
pnpm supabase login
2
pnpm supabase link
```
Push your migrations to the hosted database. The CLI asks you to confirm before it changes your project:
```
1
pnpm supabase db push --remote
```
Where your app runs, set the following environment variables:
- DATABASE_URL: the connection string from your project’s Connect panel
- BETTER_AUTH_SECRET: a new secret for production, generated with pnpm dlx auth@latest secret
- BETTER_AUTH_URL: your app’s public URL

Choose the DATABASE_URL connection type based on where your app runs:

Where your app runs	Connection type
Serverless platforms, such as Vercel or Netlify	Shared pooler, transaction mode
A long-running server on an IPv4-only network	Shared pooler, session mode
A long-running server with IPv6 or the IPv4 add-on	Direct connection

On serverless platforms, set max: 1 in the Pool options in src/lib/auth.ts. Kysely with node-postgres doesn’t use prepared statements, so it works with transaction mode without extra settings. For details on each connection type, see Connect to your database.

Update the schema

Better Auth plugins, and some Better Auth upgrades, add tables or columns. Because generate inspects your live database, it outputs only the changes. Use it to update your schema file:

In src/lib/auth.ts, update the Better Auth configuration. For example, add a plugin.

Generate the changes against your local database, which has the current schema applied. Write them to a temporary file:

1
pnpm dlx auth@latest generate --output better_auth_changes.sql --yes

For example, adding the Better Auth username plugin generates:

1
alter table "better_auth"."user" add column "username" text;
2
3
alter table "better_auth"."user" add column "displayUsername" text;
4
5
create unique index "user_username_uidx" on "better_auth"."user" ("username");

Append the changes to your schema file, and delete the temporary file:

1
cat better_auth_changes.sql >> supabase/schemas/better_auth.sql
2
rm better_auth_changes.sql

Generate and apply a new migration:

1
pnpm supabase db schema declarative sync -f add_better_auth_username --no-apply
2
pnpm supabase migration up

Deploy the migration with pnpm supabase db push --remote.

Changes made with pnpm dlx auth@latest migrate apply directly to the database, so the Supabase CLI doesn’t include them in your migrations. Make schema changes in the declarative schema files instead, and don’t run migrate in this setup.

Read and write app data

Better Auth signs users in and tracks their sessions. Your app reads and writes its own data in one of these ways:

A Postgres client or an ORM on the server, such as Kysely, Drizzle, or Prisma. Read the user from auth.api.getSession(), then filter queries by session.user.id.
The Supabase Data API with Row Level Security (RLS). Supabase accepts JSON Web Tokens (JWTs) from any OpenID Connect (OIDC) provider through third-party auth. Better Auth’s JWT plugin can issue those JWTs, so your RLS policies can identify Better Auth users. In policies, read the user ID with auth.jwt()->>'sub', because auth.uid() expects a UUID. Custom OIDC providers aren’t available in the Supabase CLI, so test this setup on a hosted project.

Link your tables to Better Auth users

To link your own tables to Better Auth users, reference better_auth."user"(id). The ID is text:

1
create table public.profiles (
2
  id bigint generated always as identity primary key,
3
  user_id text not null references better_auth."user" (id) on delete cascade,
4
  bio text
5
);

Add tables like this to a file in supabase/schemas/. Then generate and apply a migration, as in Generate and apply the migration. If a table is in a schema that is exposed via the Data API, enable RLS on it.

Resources

AI tools

Connect your AI agentAsk ChatGPT Ask Claude

Set up Better Auth with Supabase Declarative Schema

Prerequisites

Set up the project

Create the app

Start Supabase locally

Set environment variables

Create the Better Auth tables

Configure Better Auth

Generate the Better Auth schema

Generate and apply the migration

Mount the auth handler

Deploy and update the schema

Deploy to your Supabase project

Update the schema

Read and write app data

Link your tables to Better Auth users

Resources

AI tools

More Auth guides

Migrate from Auth0 to Supabase Auth

Migrate from Firebase Auth to Supabase

Prerequisites

Set up the project

Create the app

Start Supabase locally

Set environment variables

Create the Better Auth tables

Configure Better Auth

Generate the Better Auth schema

Generate and apply the migration

Add sign-up and sign-in

Mount the auth handler

Add the sign-in page

Test sign-up locally

Deploy and update the schema

Deploy to your Supabase project

Update the schema

Read and write app data

Link your tables to Better Auth users

Resources

AI tools

Migrate from Auth0 to Supabase Auth

Migrate from Firebase Auth to Supabase