# Auth Migrations

This project keeps two migration artifacts separate:

- Better Auth target schema: the full schema generated from `src/auth.migration.ts`.
- D1 migrations: incremental SQL files applied by Wrangler to the current database.

The target schema is a reference snapshot. Do not apply it directly to a production database that already has tables.

## Generate

Run this after changing Better Auth options or plugins that affect persistence:

```bash
pnpm db:generate
```

Review the generated SQL in:

```text
docs/schema/better-auth-target.sql
```

This file is generated from an in-memory SQLite database because Better Auth CLI needs a database adapter to discover the target schema. That is acceptable for schema generation, but it only represents the desired final shape.

## Check

CI and local readiness use:

```bash
pnpm db:check
```

This command generates SQL into a temporary file with Better Auth CLI and compares it with the committed migration file.

The check compares against:

```text
docs/schema/better-auth-target.sql
```

## Apply Locally

```bash
pnpm db:apply:local
```

Do not use `auth migrate` for D1. D1 migrations are applied by Wrangler so local and remote environments use the same migration history.

## Production Migration Rule

Production D1 databases may already contain an older Better Auth schema. In that case:

1. Export a backup and current schema before changing anything:

   ```bash
   wrangler d1 export cfw-auth --remote --output=backup.sql
   wrangler d1 export cfw-auth --remote --output=prod-schema.sql --no-data
   wrangler d1 migrations list cfw-auth --remote
   ```

2. Treat `docs/schema/better-auth-target.sql` as the target.
3. Write incremental files under `migrations/` that move the existing production schema to the target.
4. Apply with Wrangler:

   ```bash
   wrangler d1 migrations apply cfw-auth --remote
   ```

## Current Migration Layout

- `migrations/0001_baseline_existing_auth.sql` records a baseline for databases that already have the older auth tables.
- `migrations/0002_add_better_auth_account_center.sql` adds the current account-center tables, fields, indexes, API key table, and JWT `jwks` table.

If a brand-new empty D1 database is needed, do not use the baseline path as-is. Either apply a full initial schema generated from `docs/schema/better-auth-target.sql`, or create a separate fresh-database migration sequence.