From daf7ab7aaa5f8d8c8ae7ccdcc46bfdc08ac3e4d3 Mon Sep 17 00:00:00 2001
From: Taesu <166604494+bytaesu@users.noreply.github.com>
Date: Mon, 13 Apr 2026 11:37:17 +0900
Subject: [PATCH] docs: fix fk references in schema tables to match actual
 plugin schemas (#9143)

---
 docs/components/docs/mdx-components.tsx       |  18 +-
 docs/content/docs/concepts/database.mdx       |   2 +
 .../docs/guides/next-auth-migration-guide.mdx |   4 +
 docs/content/docs/plugins/2fa.mdx             |   1 +
 docs/content/docs/plugins/oauth-provider.mdx  |   4 +-
 docs/content/docs/plugins/oidc-provider.mdx   |  10 +-
 docs/content/docs/plugins/organization.mdx    |  11 +
 docs/content/docs/plugins/passkey.mdx         |   1 +
 docs/content/docs/plugins/sso.mdx             | 238 +++++++++---------
 9 files changed, 159 insertions(+), 130 deletions(-)

diff --git a/docs/components/docs/mdx-components.tsx b/docs/components/docs/mdx-components.tsx
index f713c4ea68..726811d577 100644
--- a/docs/components/docs/mdx-components.tsx
+++ b/docs/components/docs/mdx-components.tsx
@@ -96,6 +96,16 @@ interface Field {
 	isForeignKey?: boolean;
 	isOptional?: boolean;
 	isUnique?: boolean;
+	references?: {
+		model: string;
+		field: string;
+		onDelete?:
+			| "no action"
+			| "restrict"
+			| "cascade"
+			| "set null"
+			| "set default";
+	};
 }
 
 const typeAliases: Record<string, string> = {
@@ -231,11 +241,11 @@ function fieldToDBField(field: Field): DBFieldAttribute {
 	const bigint = raw === "bigint";
 
 	let references: DBFieldAttribute["references"] | undefined;
-	if (field.isForeignKey && field.name.endsWith("Id")) {
+	if (field.isForeignKey && field.references) {
 		references = {
-			model: field.name.slice(0, -2),
-			field: "id",
-			onDelete: "cascade",
+			model: field.references.model,
+			field: field.references.field,
+			onDelete: field.references.onDelete ?? "cascade",
 		};
 	}
 
diff --git a/docs/content/docs/concepts/database.mdx b/docs/content/docs/concepts/database.mdx
index 4076920b90..d4fa90349d 100644
--- a/docs/content/docs/concepts/database.mdx
+++ b/docs/content/docs/concepts/database.mdx
@@ -379,6 +379,7 @@ export const sessionTableFields = [
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id", onDelete: "cascade" },
 	},
 	{
 		name: "token",
@@ -433,6 +434,7 @@ export const accountTableFields = [
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id", onDelete: "cascade" },
 	},
 	{
 		name: "accountId",
diff --git a/docs/content/docs/guides/next-auth-migration-guide.mdx b/docs/content/docs/guides/next-auth-migration-guide.mdx
index 3d3ef95565..37d2f0de51 100644
--- a/docs/content/docs/guides/next-auth-migration-guide.mdx
+++ b/docs/content/docs/guides/next-auth-migration-guide.mdx
@@ -428,6 +428,7 @@ name: "userId",
 type: "string",
 description: "The ID of the user",
 isForeignKey: true,
+references: { model: "user", field: "id", onDelete: "cascade" },
 },
 {
 name: "sessionToken",
@@ -457,6 +458,7 @@ name: "userId",
 type: "string",
 description: "The ID of the user",
 isForeignKey: true,
+references: { model: "user", field: "id", onDelete: "cascade" },
 },
 {
 name: "token",
@@ -513,6 +515,7 @@ name: "userId",
 type: "string",
 description: "The ID of the user",
 isForeignKey: true,
+references: { model: "user", field: "id", onDelete: "cascade" },
 },
 {
 name: "type",
@@ -589,6 +592,7 @@ name: "userId",
 type: "string",
 description: "The ID of the user",
 isForeignKey: true,
+references: { model: "user", field: "id", onDelete: "cascade" },
 },
 {
 name: "accountId",
diff --git a/docs/content/docs/plugins/2fa.mdx b/docs/content/docs/plugins/2fa.mdx
index c36e3ef6dd..89f366db58 100644
--- a/docs/content/docs/plugins/2fa.mdx
+++ b/docs/content/docs/plugins/2fa.mdx
@@ -477,6 +477,7 @@ export const twoFactorTableFields = [
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "secret",
diff --git a/docs/content/docs/plugins/oauth-provider.mdx b/docs/content/docs/plugins/oauth-provider.mdx
index 006cc6d7c3..915d7f1997 100644
--- a/docs/content/docs/plugins/oauth-provider.mdx
+++ b/docs/content/docs/plugins/oauth-provider.mdx
@@ -1849,7 +1849,7 @@ export const oauthRefreshTokenTableFields = [
       "ID of the session used at issuance of the token (and still active)",
     isForeignKey: true,
     isOptional: true,
-    references: { model: "session", field: "id" },
+    references: { model: "session", field: "id", onDelete: "set null" },
   },
   {
     name: "userId",
@@ -1927,7 +1927,7 @@ export const oauthAccessTokenTableFields = [
       "ID of the session used at issuance of the token (and still active)",
     isForeignKey: true,
     isOptional: true,
-    references: { model: "session", field: "id" },
+    references: { model: "session", field: "id", onDelete: "set null" },
   },
   {
     name: "refreshId",
diff --git a/docs/content/docs/plugins/oidc-provider.mdx b/docs/content/docs/plugins/oidc-provider.mdx
index 151c205761..656b3f3d98 100644
--- a/docs/content/docs/plugins/oidc-provider.mdx
+++ b/docs/content/docs/plugins/oidc-provider.mdx
@@ -504,7 +504,7 @@ export const oauthApplicationTableFields = [
 		description: "ID of the user who owns the client. (optional)",
 		isOptional: true,
 		isForeignKey: true,
-		references: { model: "user", field: "id" },
+		references: { model: "user", field: "id", onDelete: "cascade" },
 	},
 	{
 		name: "createdAt",
@@ -558,7 +558,7 @@ export const oauthAccessTokenTableFields = [
 		type: "string",
 		description: "ID of the OAuth client",
 		isForeignKey: true,
-		references: { model: "oauthApplication", field: "clientId" },
+		references: { model: "oauthApplication", field: "clientId", onDelete: "cascade" },
 	},
 	{
 		name: "userId",
@@ -566,7 +566,7 @@ export const oauthAccessTokenTableFields = [
 		description: "ID of the user associated with the token",
 		isOptional: true,
 		isForeignKey: true,
-		references: { model: "user", field: "id" },
+		references: { model: "user", field: "id", onDelete: "cascade" },
 	},
 	{
 		name: "scopes",
@@ -603,14 +603,14 @@ export const oauthConsentTableFields = [
 		type: "string",
 		description: "ID of the user who gave consent",
 		isForeignKey: true,
-		references: { model: "user", field: "id" },
+		references: { model: "user", field: "id", onDelete: "cascade" },
 	},
 	{
 		name: "clientId",
 		type: "string",
 		description: "ID of the OAuth client",
 		isForeignKey: true,
-		references: { model: "oauthApplication", field: "clientId" },
+		references: { model: "oauthApplication", field: "clientId", onDelete: "cascade" },
 	},
 	{
 		name: "scopes",
diff --git a/docs/content/docs/plugins/organization.mdx b/docs/content/docs/plugins/organization.mdx
index 0a6106d9ea..d1046f4c39 100644
--- a/docs/content/docs/plugins/organization.mdx
+++ b/docs/content/docs/plugins/organization.mdx
@@ -2021,6 +2021,7 @@ export const teamsFeatureTeamTableFields = [
 		type: "string",
 		description: "The ID of the organization",
 		isForeignKey: true,
+		references: { model: "organization", field: "id" },
 	},
 	{
 		name: "createdAt",
@@ -2051,12 +2052,14 @@ export const teamsFeatureTeamMemberTableFields = [
 		type: "string",
 		description: "Unique identifier for each team",
 		isForeignKey: true,
+		references: { model: "team", field: "id" },
 	},
 	{
 		name: "userId",
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "createdAt",
@@ -2131,12 +2134,14 @@ export const memberTableFields = [
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "organizationId",
 		type: "string",
 		description: "The ID of the organization",
 		isForeignKey: true,
+		references: { model: "organization", field: "id" },
 	},
 	{
 		name: "role",
@@ -2173,12 +2178,14 @@ export const invitationTableFields = [
 		type: "string",
 		description: "The ID of the inviter",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "organizationId",
 		type: "string",
 		description: "The ID of the organization",
 		isForeignKey: true,
+		references: { model: "organization", field: "id" },
 	},
 	{
 		name: "role",
@@ -2256,6 +2263,7 @@ export const organizationRoleTableFields = [
 		type: "string",
 		description: "The ID of the organization",
 		isForeignKey: true,
+		references: { model: "organization", field: "id" },
 	},
 	{
 		name: "role",
@@ -2303,6 +2311,7 @@ export const optionalTeamTableFields = [
 		type: "string",
 		description: "The ID of the organization",
 		isForeignKey: true,
+		references: { model: "organization", field: "id" },
 	},
 	{
 		name: "createdAt",
@@ -2333,12 +2342,14 @@ export const teamsFeatureTeamTableFields0 = [
 		type: "string",
 		description: "Unique identifier for each team",
 		isForeignKey: true,
+		references: { model: "team", field: "id" },
 	},
 	{
 		name: "userId",
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "createdAt",
diff --git a/docs/content/docs/plugins/passkey.mdx b/docs/content/docs/plugins/passkey.mdx
index bd23c17549..1834aea0ac 100644
--- a/docs/content/docs/plugins/passkey.mdx
+++ b/docs/content/docs/plugins/passkey.mdx
@@ -349,6 +349,7 @@ export const passkeyTableFields = [
 		type: "string",
 		description: "The ID of the user",
 		isForeignKey: true,
+		references: { model: "user", field: "id" },
 	},
 	{
 		name: "credentialID",
diff --git a/docs/content/docs/plugins/sso.mdx b/docs/content/docs/plugins/sso.mdx
index 9512f8f095..a685bbd44a 100644
--- a/docs/content/docs/plugins/sso.mdx
+++ b/docs/content/docs/plugins/sso.mdx
@@ -1432,13 +1432,13 @@ The plugin requires additional fields in the `ssoProvider` table to store the pr
 <DatabaseTable
   fields={[
 {
-    name: "id", type: "string", description: "A database identifier", isPrimaryKey: true,
+name: "id", type: "string", description: "A database identifier", isPrimaryKey: true,
 },
 { name: "issuer", type: "string", description: "The issuer identifier" },
 { name: "domain", type: "string", description: "The domain of the provider" },
 { name: "oidcConfig", type: "string", description: "The OIDC configuration (JSON string)", isOptional: true },
 { name: "samlConfig", type: "string", description: "The SAML configuration (JSON string)", isOptional: true },
-{ name: "userId", type: "string", description: "The user ID", isForeignKey: true },
+{ name: "userId", type: "string", description: "The user ID", isForeignKey: true, references: { model: "user", field: "id" } },
 { name: "providerId", type: "string", description: "The provider ID. Used to identify a provider and to generate a redirect URL.", isUnique: true },
 { name: "organizationId", type: "string", description: "The organization Id. If provider is linked to an organization.", isOptional: true }
 ]}
@@ -1512,21 +1512,21 @@ organizationProvisioning: {
 description: "Options for provisioning users to an organization.",
 type: "object",
 properties: {
-    disabled: {
-        description: "Disable organization provisioning.",
-        type: "boolean",
-        default: false,
-    },
-    defaultRole: {
-        description: "The default role for new users.",
-        type: "string",
-        enum: ["member", "admin"],
-        default: "member",
-    },
-    getRole: {
-        description: "A custom function to determine the role for new users.",
-        type: "function",
-    },
+disabled: {
+description: "Disable organization provisioning.",
+type: "boolean",
+default: false,
+},
+defaultRole: {
+description: "The default role for new users.",
+type: "string",
+enum: ["member", "admin"],
+default: "member",
+},
+getRole: {
+description: "A custom function to determine the role for new users.",
+type: "function",
+},
 },
 },
 defaultOverrideUserInfo: {
@@ -1553,99 +1553,99 @@ domainVerification: {
 description: "Configure the domain verification feature",
 type: "object",
 properties: {
-    enabled: {
-        description: "Enables or disables the domain verification feature",
-        type: "boolean",
-        required: false
-    },
-    tokenPrefix: {
-        description: "Prefix used to generate the domain verification identifier. An underscore is automatically prepended.",
-        type: "string",
-        required: false,
-        default: "better-auth-token"
-    },
+enabled: {
+description: "Enables or disables the domain verification feature",
+type: "boolean",
+required: false
+},
+tokenPrefix: {
+description: "Prefix used to generate the domain verification identifier. An underscore is automatically prepended.",
+type: "string",
+required: false,
+default: "better-auth-token"
+},
 },
 },
 defaultSSO: {
 description: "Configure a default SSO provider for testing and development. This provider will be used when no matching provider is found in the database.",
 type: "array",
 items: {
-    type: "object",
-    properties: {
-        domain: {
-            description: "The domain to match for this default provider.",
-            type: "string",
-            required: true,
-        },
-        providerId: {
-            description: "The provider ID to use for the default provider.",
-            type: "string",
-            required: true,
-        },
-        samlConfig: {
-            description: "SAML configuration for the default provider.",
-            type: "SAMLConfig",
-            required: false,
-        },
-        oidcConfig: {
-            description: "OIDC configuration for the default provider.",
-            type: "OIDCConfig",
-            required: false,
-        },
-    }
+type: "object",
+properties: {
+domain: {
+description: "The domain to match for this default provider.",
+type: "string",
+required: true,
+},
+providerId: {
+description: "The provider ID to use for the default provider.",
+type: "string",
+required: true,
+},
+samlConfig: {
+description: "SAML configuration for the default provider.",
+type: "SAMLConfig",
+required: false,
+},
+oidcConfig: {
+description: "OIDC configuration for the default provider.",
+type: "OIDCConfig",
+required: false,
+},
+}
 },
 },
 saml: {
 description: "SAML security options for AuthnRequest/InResponseTo validation, replay protection, and timestamp handling.",
 type: "object",
 properties: {
-    enableInResponseToValidation: {
-        description: "Enable InResponseTo validation for SP-initiated SAML flows.",
-        type: "boolean",
-        default: true,
-    },
-    allowIdpInitiated: {
-        description: "Allow IdP-initiated SSO (unsolicited SAML responses). Set to false for stricter security. Only applies when validation is enabled.",
-        type: "boolean",
-        default: true,
-    },
-    requestTTL: {
-        description: "TTL for AuthnRequest records in milliseconds. Only applies when validation is enabled.",
-        type: "number",
-        default: 300000,
-    },
-    clockSkew: {
-        description: "Clock skew tolerance for SAML assertion timestamp validation (NotBefore/NotOnOrAfter) in milliseconds. Allows for minor time differences between IdP and SP servers.",
-        type: "number",
-        default: 300000,
-    },
-    requireTimestamps: {
-        description: "Require timestamp conditions (NotBefore/NotOnOrAfter) in SAML assertions. When enabled, assertions without timestamps are rejected. When disabled, they are accepted with a warning logged.",
-        type: "boolean",
-        default: false,
-    },
-    algorithms: {
-        description: "Algorithm validation options.",
-        type: "object",
-        properties: {
-            onDeprecated: {
-                description: "Behavior for deprecated algorithms (SHA-1, RSA 1.5, 3DES).",
-                type: "string",
-                enum: ["reject", "warn", "allow"],
-                default: "warn",
-            },
-        },
-    },
-    maxResponseSize: {
-        description: "Maximum allowed size for SAML responses in bytes.",
-        type: "number",
-        default: 262144,
-    },
-    maxMetadataSize: {
-        description: "Maximum allowed size for IdP metadata XML in bytes.",
-        type: "number",
-        default: 102400,
-    },
+enableInResponseToValidation: {
+description: "Enable InResponseTo validation for SP-initiated SAML flows.",
+type: "boolean",
+default: true,
+},
+allowIdpInitiated: {
+description: "Allow IdP-initiated SSO (unsolicited SAML responses). Set to false for stricter security. Only applies when validation is enabled.",
+type: "boolean",
+default: true,
+},
+requestTTL: {
+description: "TTL for AuthnRequest records in milliseconds. Only applies when validation is enabled.",
+type: "number",
+default: 300000,
+},
+clockSkew: {
+description: "Clock skew tolerance for SAML assertion timestamp validation (NotBefore/NotOnOrAfter) in milliseconds. Allows for minor time differences between IdP and SP servers.",
+type: "number",
+default: 300000,
+},
+requireTimestamps: {
+description: "Require timestamp conditions (NotBefore/NotOnOrAfter) in SAML assertions. When enabled, assertions without timestamps are rejected. When disabled, they are accepted with a warning logged.",
+type: "boolean",
+default: false,
+},
+algorithms: {
+description: "Algorithm validation options.",
+type: "object",
+properties: {
+onDeprecated: {
+description: "Behavior for deprecated algorithms (SHA-1, RSA 1.5, 3DES).",
+type: "string",
+enum: ["reject", "warn", "allow"],
+default: "warn",
+},
+},
+},
+maxResponseSize: {
+description: "Maximum allowed size for SAML responses in bytes.",
+type: "number",
+default: 262144,
+},
+maxMetadataSize: {
+description: "Maximum allowed size for IdP metadata XML in bytes.",
+type: "number",
+default: 102400,
+},
 },
 },
 modelName: {
@@ -1655,39 +1655,39 @@ default: "ssoProvider"
 },
 fields: {
 issuer: {
-    description: "Custom name for the issuer column",
-    type: "string",
-    default: "issuer",
+description: "Custom name for the issuer column",
+type: "string",
+default: "issuer",
 },
 oidcConfig: {
-    description: "Custom name for the oidcConfig column",
-    type: "string",
-    default: "oidcConfig",
+description: "Custom name for the oidcConfig column",
+type: "string",
+default: "oidcConfig",
 },
 samlConfig: {
-    description: "Custom name for the samlConfig column",
-    type: "string",
-    default: "samlConfig",
+description: "Custom name for the samlConfig column",
+type: "string",
+default: "samlConfig",
 },
 userId: {
-    description: "Custom name for the userId column",
-    type: "string",
-    default: "userId",
+description: "Custom name for the userId column",
+type: "string",
+default: "userId",
 },
 providerId: {
-    description: "Custom name for the providerId column",
-    type: "string",
-    default: "providerId",
+description: "Custom name for the providerId column",
+type: "string",
+default: "providerId",
 },
 organizationId: {
-    description: "Custom name for the organizationId column",
-    type: "string",
-    default: "organizationId",
+description: "Custom name for the organizationId column",
+type: "string",
+default: "organizationId",
 },
 domain: {
-    description: "Custom name for the domain column",
-    type: "string",
-    default: "domain",
+description: "Custom name for the domain column",
+type: "string",
+default: "domain",
 }
 }
 }}