feat: database transaction support (#4414)

Co-authored-by: Joel Solano <solano.joel@gmx.de>

Author: himself65

docs/content/docs/adapters/mongo.mdx

@@ -20,7 +20,7 @@ const client = new MongoClient("mongodb://localhost:27017/database");
 const db = client.db();
 
 export const auth = betterAuth({
- database: mongodbAdapter(db),
+ database: mongodbAdapter(db, { client }),
 });
 ```
 

docs/content/docs/guides/create-a-db-adapter.mdx

@@ -452,6 +452,16 @@ const adapter = myAdapter({
 });
 ```
 
+### `transaction`
+
+Whether the adapter supports transactions. If `false`, operations run sequentially; otherwise provide a function that executes a callback with a `TransactionAdapter`.
+
+<Callout type="warn">
+ If your database does not support transactions, the error handling and rollback
+ will not be as robust. We recommend using a database that supports transactions
+ for better data integrity.
+</Callout>
+
 ### `debugLogs`
 
 Used to enable debug logs for the adapter. You can pass in a boolean, or an object with the following keys: `create`, `update`, `updateMany`, `findOne`, `findMany`, `delete`, `deleteMany`, `count`.

packages/better-auth/src/__snapshots__/init.test.ts.snap

@@ -20,11 +20,13 @@ exports[`init > should match config 1`] = `
  "supportsDates": false,
  "supportsJSON": false,
  "supportsNumericIds": true,
+ "transaction": [Function],
  "usePlural": undefined,
  },
  "debugLogs": false,
  "type": "sqlite",
  },
+ "transaction": [Function],
  "update": [Function],
  "updateMany": [Function],
  },

packages/better-auth/src/adapters/create-adapter/index.ts

@@ -1,13 +1,17 @@
 import { safeJSONParse } from "../../utils/json";
 import { withApplyDefault } from "../../adapters/utils";
 import { getAuthTables } from "../../db/get-tables";
-import type { Adapter, BetterAuthOptions, Where } from "../../types";
+import type {
+Adapter,
+BetterAuthOptions,
+TransactionAdapter,
+Where,
+} from "../../types";
 import { generateId as defaultGenerateId, logger } from "../../utils";
 import type {
-AdapterConfig,
+CreateAdapterOptions,
 AdapterTestDebugLogs,
 CleanedWhere,
-CreateCustomAdapter,
 } from "./types";
 import type { FieldAttribute } from "../../db";
 export * from "./types";
@@ -45,14 +49,13 @@ const colors = {
 },
 };
 
+const createAsIsTransaction =
+(adapter: Adapter) =>
+<R>(fn: (trx: TransactionAdapter) => Promise<R>) =>
+fn(adapter);
+
 export const createAdapter =
-({
-adapter,
-config: cfg,
-}: {
-config: AdapterConfig;
-adapter: CreateCustomAdapter;
-}) =>
+({ adapter: customAdapter, config: cfg }: CreateAdapterOptions) =>
 (options: BetterAuthOptions): Adapter => {
 const config = {
 ...cfg,
@@ -315,7 +318,7 @@ export const createAdapter =
 return fields[defaultFieldName];
 };
 
-const adapterInstance = adapter({
+const adapterInstance = customAdapter({
 options,
 schema,
 debugLog,
@@ -560,7 +563,24 @@ export const createAdapter =
 }) as any;
 };
 
-return {
+let lazyLoadTransaction: Adapter["transaction"] | null = null;
+const adapter: Adapter = {
+transaction: async (cb) => {
+if (!lazyLoadTransaction) {
+if (!config.transaction) {
+logger.warn(
+`[${config.adapterName}] - Transactions are not supported. Executing operations sequentially.`,
+);
+lazyLoadTransaction = createAsIsTransaction(adapter);
+} else {
+logger.debug(
+`[${config.adapterName}] - Using provided transaction implementation.`,
+);
+lazyLoadTransaction = config.transaction;
+}
+}
+return lazyLoadTransaction(cb);
+},
 create: async <T extends Record<string, any>, R = T>({
 data: unsafeData,
 model: unsafeModel,
@@ -1016,6 +1036,7 @@ export const createAdapter =
 }
 : {}),
 };
+return adapter;
 };
 
 function formatTransactionId(transactionId: number) {

packages/better-auth/src/adapters/create-adapter/types.ts

@@ -3,6 +3,7 @@ import type { BetterAuthDbSchema } from "../../db/get-tables";
 import type {
 AdapterSchemaCreation,
 BetterAuthOptions,
+TransactionAdapter,
 Where,
 } from "../../types";
 import type { Prettify } from "../../types/helper";
@@ -32,6 +33,11 @@ export type AdapterDebugLogs =
 isRunningAdapterTests: boolean;
  };
 
+export type CreateAdapterOptions = {
+config: AdapterConfig;
+adapter: CreateCustomAdapter;
+};
+
 export interface AdapterConfig {
 /**
  * Use plural table names.
@@ -89,6 +95,15 @@ export interface AdapterConfig {
  * @default true
  */
 supportsBooleans?: boolean;
+/**
+ * Execute multiple operations in a transaction.
+ *
+ * If the database doesn't support transactions, set this to `false` and operations will be executed sequentially.
+ *
+ */
+transaction?:
+| false
+| (<R>(callback: (trx: TransactionAdapter) => Promise<R>) => Promise<R>);
 /**
  * Disable id generation for the `create` method.
  *

packages/better-auth/src/adapters/drizzle-adapter/drizzle-adapter.ts

@@ -17,8 +17,13 @@ import {
 SQL,
 } from "drizzle-orm";
 import { BetterAuthError } from "../../error";
-import type { Where } from "../../types";
-import { createAdapter, type AdapterDebugLogs } from "../create-adapter";
+import type { Adapter, BetterAuthOptions, Where } from "../../types";
+import {
+createAdapter,
+type AdapterDebugLogs,
+type CreateAdapterOptions,
+type CreateCustomAdapter,
+} from "../create-adapter";
 
 export interface DB {
 [key: string]: any;
@@ -52,17 +57,21 @@ export interface DrizzleAdapterConfig {
  * @default false
  */
 camelCase?: boolean;
+/**
+ * Whether to execute multiple operations in a transaction.
+ *
+ * If the database doesn't support transactions,
+ * set this to `false` and operations will be executed sequentially.
+ * @default true
+ */
+transaction?: boolean;
 }
 
-export const drizzleAdapter = (db: DB, config: DrizzleAdapterConfig) =>
-createAdapter({
-config: {
-adapterId: "drizzle",
-adapterName: "Drizzle Adapter",
-usePlural: config.usePlural ?? false,
-debugLogs: config.debugLogs ?? false,
-},
-adapter: ({ getFieldName, debugLog }) => {
+export const drizzleAdapter = (db: DB, config: DrizzleAdapterConfig) => {
+let lazyOptions: BetterAuthOptions | null = null;
+const createCustomAdapter =
+(db: DB): CreateCustomAdapter =>
+({ getFieldName, debugLog }) => {
 function getSchema(model: string) {
 const schema = config.schema || db._.fullSchema;
 if (!schema) {
@@ -343,5 +352,31 @@ export const drizzleAdapter = (db: DB, config: DrizzleAdapterConfig) =>
 },
 options: config,
 };
+};
+let adapterOptions: CreateAdapterOptions | null = null;
+adapterOptions = {
+config: {
+adapterId: "drizzle",
+adapterName: "Drizzle Adapter",
+usePlural: config.usePlural ?? false,
+debugLogs: config.debugLogs ?? false,
+transaction:
+(config.transaction ?? true)
+? (cb) =>
+db.transaction((tx: DB) => {
+const adapter = createAdapter({
+config: adapterOptions!.config,
+adapter: createCustomAdapter(tx),
+})(lazyOptions!);
+return cb(adapter);
+})
+: false,
 },
-});
+adapter: createCustomAdapter(db),
+};
+const adapter = createAdapter(adapterOptions);
+return (options: BetterAuthOptions): Adapter => {
+lazyOptions = options;
+return adapter(options);
+};
+};

packages/better-auth/src/adapters/kysely-adapter/kysely-adapter.ts

@@ -1,5 +1,10 @@
-import { createAdapter, type AdapterDebugLogs } from "../create-adapter";
-import type { Where } from "../../types";
+import {
+createAdapter,
+type AdapterDebugLogs,
+type CreateCustomAdapter,
+type CreateAdapterOptions,
+} from "../create-adapter";
+import type { Adapter, BetterAuthOptions, Where } from "../../types";
 import type { KyselyDatabaseType } from "./types";
 import type { InsertQueryBuilder, Kysely, UpdateQueryBuilder } from "kysely";
 
@@ -20,26 +25,23 @@ interface KyselyAdapterConfig {
  * @default false
  */
 usePlural?: boolean;
+/**
+ * Whether to execute multiple operations in a transaction.
+ *
+ * If the database doesn't support transactions,
+ * set this to `false` and operations will be executed sequentially.
+ * @default true
+ */
+transaction?: boolean;
 }
 
-export const kyselyAdapter = (db: Kysely<any>, config?: KyselyAdapterConfig) =>
-createAdapter({
-config: {
-adapterId: "kysely",
-adapterName: "Kysely Adapter",
-usePlural: config?.usePlural,
-debugLogs: config?.debugLogs,
-supportsBooleans:
-config?.type === "sqlite" || config?.type === "mssql" || !config?.type
-? false
-: true,
-supportsDates:
-config?.type === "sqlite" || config?.type === "mssql" || !config?.type
-? false
-: true,
-supportsJSON: false,
-},
-adapter: ({ getFieldName, schema }) => {
+export const kyselyAdapter = (
+db: Kysely<any>,
+config?: KyselyAdapterConfig,
+) => {
+let lazyOptions: BetterAuthOptions | null = null;
+const createCustomAdapter = (db: Kysely<any>): CreateCustomAdapter => {
+return ({ getFieldName, schema }) => {
 const withReturning = async (
 values: Record<string, any>,
 builder:
@@ -315,5 +317,43 @@ export const kyselyAdapter = (db: Kysely<any>, config?: KyselyAdapterConfig) =>
 },
 options: config,
 };
+};
+};
+let adapterOptions: CreateAdapterOptions | null = null;
+adapterOptions = {
+config: {
+adapterId: "kysely",
+adapterName: "Kysely Adapter",
+usePlural: config?.usePlural,
+debugLogs: config?.debugLogs,
+supportsBooleans:
+config?.type === "sqlite" || config?.type === "mssql" || !config?.type
+? false
+: true,
+supportsDates:
+config?.type === "sqlite" || config?.type === "mssql" || !config?.type
+? false
+: true,
+supportsJSON: false,
+transaction:
+(config?.transaction ?? true)
+? (cb) =>
+db.transaction().execute((trx) => {
+const adapter = createAdapter({
+config: adapterOptions!.config,
+adapter: createCustomAdapter(trx),
+})(lazyOptions!);
+return cb(adapter);
+})
+: false,
 },
-});
+adapter: createCustomAdapter(db),
+};
+
+const adapter = createAdapter(adapterOptions);
+
+return (options: BetterAuthOptions): Adapter => {
+lazyOptions = options;
+return adapter(options);
+};
+};

packages/better-auth/src/adapters/memory-adapter/adapter.memory.test.ts

@@ -24,6 +24,10 @@ describe("adapter test", async () => {
 ...customOptions,
 });
 },
+disableTests: {
+SHOULD_ROLLBACK_FAILING_TRANSACTION: true,
+SHOULD_RETURN_TRANSACTION_RESULT: true,
+},
 });
 });
 

packages/better-auth/src/adapters/memory-adapter/memory-adapter.ts

@@ -4,6 +4,7 @@ import {
 type AdapterDebugLogs,
 type CleanedWhere,
 } from "../create-adapter";
+import type { BetterAuthOptions } from "../../types";
 
 export interface MemoryDB {
 [key: string]: any[];
@@ -13,8 +14,9 @@ export interface MemoryAdapterConfig {
 debugLogs?: AdapterDebugLogs;
 }
 
-export const memoryAdapter = (db: MemoryDB, config?: MemoryAdapterConfig) =>
-createAdapter({
+export const memoryAdapter = (db: MemoryDB, config?: MemoryAdapterConfig) => {
+let lazyOptions: BetterAuthOptions | null = null;
+let adapterCreator = createAdapter({
 config: {
 adapterId: "memory",
 adapterName: "Memory Adapter",
@@ -30,6 +32,18 @@ export const memoryAdapter = (db: MemoryDB, config?: MemoryAdapterConfig) =>
 }
 return props.data;
 },
+transaction: async (cb) => {
+let clone = structuredClone(db);
+try {
+return cb(adapterCreator(lazyOptions!));
+} catch {
+// Rollback changes
+Object.keys(db).forEach((key) => {
+db[key] = clone[key];
+});
+throw new Error("Transaction failed, rolling back changes");
+}
+},
 },
 adapter: ({ getFieldName, options, debugLog }) => {
 function convertWhereClause(where: CleanedWhere[], model: string) {
@@ -147,3 +161,8 @@ export const memoryAdapter = (db: MemoryDB, config?: MemoryAdapterConfig) =>
 };
 },
 });
+return (options: BetterAuthOptions) => {
+lazyOptions = options;
+return adapterCreator(options);
+};
+};