Database Adapter Schema Resolution#

Overview#

The adapter layer in Better Auth uses a two-layer naming system — schema keys (canonical identifiers like "user", "session", "account") vs. modelName (the physical table/collection name). Schema resolution is the process of translating between these two, and of discovering foreign-key relationships at query time.

Key source files:

• packages/core/src/db/adapter/factory.ts — main adapter factory; hosts transformJoinClause, handleFallbackJoin, transformInput, transformOutput
• packages/core/src/db/adapter/get-default-model-name.ts — canonical schema-key resolver
• packages/core/src/db/type.ts — BetterAuthDBSchema, DBFieldAttribute, references type
• packages/core/src/db/get-tables.ts — builds the full schema object including FK declarations and additionalFields

Model Name Resolution#

Every adapter operation goes through two resolver functions instantiated once inside createAdapterFactory:

getDefaultModelName resolution order 1#

1. Exact schema-key match wins — if schema[candidate] exists, return immediately.
2. modelName alias fallback — scan all schema entries for a matching modelName.
3. usePlural strip — if usePlural is enabled and input ends in s, strip it and re-run both checks.
4. Not found — throws BetterAuthError: Model "${model}" not found in schema.

Schema-key-first priority is critical. If a user sets user.modelName = "account", the old resolver would have routed every internal "account" lookup to the user table (issue #8111). The fix ensures schema keys always win over modelName aliases.

Foreign Key Declarations#

FK relationships are declared via the references property on DBFieldAttribute:

references?: {
  model: string; // canonical schema key, NOT modelName
  field: string;
  onDelete?: "no action" | "restrict" | "cascade" | "set null" | "set default";
}

The references.model value must be a canonical schema key, never a custom modelName. The built-in tables enforce this: session.userId and account.userId both hard-code "user" as the reference model, not options.user.modelName. This prevents FK mis-routing when users customize model names.

Join Resolution: transformJoinClause#

When a query includes a join option (e.g., { user: true } on a session query), transformJoinClause converts it to a fully-resolved JoinConfig:

1. Resolves both the base model and joined model to canonical schema keys via getDefaultModelName.
2. Forward FK check — scans schema[joinedModel].fields for a field whose references.model resolves to the base model 2.
3. Backward FK check — if no forward FK found, scans schema[baseModel].fields for a FK pointing to the joined model 3.
4. Derives from/to column names and infers relationship type (one-to-one if the FK field has unique: true or references id; otherwise one-to-many) 4.
5. Assigns a default limit of 100 (or options.advanced.database.defaultFindManyLimit) to one-to-many joins.

Error cases thrown as BetterAuthError:

• No foreign key found for model ${model} and base model ${baseModel} while performing join operation. — no FK exists in either direction 5.
• Multiple foreign keys found for model ${model} and base model ${baseModel}... — more than one FK found; only single FKs are supported 6.

Join Dispatch: Native vs. Fallback#

After transformJoinClause produces a JoinConfig, the factory decides how to execute it 7:

• options.experimental.joins: true — the join config is passed directly to the adapter (Kysely uses SQL LEFT JOIN; MongoDB uses $lookup aggregation pipelines).
• Default (joins disabled) — the factory withholds the join from the adapter and instead resolves it via handleFallbackJoin: a separate findOne or findMany query is issued for each joined model and results are merged in memory.

transformOutput handles the final assembly: after transforming the base model row, it iterates joined models and either appends a single object (one-to-one) or an array (one-to-many) under the default model name key 8.

additionalFields and Schema Merging#

additionalFields declared in the top-level config for user, session, account, or verification are spread into that table's fields object during schema construction in get-tables.ts. They are merged after built-in fields, so they can extend (but not rename) core columns.

At runtime, additionalFields participate in the full field-resolution pipeline:

• transformInput applies defaultValue, onUpdate, transform.input, and type coercions for each field defined in the schema 9.
• transformOutput reverses the mapping and applies transform.output 10.
• input: false fields are blocked at the API layer before reaching the adapter; returned: false fields are stripped from output. See Additional Fields Schema Configuration.

Plugin-contributed fields follow the same path: they are merged into schema[modelName].fields before createAdapterFactory runs. Plugins can declare their own references to create FK relationships to other tables, which transformJoinClause will resolve at query time using the same forward/backward FK scan.

Validation of External Model References#

Any references.model value that does not resolve to a known schema key will throw at runtime when transformJoinClause calls getDefaultModelName(fieldAttributes.references.model). There is no compile-time guard — the error surfaces only when a join query touches the offending field.

The same error fires if a caller passes an unknown model name to any adapter method (create, findOne, etc.), since every entry point calls getDefaultModelName as its first step 11.