Drizzle ORM v1 Compatibility#

Drizzle ORM v1 (release candidate as 1.0.0-rc.x) ships a redesigned relations API — Relations v2 — that replaces the per-table relations() helper with a unified defineRelations() / defineRelationsPart() API. Better Auth added native support in @better-auth/drizzle-adapter@1.7.0-beta.10 (via PR #9489, included in the v1.7 release) through a new relations-v2 package entry point. 1

The two concrete breakages with Drizzle v1 on better-auth ≤ 1.6.x:

• experimental.joins → HTTP 500: The adapter expected old-style per-table Relations class instances; Drizzle v1's defineRelations() object was not recognized, so all joined-query endpoints threw at runtime. 2
• CLI generates invalid schema: auth generate emitted import { relations } from "drizzle-orm" and relations(...) exports, but relations is no longer exported from the root drizzle-orm package in v1, producing a TypeScript error on import. 3

The relations-v2 Entry Point#

For Drizzle ORM v1 projects on better-auth ≥ 1.7, change the adapter import:

// auth.ts
import { drizzleAdapter } from "@better-auth/drizzle-adapter/relations-v2";
import * as schema from "./schema";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg", schema }),
});

Importing from /relations-v2 activates the adapter path that understands Drizzle v1's defineRelations() / defineRelationsPart() types for relational queries. 4 Using the old default import (better-auth/adapters/drizzle or @better-auth/drizzle-adapter) with Drizzle v1 and experimental.joins: true will still fail at runtime. 2

CLI Schema Generation: defineRelationsPart#

After updating to v1.7 and regenerating with npx auth@rc generate, the output uses defineRelationsPart instead of relations():

• Before (Drizzle v0.x output): export const userRelations = relations(user, ({ many }) => ({ ... }))
• After (Drizzle v1.x output): Relations are emitted via defineRelationsPart, so the generated auth schema can be merged alongside your app's own relations without changing the database structure. 1

defineRelationsPart is used instead of defineRelations because Drizzle v1 only accepts one "main" relations object from defineRelations. The CLI generates a part that your app spreads in, leaving your app's defineRelations call intact. 5

Drizzle instance setup after regeneration#

import { drizzle } from "drizzle-orm/postgres-js";
import { relations as appRelations } from "./app-schema";
import { relations as authRelations } from "./schema"; // generated by CLI

export const db = drizzle({
  client,
  // authRelations uses defineRelationsPart; must come after the main relations.
  relations: { ...appRelations, ...authRelations },
});

As of Drizzle v1 RC, schema no longer needs to be passed to the Drizzle instance separately — only relations is required. 5

experimental.joins and Drizzle v1#

The adapter's join logic checks options.experimental?.joins, then calls db.query[queryModel].findFirst/findMany(...) with a with: clause. With Drizzle v0.x, db.query is populated by per-table Relations objects exported from the schema; with v1, it is populated by passing relations to the drizzle() constructor. The relations-v2 entry point corrects how the adapter inspects and uses the db.query object. Without it, you get runtime errors such as Unknown relational filter field: "decoder". 5

Version Compatibility#

Known Issues (as of 2026-07-09)#

• CLI still emits relations() on v1.7-rc.1 if the adapter import is not updated: Issue #10317 confirms the old relations() format is generated unless the auth config already imports from @better-auth/drizzle-adapter/relations-v2. Switching the import and re-running the CLI resolves it. 3 6
• experimental.joins failures on ≤ 1.6.x: The only in-place workaround is disabling experimental.joins until upgrading to v1.7. 2

Key References#