# schema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Bundles the canonical 17-table Better-Auth SurrealQL schema as a frozen
string constant `BETTER_AUTH_SURREAL_SCHEMA` and exposes a one-shot
`applyBetterAuthSchema(client)` helper for callers who do not run their
DDL through `@suaveplan/api-migrations`. Schema content is mirrored
byte-for-byte from the canonical source-of-truth file
`/mnt/f/surrealdb/surql/features/02-auth/02-better-auth.surql`; future
upstream changes require a coordinated package version bump.

## Features

- 17 DDL targets: `user` field extensions, plus `session`, `account`,
  `verification`, `passkey`, `jwks`, `sso_provider`, `oauth_application`,
  `oauth_access_token`, `oauth_consent`, `organization`, `member`,
  `invitation`, `team`, `team_member`, `two_factor`, `api_key`.
- 13 indexes (account provider, verification identifier, SSO provider id,
  oauth client/access/refresh tokens, organization slug, passkey
  credential, user phone, api_key prefix/user, member/team uniqueness,
  invitation email/org).
- Idempotent on re-application — every `DEFINE TABLE`/`DEFINE FIELD`/
  `DEFINE INDEX` uses the `OVERWRITE` flag.
- `applyBetterAuthSchema(client)` executes the schema via the
  `SurrealClientView.execute()` surface and wraps any underlying failure
  in `BetterAuthSurrealError(QUERY_FAILED)`.

## Usage: Basic

```ts
import { SurrealAdapter } from "@suaveplan/surrealdb";
import { applyBetterAuthSchema } from "@suaveplan/better-auth-surrealdb/schema";

const client = new SurrealAdapter({ url: "ws://localhost:8000" });
await client.connect();
await applyBetterAuthSchema(client);
```

## Usage: Advanced

```ts
import { BETTER_AUTH_SURREAL_SCHEMA } from "@suaveplan/better-auth-surrealdb/schema";

// Pipe the schema through @suaveplan/api-migrations
import { createSurrealqlAdapter } from "@suaveplan/api-migrations";

const migrations = createSurrealqlAdapter({
    steps: [
        { id: "001-better-auth", up: BETTER_AUTH_SURREAL_SCHEMA },
    ],
});

await migrations.run(client);
```

## API Reference

- `BETTER_AUTH_SURREAL_SCHEMA: string` — frozen DDL string.
- `applyBetterAuthSchema(client: SurrealClientView): Promise<void>` — executes
  the schema via `client.execute(...)`; wraps failures in `QUERY_FAILED`.

## Implementation Notes

The constant is a single string literal so bundlers can tree-shake it out
of consumers that import only `applyBetterAuthSchema` from sibling
modules. Newlines are preserved (`\n`) so EXPLAIN output and DB logs stay
human-readable. The helper executes the whole DDL in one `execute()`
call; SurrealDB v3 parses multi-statement scripts natively and runs them
sequentially within a single response. Failure capture preserves the
underlying `SurrealError` via `cause` for upstream telemetry.