github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-22 14:21:55 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[GH-ISSUE #9137] docs(oauth-provider): SQL schema references oauthClient.id where plugin/CLI use oauthClient.clientId #11285

New Issue
Closed
opened 2026-04-13 07:37:54 -05:00 by GiteaMirror · 3 comments
GiteaMirror commented 2026-04-13 07:37:54 -05:00
Owner
Copy Link

Originally created by @pplytas on GitHub (Apr 12, 2026).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/9137

Is this suited for github?

  • Yes, this is suited for github

Reproduction

  1. Open the OAuth Provider schema docs:
    https://better-auth.com/docs/plugins/oauth-provider#schema

  2. Follow the SQL shown there for the OAuth Provider tables.

  3. The docs define both oauthClient.id and oauthClient.clientId, but the child-table SQL examples reference clientId to the parent id.

  4. Run an OAuth authorization + consent flow.

  5. Submit consent at /api/auth/oauth2/consent.

  6. Observe a foreign-key failure if the DB schema was created from the docs SQL literally.

Current vs. Expected behavior

Current behavior:

The OAuth Provider docs SQL appears inconsistent with Better Auth's actual schema.

The docs define both oauthClient.id and oauthClient.clientId, but the child-table SQL examples reference clientId to the parent id.

Following that SQL literally caused a DB schema mismatch for us and broke the consent flow with a foreign-key error.

Expected behavior:

The docs SQL should match the actual Better Auth plugin contract.

These child-table foreign keys should reference oauth_client.client_id:

  • oauth_refresh_token.client_id
  • oauth_access_token.client_id
  • oauth_consent.client_id

What version of Better Auth are you using?

1.6.1

System info

- better-auth: 1.6.1
- @better-auth/oauth-provider: 1.6.1
- Node.js: v24.14.1
- OS: Darwin 25.3.0 arm64
- Framework: Next.js 16.2.1
- Database: PostgreSQL

Which area(s) are affected? (Select all that apply)

Documentation

Auth config (if applicable)

import { betterAuth } from "better-auth";
import { oauthProvider } from "@better-auth/oauth-provider";
import { jwt } from "better-auth/plugins/jwt";

export const auth = betterAuth({
  plugins: [jwt(), oauthProvider({ grantTypes: ["authorization_code", "refresh_token"] })],
});

Additional context

We verified this against both the Better Auth CLI-generated schema and the shipped @better-auth/oauth-provider plugin schema. Both use oauthClient.clientId as the FK target, not oauthClient.id.

Originally created by @pplytas on GitHub (Apr 12, 2026). Original GitHub issue: https://github.com/better-auth/better-auth/issues/9137 ### Is this suited for github? - [x] Yes, this is suited for github ### Reproduction 1. Open the OAuth Provider schema docs: https://better-auth.com/docs/plugins/oauth-provider#schema 2. Follow the SQL shown there for the OAuth Provider tables. 3. The docs define both `oauthClient.id` and `oauthClient.clientId`, but the child-table SQL examples reference `clientId` to the parent `id`. 4. Run an OAuth authorization + consent flow. 5. Submit consent at `/api/auth/oauth2/consent`. 6. Observe a foreign-key failure if the DB schema was created from the docs SQL literally. ### Current vs. Expected behavior #### Current behavior: The OAuth Provider docs SQL appears inconsistent with Better Auth's actual schema. The docs define both `oauthClient.id` and `oauthClient.clientId`, but the child-table SQL examples reference `clientId` to the parent `id`. Following that SQL literally caused a DB schema mismatch for us and broke the consent flow with a foreign-key error. #### Expected behavior: The docs SQL should match the actual Better Auth plugin contract. These child-table foreign keys should reference `oauth_client.client_id`: - `oauth_refresh_token.client_id` - `oauth_access_token.client_id` - `oauth_consent.client_id` ### What version of Better Auth are you using? 1.6.1 ### System info ```bash - better-auth: 1.6.1 - @better-auth/oauth-provider: 1.6.1 - Node.js: v24.14.1 - OS: Darwin 25.3.0 arm64 - Framework: Next.js 16.2.1 - Database: PostgreSQL ``` ### Which area(s) are affected? (Select all that apply) Documentation ### Auth config (if applicable) ```typescript import { betterAuth } from "better-auth"; import { oauthProvider } from "@better-auth/oauth-provider"; import { jwt } from "better-auth/plugins/jwt"; export const auth = betterAuth({ plugins: [jwt(), oauthProvider({ grantTypes: ["authorization_code", "refresh_token"] })], }); ``` ### Additional context We verified this against both the Better Auth CLI-generated schema and the shipped `@better-auth/oauth-provider` plugin schema. Both use `oauthClient.clientId` as the FK target, not `oauthClient.id`.
GiteaMirror added the docs label 2026-04-13 07:37:54 -05:00
GiteaMirror commented 2026-04-13 07:37:56 -05:00
Author
Owner
Copy Link

@pplytas commented on GitHub (Apr 12, 2026):

For reference, the problematic docs SQL is the child-table FK shape like:

FOREIGN KEY ("clientId") REFERENCES "client" ("id") ON DELETE CASCADE

That seems to conflict with the actual Better Auth plugin/CLI schema, which uses oauthClient.clientId as the FK target for:

  • oauthRefreshToken.clientId
  • oauthAccessToken.clientId
  • oauthConsent.clientId
<!-- gh-comment-id:4231724534 --> @pplytas commented on GitHub (Apr 12, 2026): For reference, the problematic docs SQL is the child-table FK shape like: ```sql FOREIGN KEY ("clientId") REFERENCES "client" ("id") ON DELETE CASCADE ``` That seems to conflict with the actual Better Auth plugin/CLI schema, which uses `oauthClient.clientId` as the FK target for: - oauthRefreshToken.clientId - oauthAccessToken.clientId - oauthConsent.clientId
GiteaMirror commented 2026-04-13 07:37:57 -05:00
Author
Owner
Copy Link

@dosubot[bot] commented on GitHub (Apr 12, 2026):

Hi @pplytas! I'm Dosu and I’m helping the better-auth team.

Can confirm this is a documentation bug. In the plugin source code, all three child tables explicitly reference oauthClient.clientId, not oauthClient.id [1]:

clientId: {
  type: "string",
  required: true,
  references: {
    model: "oauthClient",
    field: "clientId",  // not "id"
  },
}

This applies consistently to oauthRefreshToken, oauthAccessToken, and oauthConsent. The documentation page incorrectly shows these FKs pointing to oauthClient.id.

The CLI-generated migrations will produce the correct FK constraints (referencing clientId), so anyone using npx @better-auth/cli generate or migrate is fine. The issue only affects developers who manually wrote their DDL based on the docs.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
Chat with Dosu Open in Cursor Join Discord Share on X

<!-- gh-comment-id:4231731547 --> @dosubot[bot] commented on GitHub (Apr 12, 2026): <!-- Greeting --> Hi @pplytas! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the better-auth team. <!-- Answer --> Can confirm this is a documentation bug. In the plugin source code, all three child tables explicitly reference `oauthClient.clientId`, not `oauthClient.id` [[1]](https://github.com/better-auth/better-auth/blob/ed2c18df3150ab3a024f7d14a5b5fa58719332f2/packages/oauth-provider/src/schema.ts#L143-L307): ```typescript clientId: { type: "string", required: true, references: { model: "oauthClient", field: "clientId", // not "id" }, } ``` This applies consistently to `oauthRefreshToken`, `oauthAccessToken`, and `oauthConsent`. The [documentation page](https://better-auth.com/docs/plugins/oauth-provider) incorrectly shows these FKs pointing to `oauthClient.id`. The CLI-generated migrations will produce the correct FK constraints (referencing `clientId`), so anyone using `npx @better-auth/cli generate` or `migrate` is fine. The issue only affects developers who manually wrote their DDL based on the docs. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=brand-link).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-great_response#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-irrelevant_answer#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-incorrect_sources#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-too_verbose#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-hallucination#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-bug_report#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-other#message_id=108cfbe7-20fa-4f81-a83f-e5736eea5c6e&feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=chat-badge)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=Can%20confirm%20this%20is%20a%20documentation%20bug.%20In%20the%20plugin%20source%20code%2C%20all%20three%20child%20tables%20explicitly%20reference%20%60oauthClient.clientId%60%2C%20not%20%60oauthClient.id%60%20%5B%5B1%5D%5D%28https%3A//github.com/better-auth/better-auth/blob/ed2c18df3150ab3a024f7d14a5b5fa58719332f2/packages/oauth-provider/src/schema.ts%23L143-L307%29%3A%0A%0A%60%60%60typescript%0AclientId%3A%20%7B%0A%20%20type%3A%20%22string%22%2C%0A%20%20required%3A%20true%2C%0A%20%20references%3A%20%7B%0A%20%20%20%20model%3A%20%22oauthClient%22%2C%0A%20%20%20%20field%3A%20%22clientId%22%2C%20%20//%20not%20%22id%22%0A%20%20%7D%2C%0A%7D%0A%60%60%60%0A%0AThis%20applies%20consistently%20to%20%60oauthRefreshToken%60%2C%20%60oauthAccessToken%60%2C%20and%20%60oauthConsent%60.%20The%20%5Bdocumentation%20page%5D%28https%3A//better-auth.com/docs/plugins/oauth-provider%29%20incorrectly%20shows%20these%20FKs%20pointing%20to%20%60oauthClient.id%60.%0A%0AThe%20CLI-generated%20migrations%20will%20produce%20the%20correct%20FK%20constraints%20%28referencing%20%60clientId%60%29%2C%20so%20anyone%20using%20%60npx%20%40better-auth/cli%20generate%60%20or%20%60migrate%60%20is%20fine.%20The%20issue%20only%20affects%20developers%20who%20manually%20wrote%20their%20DDL%20based%20on%20the%20docs.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=join-discord)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/9137)
GiteaMirror commented 2026-04-13 07:37:57 -05:00
Author
Owner
Copy Link

@bytaesu commented on GitHub (Apr 13, 2026):

@pplytas Thanks for letting us know!

I'll check 😁

<!-- gh-comment-id:4233226852 --> @bytaesu commented on GitHub (Apr 13, 2026): @pplytas Thanks for letting us know! I'll check 😁
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label docs
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#11285
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?