github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-10-19 23:53:17 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

docs: clarify guided migration behavior

Browse Source
This commit is contained in:
Gustavo Valverde
2026-08-25 07:23:34 -04:00
parent b29190de81
commit ae402f0797
2 changed files with 5 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/migration-preflight-plans.md
+4 -2
View File
@@ -6,6 +6,8 @@
"better-auth": patch
---
`auth migrate plan` now inspects schema and release changes without writing to the database, while `auth migrate apply` performs the reviewed changes together. The CLI guides populated Better Auth 1.6 databases through account identity, OAuth provider, and SCIM decisions; records the `1.6-to-1.7` transition and effective configuration values in `better-auth-migration.json`; and supports deterministic JSON output. Plain `auth migrate` remains as a deprecated alias for `migrate apply`.
`auth migrate plan` now reports schema changes, release actions, and blockers without changing the database. `auth migrate apply` confirms and performs the reviewed data and schema changes together, while `--json` provides deterministic output for automation. Plain `auth migrate` remains available as a deprecated alias for `migrate apply`.
Migration planning now reports blockers through `getMigrations` and delays `UnsafeMigrationError` until a caller runs or compiles the plan. The release migration repairs empty MySQL account issuers, bounds indexed identity columns where required, and requires custom Kysely dialects to declare their database type before migrating.
When upgrading a populated Better Auth 1.6 SQL database, the CLI can now backfill account issuers, move OAuth clients and eligible consents, revoke legacy provider tokens, and retire legacy SCIM state before reprovisioning. Decisions that require review are saved in `better-auth-migration.json` with the `1.6-to-1.7` transition and effective issuer values, so the same choices can be inspected and replayed without silently changing under another configuration. The migration also repairs accounts left with empty MySQL issuers and keeps indexed identity fields within MySQL and SQL Server limits.
`getMigrations` results now expose unsafe changes and migration blockers for inspection, while running or compiling an unsafe migration still fails before changing data. SQL-backed Drizzle and Prisma adapters can use the guided migration, and custom Kysely dialects must declare `database.type` so the CLI emits the correct SQL.
docs/content/docs/concepts/cli.mdx
+1 -1
View File
@@ -54,7 +54,7 @@ npx auth@latest migrate plan better-auth-migration.json
npx auth@latest migrate apply better-auth-migration.json
```
For non-interactive JSON application, also pass `--yes`; otherwise the command exits without changing the database. Plain `npx auth@latest migrate` remains an alias for `migrate apply` and prints a deprecation warning. For the current release migration procedure, including Drizzle and Prisma preparation, see the [1.7 upgrade guide](/docs/guides/1-7-upgrade-guide#migrate-from-16-to-17).
For non-interactive JSON application, also pass `--yes`; otherwise the command exits without changing the database. Running plain `npx auth@latest migrate` invokes `migrate apply` and prints a deprecation warning. For the current release migration procedure, including Drizzle and Prisma preparation, see the [1.7 upgrade guide](/docs/guides/1-7-upgrade-guide#migrate-from-16-to-17).
<Callout type="info">
**Using PostgreSQL with a non-default schema?**