docs: correct the 1.7 account cleanup guide by gustavovalverde · Pull Request #11198 · better-auth/better-auth

gustavovalverde · 2026-09-07T12:43:36Z

Corrects account cleanup instructions that fail on SQL Server and PostgreSQL, and fills gaps in the 1.7.3 recovery sequence.

Separate SQL Server syntax and quote the PostgreSQL index name.
Cover preview databases, ORM migration application, restarts, and rollback limits.
Explain recovery for provider connections that previously shared an account.

Summary by cubic

Corrects the 1.7 account cleanup guide so the SQL statements work on SQL Server and PostgreSQL, and completes the 1.7.3 recovery steps.

Separates SQL Server syntax and quotes the PostgreSQL index name so the statements execute.
Covers preview databases that stored synthetic issuers, ORM migration checks, restarts, and rollback limits.
Documents how to recover provider connections that previously shared an account.

^{Written for commit 0b591fe. Summary will update on new commits.}

vercel · 2026-09-07T12:43:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
better-auth	Ready	Preview	Sep 7, 2026 3:00pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
better-auth-demo	Ignored		Sep 7, 2026 3:00pm UTC

pkg-pr-new · 2026-09-07T12:44:40Z

Open in StackBlitz

@better-auth/api-key

npm i https://pkg.pr.new/@better-auth/api-key@11198

better-auth

npm i https://pkg.pr.new/better-auth@11198

@better-auth/cimd

npm i https://pkg.pr.new/@better-auth/cimd@11198

auth

npm i https://pkg.pr.new/auth@11198

@better-auth/core

npm i https://pkg.pr.new/@better-auth/core@11198

@better-auth/drizzle-adapter

npm i https://pkg.pr.new/@better-auth/drizzle-adapter@11198

@better-auth/electron

npm i https://pkg.pr.new/@better-auth/electron@11198

@better-auth/expo

npm i https://pkg.pr.new/@better-auth/expo@11198

@better-auth/i18n

npm i https://pkg.pr.new/@better-auth/i18n@11198

@better-auth/kysely-adapter

npm i https://pkg.pr.new/@better-auth/kysely-adapter@11198

@better-auth/mcp

npm i https://pkg.pr.new/@better-auth/mcp@11198

@better-auth/memory-adapter

npm i https://pkg.pr.new/@better-auth/memory-adapter@11198

@better-auth/mongo-adapter

npm i https://pkg.pr.new/@better-auth/mongo-adapter@11198

@better-auth/oauth-provider

npm i https://pkg.pr.new/@better-auth/oauth-provider@11198

@better-auth/passkey

npm i https://pkg.pr.new/@better-auth/passkey@11198

@better-auth/prisma-adapter

npm i https://pkg.pr.new/@better-auth/prisma-adapter@11198

@better-auth/redis-storage

npm i https://pkg.pr.new/@better-auth/redis-storage@11198

@better-auth/scim

npm i https://pkg.pr.new/@better-auth/scim@11198

@better-auth/sso

npm i https://pkg.pr.new/@better-auth/sso@11198

@better-auth/stripe

npm i https://pkg.pr.new/@better-auth/stripe@11198

@better-auth/telemetry

npm i https://pkg.pr.new/@better-auth/telemetry@11198

@better-auth/test-utils

npm i https://pkg.pr.new/@better-auth/test-utils@11198

commit: 0b591fe

greptile-apps · 2026-09-07T12:46:45Z

Greptile Summary

Corrects the Better Auth 1.7 account cleanup guide across supported databases and expands the recovery procedure.

Separates MySQL and SQL Server cleanup syntax and preserves database-specific column attributes.
Adds preparation, migration, restart, rollback, and verification guidance.
Documents OAuth and SSO recovery for provider connections that previously shared an account.

Confidence Score: 4/5

The PR is not yet safe to merge because deployments without SSO resolver support still lack a documented recovery procedure.

The previous SSO recovery finding is only partially addressed: the guide now acknowledges that deployments without transaction or resolver support have no automatic recovery path, but it still does not provide the requested manual or normal account-linking procedure for those deployments.

_{Reviews (2): Last reviewed commit: "docs: clarify account recovery and prese..." | Re-trigger Greptile}

Copilot

🟡 Changes recommended

The SQL Server example hardcodes a specific collation in an ALTER statement, which can be incorrect and unintentionally change a database’s collation during cleanup.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the Better Auth 1.7 upgrade documentation to correct the “account issuer cleanup” steps and expand the recovery guidance for databases affected by 1.7.0–1.7.2 account identity behavior.

Changes:

Adjusts SQL snippets to be compatible across PostgreSQL, MySQL, SQL Server, and SQLite (including quoting and SQL Server-specific syntax).
Adds operational guidance around backups, preview-build cleanup, ORM migration application, restarts, and rollback limitations.
Documents a recovery path for provider connections that previously collapsed into a shared Account row.

File summaries

File	Description
docs/content/docs/guides/1-7-upgrade-guide.mdx	Refines the 1.7 issuer cleanup and recovery instructions, including per-database SQL examples and additional post-cutover verification guidance.

Review details

Files reviewed: 1/1 changed files
Comments generated: 1
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+
+        ```sql
+        DROP INDEX account_issuer_accountId_uidx ON dbo.account;
+        ALTER TABLE dbo.account ALTER COLUMN issuer VARCHAR(255) COLLATE SQL_Latin1_General_CP1_CI_AS NULL;


greptile-apps · 2026-09-07T12:46:51Z

+
+On 1.7.0 through 1.7.2, several provider configurations could share one Account row. In 1.7.3, each provider ID needs its own row; removing the issuer column or index does not create missing accounts. Inventory those connections and their existing users before removing issuer values.
+
+For affected SSO connections, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. Return `{ action: "link", userId, profile: "preserve" }` for known mappings and reject unknown identities. The verified sign-in creates the connection's Account row for that user. Do not infer ownership from an email match or copy tokens between connections.


SSO recovery is unavailable

On supported deployments without native transactions or transaction async-context support, such as Cloudflare D1, configuring resolveUser as instructed returns HTTP 501 before the resolver runs. The linked SSO documentation states these requirements but provides no alternative, so affected SSO connections have no documented way to restore their missing account rows. Please document a manual or normal account-linking recovery path for deployments that cannot use the resolver.

Knowledge Base Used: Enterprise identity protocols

cubic-dev-ai

1 issue found across 1 file

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/content/docs/guides/1-7-upgrade-guide.mdx">

<violation number="1" location="docs/content/docs/guides/1-7-upgrade-guide.mdx:186">
P2: This recovery path is unavailable on deployments without native transactions and transaction async-context support because `resolveUser` fails before the callback runs. Document a manual or normal account-linking recovery path for affected SSO connections on those deployments.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

cubic-dev-ai · 2026-09-07T12:50:59Z

+
+On 1.7.0 through 1.7.2, several provider configurations could share one Account row. In 1.7.3, each provider ID needs its own row; removing the issuer column or index does not create missing accounts. Inventory those connections and their existing users before removing issuer values.
+
+For affected SSO connections, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. Return `{ action: "link", userId, profile: "preserve" }` for known mappings and reject unknown identities. The verified sign-in creates the connection's Account row for that user. Do not infer ownership from an email match or copy tokens between connections.


P2: This recovery path is unavailable on deployments without native transactions and transaction async-context support because resolveUser fails before the callback runs. Document a manual or normal account-linking recovery path for affected SSO connections on those deployments.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/content/docs/guides/1-7-upgrade-guide.mdx, line 186: <comment>This recovery path is unavailable on deployments without native transactions and transaction async-context support because `resolveUser` fails before the callback runs. Document a manual or normal account-linking recovery path for affected SSO connections on those deployments.</comment> <file context> @@ -150,17 +167,27 @@ Better Auth 1.7.0 through 1.7.2 added a required `issuer` column to the `account + +On 1.7.0 through 1.7.2, several provider configurations could share one Account row. In 1.7.3, each provider ID needs its own row; removing the issuer column or index does not create missing accounts. Inventory those connections and their existing users before removing issuer values. + +For affected SSO connections, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. Return `{ action: "link", userId, profile: "preserve" }` for known mappings and reject unknown identities. The verified sign-in creates the connection's Account row for that user. Do not infer ownership from an email match or copy tokens between connections. + +For other providers, have the existing user authenticate with a working sign-in method and link the missing connection through the normal account-linking flow. Keep any connection without a verified recovery path disabled until its mapping is reviewed. </file context>

Suggested change

For affected SSO connections, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. Return `{ action: "link", userId, profile: "preserve" }` for known mappings and reject unknown identities. The verified sign-in creates the connection's Account row for that user. Do not infer ownership from an email match or copy tokens between connections.

For affected SSO connections on deployments with native transactions and transaction async-context support, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. On deployments without those capabilities, document and use a manual or normal account-linking recovery path instead.

bytaesu · 2026-09-07T17:02:10Z


 <Callout type="warn">
-  Only databases that ran 1.7.0 through 1.7.2 need the steps below. New rows no longer write `issuer`, so a `NOT NULL` column rejects every sign-up and account link until you relax it.
+  Databases created or migrated with 1.7.0 through 1.7.2 need the cleanup below, including preview builds that stored synthetic issuers with `identityStrategy: "provider-id"`. Remove `account.identityStrategy` from preview configurations; 1.7.3 no longer supports it. A required `issuer` column rejects new account writes, and schema checks can also block existing sign-ins and session requests.


We don't need to mention identityStrategy. Including unreleased changes would only make this unnecessarily verbose.

bytaesu

I think we should keep the guide focused on what actually needs to be changed. It's enough to tell users what they need to check. Going into too detail will make it longer and more confusing.

docs: correct the 1.7 account cleanup guide

7baee38

gustavovalverde requested a review from a team as a code owner September 7, 2026 12:43

gustavovalverde requested review from Bekacru and a lite review from Copilot and removed request for a team September 7, 2026 12:43

better-release Bot added the docs Documentation, demos label Sep 7, 2026

Copilot started reviewing on behalf of gustavovalverde September 7, 2026 12:44 View session

Copilot AI reviewed Sep 7, 2026

View reviewed changes

Comment thread docs/content/docs/guides/1-7-upgrade-guide.mdx

```sql

DROP INDEX account_issuer_accountId_uidx ON dbo.account;

ALTER TABLE dbo.account ALTER COLUMN issuer VARCHAR(255) COLLATE SQL_Latin1_General_CP1_CI_AS NULL;

greptile-apps Bot reviewed Sep 7, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Sep 7, 2026

View reviewed changes

docs: clarify account recovery and preserve column collations

0b591fe

bytaesu reviewed Sep 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

docs: correct the 1.7 account cleanup guide - #11198

docs: correct the 1.7 account cleanup guide#11198
gustavovalverde wants to merge 2 commits into
mainfrom
docs/1-7-account-cleanup-guide

gustavovalverde commented Sep 7, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

vercel Bot commented Sep 7, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Sep 7, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 7, 2026 •

edited

Loading

Greptile Summary

Confidence Score: 4/5

Uh oh!

Copilot AI left a comment

Uh oh!

greptile-apps Bot Sep 7, 2026

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

cubic-dev-ai Bot Sep 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

bytaesu Sep 7, 2026

Uh oh!

bytaesu left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		On 1.7.0 through 1.7.2, several provider configurations could share one Account row. In 1.7.3, each provider ID needs its own row; removing the issuer column or index does not create missing accounts. Inventory those connections and their existing users before removing issuer values.

		For affected SSO connections, configure the [user resolver](/docs/plugins/sso#resolve-sso-users) with a reviewed mapping from the configured connection, verified issuer, and subject to the existing `userId`. Return `{ action: "link", userId, profile: "preserve" }` for known mappings and reject unknown identities. The verified sign-in creates the connection's Account row for that user. Do not infer ownership from an email match or copy tokens between connections.

Uh oh!

Uh oh!

Conversation

gustavovalverde commented Sep 7, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

vercel Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

greptile-apps Bot Sep 7, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bytaesu Sep 7, 2026

Choose a reason for hiding this comment

Uh oh!

bytaesu left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gustavovalverde commented Sep 7, 2026 •

edited by cubic-dev-ai Bot

Loading

vercel Bot commented Sep 7, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 7, 2026 •

edited

Loading

greptile-apps Bot commented Sep 7, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot Sep 7, 2026 •

edited

Loading