From 05303cb857d2c706d2511ee1aa67ebefdfb50e96 Mon Sep 17 00:00:00 2001
From: Maxwell <145994855+ping-maxwell@users.noreply.github.com>
Date: Wed, 8 Oct 2025 04:47:12 +1000
Subject: [PATCH] docs: improve database docs (#5146)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Alex Yang <himself65@outlook.com>
---
 docs/content/docs/concepts/database.mdx | 58 +++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/docs/content/docs/concepts/database.mdx b/docs/content/docs/concepts/database.mdx
index 6d7b42e1..25f111cd 100644
--- a/docs/content/docs/concepts/database.mdx
+++ b/docs/content/docs/concepts/database.mdx
@@ -482,9 +482,7 @@ import { betterAuth } from "better-auth";
 import { db } from "./db";
 
 export const auth = betterAuth({
-  database: {
-    db: db,
-  },
+  database: db,
   advanced: {
     database: {
       generateId: false,
@@ -493,10 +491,63 @@ export const auth = betterAuth({
 });
 ```
 
+**Example: Using a Custom ID Generator**
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth";
+import { db } from "./db";
+
+export const auth = betterAuth({
+  database: db,
+  advanced: {
+    database: {
+      generateId: () => crypto.randomUUID(),
+    },
+  },
+});
+```
+
+### Numeric IDs
+
+If you prefer auto-incrementing numeric IDs, you can set the `advanced.database.useNumberId` option to `true`.
+Doing this will disable Better-Auth from generating IDs for any table, and will assume your
+database will generate the numeric ID automatically.
+
+When enabled, the Better-Auth CLI will generate or migrate the schema with the `id` field as a numeric type for your database
+with auto-incrementing attributes associated with it.
+
+```ts
+import { betterAuth } from "better-auth";
+import { db } from "./db";
+
+export const auth = betterAuth({
+  database: db,
+  advanced: {
+    database: {
+      useNumberId: true,
+    },
+  },
+});
+```
+
+<Callout type="info">
+  Better-Auth will continue to infer the type of the `id` field as a `string` for the database, but will
+  automatically convert it to a numeric type when fetching or inserting data from the database.
+
+  It's likely when grabbing `id` values returned from Better-Auth that you'll receive a string version of a number,
+  this is normal. It's also expected that all id values passed to Better-Auth (eg via an endpoint body) is expected to be a string.
+</Callout>
+
+
 ### Database Hooks
 
 Database hooks allow you to define custom logic that can be executed during the lifecycle of core database operations in Better Auth. You can create hooks for the following models: **user**, **session**, and **account**.
 
+<Callout type="warn">
+  Additional fields are supported, however full type inference for these fields isn't yet supported.
+  Improved type support is planned.
+</Callout>
+
 There are two types of hooks you can define:
 
 #### 1. Before Hook
@@ -522,6 +573,7 @@ export const auth = betterAuth({
           // Modify the user object before it is created
           return {
             data: {
+              // Ensure to return Better-Auth named fields, not the original field names in your database.
               ...user,
               firstName: user.name.split(" ")[0],
               lastName: user.name.split(" ")[1],