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

[PR #1926] [MERGED] feat: createAdapter and useNumberId #4072

New Issue
Closed
opened 2026-03-13 11:31:24 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-03-13 11:31:24 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/better-auth/better-auth/pull/1926
Author: @ping-maxwell
Created: 3/21/2025
Status: ✅ Merged
Merged: 4/11/2025
Merged by: @Bekacru

Base: main ← Head: refactor/adapter

📝 Commits (10+)

  • 5e2a0b2 refactor(adapter): createAdapter helper
  • b59edd9 update: Kysely adapter support
  • ffd184f update: memory adapter
  • b3fe580 chore: cleanup
  • 3f17f31 update: MongoDB adapter supported
  • afd41fc update: mongodb adapter file names
  • 4d78fcd update: support for prisma adapter
  • 9f0ad1f chore: lint
  • 3fbad8f fix: generate an id if it isn't already provided
  • 8a3332c update(test): init config snapshot

📊 Changes

68 files changed (+6500 additions, -2181 deletions)

View changed files

📝 docs/components/sidebar-content.tsx (+5 -0)
📝 docs/content/docs/adapters/mongo.mdx (+3 -1)
➕ docs/content/docs/guides/create-a-db-adapter.mdx (+563 -0)
📝 docs/content/docs/reference/options.mdx (+12 -7)
📝 docs/package.json (+1 -1)
📝 examples/astro-example/package.json (+1 -1)
📝 examples/nuxt-example/package.json (+1 -1)
📝 examples/remix-example/package.json (+1 -1)
📝 examples/svelte-kit-example/package.json (+44 -44)
📝 packages/better-auth/build.config.ts (+1 -0)
📝 packages/better-auth/package.json (+14 -3)
📝 packages/better-auth/src/__snapshots__/init.test.ts.snap (+11 -0)
➕ packages/better-auth/src/adapters/create-adapter/index.ts (+994 -0)
➕ packages/better-auth/src/adapters/create-adapter/test/__snapshots__/create-adapter.test.ts.snap (+7 -0)
➕ packages/better-auth/src/adapters/create-adapter/test/create-adapter.test.ts (+1467 -0)
➕ packages/better-auth/src/adapters/create-adapter/types.ts (+379 -0)
📝 packages/better-auth/src/adapters/drizzle-adapter/drizzle-adapter.ts (+265 -340)
📝 packages/better-auth/src/adapters/drizzle-adapter/test/adapter.drizzle.mysql.test.ts (+89 -32)
📝 packages/better-auth/src/adapters/drizzle-adapter/test/adapter.drizzle.test.ts (+70 -20)
📝 packages/better-auth/src/adapters/drizzle-adapter/test/schema.ts (+1 -1)

...and 48 more files

📄 Description

TLDR

This PR was meant to only be the addition of createAdapter. However over time I realized a lot of other things relating to the adapter or databases that needed to be improved. Therefore this PR now includes a lot more things.

The primary things this PR does:

  • Introduce createAdapter.
  • Support useNumberId.
  • Modify database related options in the Better auth config to be under options.advanced.database. to keep things together.

What is createAdapter?

The createAdapter function will handle everything a database adapter shouldn't be.

The devs who create database adapters shouldn't have to worry about stuff like incorrect model names just because the end better-auth user had special configurations, or the fact that ID generations can be customized.

This createAdapter helper allows devs who create database adapters to only focus on database logic. No more need of worrying about whether the end user wanted plurals for model names, or if a given model already has defaultValues, let alone if the model name is accurate according to the schema. There are a lot of minor details which are important that a dev may not be aware of when creating a Better-Auth adapter.
This helper function will handle everything that Better-auth really should be handling before passing data to the adapter.

Another really important point:
In the future, if Better-Auth wants to make any adjustment towards how adapters work (eg add support for soft-deletes), development becomes much easier, faster and definitely more consistent to achieve.

What does this PR include?

createAdapter:

  • Add: createAdapter helper.
  • Add: tests for this new createAdapter helper.
  • Add: Documentation on createAdapter in docs.

useNumberId:

  • Add: useNumberId option under advanced.database to convert id fields referenced in where clauses and similar cases into numbers.
  • Add: Documentation for useNumberId.
  • Add: support for autoIncrement in drizzle schema generation when useNumberId is enabled.
  • Add: New useNumberId adapter tests, each DB adapter now tests this too.
  • Update: getMigrations to support useNumberId.

Misc:

  • Refactor: removed all id fields in any adapter.create call across Better-Auth. If there is a missed case where the id is there, it will throw an error in the console as well as stack traces to locate it. We should look to remove all id fields as the adapter will handle this.
  • Add: support for uuid in Drizzle schema generation for postgresql DB type.
  • Add: support for string[] and number[] field types in drizzle adapter schema generation.
  • Fix: Drizzle schema generation doesn't set the correct foreign key onDelete action based on schema.
  • Fix: Prisma schema generation doesn't set the correct foreign key onDelete action based on schema.
  • Add: MemoryAdapter parameter now has options to enable or disable debug logs.
  • Update(breaking): Moved generateId in BetterAuthOptions to be under advanced.database
  • Add: defaultFindManyLimit to BetterAuthOption's advanced.database.

Adapter tests:

  • Update: existing adapter tests to also make sure that all create methods will return an id.
  • Add: Option to skip any tests as needed for adapter tests.
  • Update: renamed memory.test to adapter.memory.test
  • Update: package.json's test:adapters script to run vitest adapter instead of vitest adapters since adapter tests names start with adapter.name.test, instead of adapters.name.test (Both the old script and new work, just changed it since it seemed more accurate)
  • Update: package.json's primsa push scripts. We now automatically push the prisma schemas during each tests automatically. Also there are 2 separate schemas now, one for the normal adpater tests, the other is for the autoIncrement number id tests.
  • Add: Option to pass testPrefix which adds that prefix in front of each test name.

Potential Breaking Changes ⚠️

  • generateId is no longer under advanced, instead it's now under advanced.database
    • Update: This is no longer removed in advanced, but I added @deprecated indicating to move to advanced.database.generateId. Also, there will be warning logs telling them to move it.

What's Next?

Future plans (by me) that may or may not be accepted into BetterAuth regarding adapters/databases:

  1. Transaction support.
  2. Soft-delete support.
  3. Support custom primary keys other than id. (Very unlikely)
  4. Database Indexing support.
  5. Database Hooks to support any table.
  6. createAdapter automatically routes secondaryStorage related tables to secondary storage.
  7. Support a more dynamic secondary storage system.

Todo:

  • createAdapter
    • Tests for createAdapter
    • Add Documentation.
    • Update DrizzleAdapter to use it.
    • Update KysleyAdapter to use it.
    • Update MemoryAdapter to use it.
    • Update PrismaAdapter to use it.
    • Update MongoDbAdapter to use it.
  • Update adapter tests to allow disabling any tests as needed
    • Update documentation regarding this ^
  • Add defaultFindManyLimit to BetterAuthOption's advanced.database obj.
    • Update documentation regarding this ^
  • Redesign the overall id system.
    • Remove all id fields in every adapter.create call. (Done as far as I'm aware, however it's possible that there are ones that I missed. In which case there will be warning logs to help track these down and remove them)
    • Support useNumberId.
      • createAdapter helper to support useNumberId.
      • Create tests for useNumberId.
      • Documentation for useNumberId.
      • DrizzleAdapter:
        • Adapter should support useNumberId
        • Schema generation support
        • Add the new useNumberId tests
        • ^ same for the mysql test file
      • KyselyAdapter:
        • Adapter should support useNumberId
        • Schema generation support
        • Migration support
        • Add the new useNumberId tests
      • MemoryAdapter:
        • Adapter should support useNumberId
        • Add the new useNumberId tests
      • MongoDbAdapter:
        • Adapter should support useNumberId (MongoDB doesn't support numeric IDs)
        • Add the new useNumberId tests
      • PrismaAdapter:
        • Adapter should support useNumberId
        • Schema generation support
        • Add the new useNumberId tests

Additional Notes:

Prisma Adapter Tests

Since the PrismaClient can only work on 1 prisma.schema at a time, it was tricky to make 2 primsa adapter tests with different PrismaClient instances.
The solution I ended up was to run a script which pushes the schema, after which will run an import to get the PrismaClient, then run the adapter test. Since the import was called asynchronously, after the schema was pushed, it means the PrismaClient is up-to-date with the new schema changes.

The second challenge was getting both prisma adapter tests to run one after another. Since normally tests can run alongside each other. This would cause each prisma adapter tests to push it's individual schemas consecutively, causing errors. So the solution I ended up doing was creating a state.txt file. The 2nd adapter tests will watch this state.txt file to change, and if it does, checks it's IDLE, if so it will run it's test. And I'm sure you can already guess that the first test will set this to RUNNING and then set it back to IDLE once it's finished.

Kysely Adapter tests

Similar situation as the Prisma adapter tests, similar solution to it.

createAdapter adapter-test debug log options & functions

Added the option to pass isRunningAdapterTests in the debugLogs option in the createAdapter config.
This option by default has the JSDoc of @deprecated thus hiding it (Or placing it at the very bottom of the menu for choosing methods in debugLogs options obj) from the IDE in case end-users accidentally enable it.
This should only be enabled during our adapter tests, which will essentially make all debugLog transactions save into memory, and whenever a test case fails, we will print that test's debug logs.

This really helps with debugging/finding issues while developing an adapter.

Note: These specifial adapterTestDebugLog functions are only in the result of createAdapter IF the config has enabled isRunningAdapterTests. Otherwise the result is just the normal Adapter.

Closes:

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/better-auth/better-auth/pull/1926 **Author:** [@ping-maxwell](https://github.com/ping-maxwell) **Created:** 3/21/2025 **Status:** ✅ Merged **Merged:** 4/11/2025 **Merged by:** [@Bekacru](https://github.com/Bekacru) **Base:** `main` ← **Head:** `refactor/adapter` --- ### 📝 Commits (10+) - [`5e2a0b2`](https://github.com/better-auth/better-auth/commit/5e2a0b28b5aa9f452a8202bfdf59d160ce90af98) refactor(adapter): `createAdapter` helper - [`b59edd9`](https://github.com/better-auth/better-auth/commit/b59edd9c199cbe28cebd135e2584acf77ef22812) update: Kysely adapter support - [`ffd184f`](https://github.com/better-auth/better-auth/commit/ffd184fc70f3b1f457cacd5eb8e96e05a7e007b8) update: memory adapter - [`b3fe580`](https://github.com/better-auth/better-auth/commit/b3fe580bc530948303e5a57c3188c81f31e0d9ff) chore: cleanup - [`3f17f31`](https://github.com/better-auth/better-auth/commit/3f17f31d1d4067631e5c9163c7c0c14370dab24c) update: MongoDB adapter supported - [`afd41fc`](https://github.com/better-auth/better-auth/commit/afd41fc2edfd833a11d3af97be500b8b13324675) update: mongodb adapter file names - [`4d78fcd`](https://github.com/better-auth/better-auth/commit/4d78fcd09c8f8f02f6a985da8a3693e5ad319886) update: support for prisma adapter - [`9f0ad1f`](https://github.com/better-auth/better-auth/commit/9f0ad1f3f24c09626c2087e544da62ca2d81734c) chore: lint - [`3fbad8f`](https://github.com/better-auth/better-auth/commit/3fbad8f9ab5548eb79aa481bdeab3ebd2b5295ac) fix: generate an `id` if it isn't already provided - [`8a3332c`](https://github.com/better-auth/better-auth/commit/8a3332cb35b4efd39cc89556df3413d6a8bebcfa) update(test): init config snapshot ### 📊 Changes **68 files changed** (+6500 additions, -2181 deletions) <details> <summary>View changed files</summary> 📝 `docs/components/sidebar-content.tsx` (+5 -0) 📝 `docs/content/docs/adapters/mongo.mdx` (+3 -1) ➕ `docs/content/docs/guides/create-a-db-adapter.mdx` (+563 -0) 📝 `docs/content/docs/reference/options.mdx` (+12 -7) 📝 `docs/package.json` (+1 -1) 📝 `examples/astro-example/package.json` (+1 -1) 📝 `examples/nuxt-example/package.json` (+1 -1) 📝 `examples/remix-example/package.json` (+1 -1) 📝 `examples/svelte-kit-example/package.json` (+44 -44) 📝 `packages/better-auth/build.config.ts` (+1 -0) 📝 `packages/better-auth/package.json` (+14 -3) 📝 `packages/better-auth/src/__snapshots__/init.test.ts.snap` (+11 -0) ➕ `packages/better-auth/src/adapters/create-adapter/index.ts` (+994 -0) ➕ `packages/better-auth/src/adapters/create-adapter/test/__snapshots__/create-adapter.test.ts.snap` (+7 -0) ➕ `packages/better-auth/src/adapters/create-adapter/test/create-adapter.test.ts` (+1467 -0) ➕ `packages/better-auth/src/adapters/create-adapter/types.ts` (+379 -0) 📝 `packages/better-auth/src/adapters/drizzle-adapter/drizzle-adapter.ts` (+265 -340) 📝 `packages/better-auth/src/adapters/drizzle-adapter/test/adapter.drizzle.mysql.test.ts` (+89 -32) 📝 `packages/better-auth/src/adapters/drizzle-adapter/test/adapter.drizzle.test.ts` (+70 -20) 📝 `packages/better-auth/src/adapters/drizzle-adapter/test/schema.ts` (+1 -1) _...and 48 more files_ </details> ### 📄 Description ## TLDR This PR was meant to only be the addition of `createAdapter`. However over time I realized a lot of other things relating to the adapter or databases that needed to be improved. Therefore this PR now includes a lot more things. The primary things this PR does: * Introduce `createAdapter`. * Support `useNumberId`. * Modify database related options in the Better auth config to be under `options.advanced.database.` to keep things together. ## What is `createAdapter`? The `createAdapter` function will handle everything a database adapter shouldn't be. The devs who create database adapters shouldn't have to worry about stuff like incorrect model names just because the end better-auth user had special configurations, or the fact that ID generations can be customized. This `createAdapter` helper allows devs who create database adapters to only focus on database logic. No more need of worrying about whether the end user wanted plurals for model names, or if a given model already has defaultValues, let alone if the model name is accurate according to the schema. There are a lot of minor details which are important that a dev may not be aware of when creating a Better-Auth adapter. This helper function will handle everything that Better-auth really should be handling before passing data to the adapter. Another really important point: In the future, if Better-Auth wants to make any adjustment towards how adapters work (eg add support for soft-deletes), development becomes **much** easier, faster and definitely more consistent to achieve. ## What does this PR include? ### **`createAdapter`**: * Add: `createAdapter` helper. * Add: tests for this new `createAdapter` helper. * Add: Documentation on `createAdapter` in docs. ### **`useNumberId`**: * Add: `useNumberId` option under `advanced.database` to convert id fields referenced in where clauses and similar cases into numbers. * Add: Documentation for `useNumberId`. * Add: support for autoIncrement in drizzle schema generation when `useNumberId` is enabled. * Add: New `useNumberId` adapter tests, each DB adapter now tests this too. * Update: `getMigrations` to support `useNumberId`. ### **Misc:** * Refactor: removed all `id` fields in any adapter.create call across Better-Auth. If there is a missed case where the `id` is there, it will throw an error in the console as well as stack traces to locate it. We should look to remove all `id` fields as the adapter will handle this. * Add: support for `uuid` in Drizzle schema generation for postgresql DB type. * Add: support for `string[]` and `number[]` field types in drizzle adapter schema generation. * Fix: Drizzle schema generation doesn't set the correct foreign key `onDelete` action based on schema. * Fix: Prisma schema generation doesn't set the correct foreign key `onDelete` action based on schema. * Add: MemoryAdapter parameter now has options to enable or disable debug logs. * Update(breaking): Moved `generateId` in BetterAuthOptions to be under `advanced.database` * Add: `defaultFindManyLimit` to BetterAuthOption's `advanced.database`. ### **Adapter tests:** * Update: existing adapter tests to also make sure that all `create` methods will return an `id`. * Add: Option to skip any tests as needed for adapter tests. * Update: renamed `memory.test` to `adapter.memory.test` * Update: `package.json`'s `test:adapters` script to run `vitest adapter` instead of `vitest adapters` since adapter tests names start with `adapter.name.test`, instead of `adapters.name.test` (Both the old script and new work, just changed it since it seemed more accurate) * Update: `package.json`'s primsa push scripts. We now automatically push the prisma schemas during each tests automatically. Also there are 2 separate schemas now, one for the normal adpater tests, the other is for the autoIncrement number id tests. * Add: Option to pass `testPrefix` which adds that prefix in front of each test name. ## Potential Breaking Changes ⚠️ * `generateId` is no longer under `advanced`, instead it's now under `advanced.database` * Update: This is no longer removed in `advanced`, but I added `@deprecated` indicating to move to `advanced.database.generateId`. Also, there will be warning logs telling them to move it. ## What's Next? Future plans (by me) that may or may not be accepted into BetterAuth regarding adapters/databases: 1. Transaction support. 3. Soft-delete support. 4. Support custom primary keys other than `id`. (Very unlikely) 5. Database Indexing support. 6. Database Hooks to support any table. 7. createAdapter automatically routes secondaryStorage related tables *to* secondary storage. 8. Support a more dynamic secondary storage system. ## Todo: - [x] `createAdapter` - [x] Tests for `createAdapter` - [x] Add Documentation. - [x] Update **DrizzleAdapter** to use it. - [x] Update **KysleyAdapter** to use it. - [x] Update **MemoryAdapter** to use it. - [x] Update **PrismaAdapter** to use it. - [x] Update **MongoDbAdapter** to use it. - [x] Update adapter tests to allow disabling any tests as needed - [x] Update documentation regarding this ^ - [x] Add `defaultFindManyLimit` to BetterAuthOption's `advanced.database` obj. - [x] Update documentation regarding this ^ - [x] Redesign the overall `id` system. - [x] Remove all `id` fields in every `adapter.create` call. (Done as far as I'm aware, however it's possible that there are ones that I missed. In which case there will be warning logs to help track these down and remove them) - [x] Support `useNumberId`. - [x] `createAdapter` helper to support `useNumberId`. - [x] Create tests for `useNumberId`. - [x] Documentation for `useNumberId`. - [x] **DrizzleAdapter:** - [x] Adapter should support `useNumberId` - [x] Schema generation support - [x] Add the new `useNumberId` tests - [x] ^ same for the `mysql` test file - [x] **KyselyAdapter:** - [x] Adapter should support `useNumberId` - [x] Schema generation support - [x] Migration support - [x] Add the new `useNumberId` tests - [x] **MemoryAdapter:** - [x] Adapter should support `useNumberId` - [x] Add the new `useNumberId` tests - [x] **MongoDbAdapter:** - [x] ~~Adapter should support `useNumberId`~~ (MongoDB doesn't support numeric IDs) - [x] ~~Add the new `useNumberId` tests~~ - [x] **PrismaAdapter:** - [x] Adapter should support `useNumberId` - [x] Schema generation support - [x] Add the new `useNumberId` tests ## Additional Notes: ### Prisma Adapter Tests Since the PrismaClient can only work on 1 prisma.schema at a time, it was tricky to make 2 primsa adapter tests with different PrismaClient instances. The solution I ended up was to run a script which pushes the schema, after which will run an `import` to get the PrismaClient, then run the adapter test. Since the import was called asynchronously, after the schema was pushed, it means the PrismaClient is up-to-date with the new schema changes. The second challenge was getting both prisma adapter tests to run one after another. Since normally tests can run alongside each other. This would cause each prisma adapter tests to push it's individual schemas consecutively, causing errors. So the solution I ended up doing was creating a `state.txt` file. The 2nd adapter tests will watch this state.txt file to change, and if it does, checks it's `IDLE`, if so it will run it's test. And I'm sure you can already guess that the first test will set this to `RUNNING` and then set it back to `IDLE` once it's finished. ### Kysely Adapter tests Similar situation as the Prisma adapter tests, similar solution to it. ### `createAdapter` adapter-test debug log options & functions Added the option to pass `isRunningAdapterTests` in the `debugLogs` option in the `createAdapter` config. This option by default has the JSDoc of `@deprecated` thus hiding it (Or placing it at the very bottom of the menu for choosing methods in `debugLogs` options obj) from the IDE in case end-users accidentally enable it. This should only be enabled during our adapter tests, which will essentially make all debugLog transactions save into memory, and whenever a test case fails, we will print that test's debug logs. This really helps with debugging/finding issues while developing an adapter. Note: These specifial *adapterTestDebugLog* functions are only in the result of `createAdapter` **IF** the config has enabled `isRunningAdapterTests`. Otherwise the result is just the normal `Adapter`. ## Closes: - https://github.com/better-auth/better-auth/pull/1325 - https://github.com/better-auth/better-auth/pull/1976 - https://github.com/better-auth/better-auth/pull/1299 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-03-13 11:31:24 -05:00
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 pull-request
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#4072
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?