Upgrading
What to check after every Better Auth upgrade, and which per-release migrations apply between your version and the current one.
Two kinds of upgrade need attention: bumping Better Auth (which can change your generated collections) and bumping this plugin (whose minor releases are reserved for breaking changes while it is pre-1.0).
Upgrading Better Auth
Generate and read a migration after every Better Auth bump
Generated collections follow the installed Better Auth schema. With the SQL adapters (Postgres, SQLite), after any better-auth bump, including a patch, generate a migration and read the diff before deploying.
payload migrate:create- A new
NOT NULLcolumn on a populated table needs a backfill before the constraint is enforced. - A proposed column drop needs you to confirm nothing still reads it.
payload migrate:createcompares against the last migration's snapshot, not the live database. An empty migration does not prove the database matches; check the actual columns if in doubt.- Dev
pushmode applies the same changes without asking.
The plugin's repository keeps schema snapshots and runs a daily CI canary against the latest Better Auth packages (better-auth, @better-auth/api-key, @better-auth/passkey, @better-auth/oauth-provider) to catch drift. The CHANGELOG records the Better Auth schema changes it detects; review it alongside your own migration diff.
Upgrading the plugin
Apply each step between your version and the current one, oldest first.
| From | To | What to do |
|---|---|---|
| 0.13.x | 0.14 | Raise peers to the security floors. If you ran the 0.11 issuer migration, relax it first. 0.14 |
| 0.12.x | 0.13 | Nothing required. One session behavior changed. 0.13 |
| 0.11.x | 0.12 | Convert stringified array fields, if you have any. Use 0.12.1 or later. 0.12 |
| 0.10.x | 0.11 | Better Auth 1.7 required, plus a database migration. 0.11 |
| 0.10 or earlier | — | Secret fields locked by default, and breaking changes in 0.7 to 0.9. 0.10 and earlier |
Payload 4 beta has its own release line. See Payload 4.