feat: Add support for nested transaction rollbacks in SQL databases

This change adds support for handling rollbacks in nested transactions
in SQL databases. Specifically, the inner transaction should be rolled
back if the outer transaction fails.

To do this we keep track of the transaction ID and transaction depth so we can
re-use an existing open transaction in the underlying engine. This change also
allows the use of the `$transaction` method on an interactive transaction client.

depends-on: prisma/prisma-engines#4375

packages/adapter-d1/src/d1.ts

@@ -117,6 +117,12 @@ class D1Transaction extends D1Queryable<StdClient> implements Transaction {
     super(client)
   }
 
+  async begin(): Promise<Result<void>> {
+    debug(`[js::begin]`)
+
+    return ok(undefined)
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/adapter-libsql/src/libsql.ts

@@ -100,6 +100,15 @@ class LibSqlTransaction extends LibSqlQueryable<TransactionClient> implements Tr
     super(client)
   }
 
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async begin(): Promise<Result<void>> {
+    debug(`[js::commit]`)
+
+    throw new Error('Method not implemented.')
+
+    return ok(undefined)
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/adapter-neon/src/neon.ts

@@ -154,6 +154,13 @@ class NeonTransaction extends NeonWsQueryable<neon.PoolClient> implements Transa
     super(client)
   }
 
+  async begin(): Promise<Result<void>> {
+    debug(`[js::begin]`)
+
+    this.client.release()
+    return Promise.resolve(ok(undefined))
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/adapter-pg-worker/src/pg.ts

@@ -143,6 +143,13 @@ class PgTransaction extends PgQueryable<TransactionClient> implements Transactio
     super(client)
   }
 
+  async begin(): Promise<Result<void>> {
+    debug(`[js::begin]`)
+
+    this.client.release()
+    return ok(undefined)
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/adapter-pg/src/pg.ts

@@ -145,6 +145,13 @@ class PgTransaction extends PgQueryable<TransactionClient> implements Transactio
     super(client)
   }
 
+  async begin(): Promise<Result<void>> {
+    debug(`[js::begin]`)
+
+    this.client.release()
+    return ok(undefined)
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/adapter-planetscale/src/planetscale.ts

@@ -131,6 +131,13 @@ class PlanetScaleTransaction extends PlanetScaleQueryable<planetScale.Transactio
     super(tx)
   }
 
+  async begin(): Promise<Result<void>> {
+    debug(`[js::begin]`)
+
+    this.txDeferred.resolve()
+    return Promise.resolve(ok(await this.txResultPromise))
+  }
+
   async commit(): Promise<Result<void>> {
     debug(`[js::commit]`)
 

packages/client/package.json

@@ -199,7 +199,7 @@
     "@prisma/debug": "workspace:*",
     "@prisma/driver-adapter-utils": "workspace:*",
     "@prisma/engines": "workspace:*",
-    "@prisma/engines-version": "6.2.0-14.4123509d24aa4dede1e864b46351bf2790323b69",
+    "@prisma/engines-version": "6.3.0-2.integration-sql-nested-transactions5-9a074425ccc05b5ec12b88ec141ba5dea21472b7",
     "@prisma/fetch-engine": "workspace:*",
     "@prisma/generator-helper": "workspace:*",
     "@prisma/get-platform": "workspace:*",
@@ -208,7 +208,7 @@
     "@prisma/migrate": "workspace:*",
     "@prisma/mini-proxy": "0.9.5",
     "@prisma/pg-worker": "workspace:*",
-    "@prisma/query-engine-wasm": "6.2.0-14.4123509d24aa4dede1e864b46351bf2790323b69",
+    "@prisma/query-engine-wasm": "6.3.0-2.integration-sql-nested-transactions5-9a074425ccc05b5ec12b88ec141ba5dea21472b7",
     "@snaplet/copycat": "0.17.3",
     "@swc-node/register": "1.10.9",
     "@swc/core": "1.10.1",
@@ -278,4 +278,4 @@
     }
   },
   "sideEffects": false
-}
+}

packages/client/src/runtime/RequestHandler.ts

@@ -109,6 +109,14 @@ export class RequestHandler {
         const interactiveTransaction =
           request.transaction?.kind === 'itx' ? getItxTransactionOptions(request.transaction) : undefined
 
+        if (interactiveTransaction) {
+          interactiveTransaction.payload = {
+            // If the interactive transaction has a payload, we need to merge it with the new_tx_id
+            ...(interactiveTransaction.payload as any),
+            new_tx_id: interactiveTransaction?.id,
+          }
+        }
+
         const response = await this.client._engine.request(request.protocolQuery, {
           traceparent: this.client._tracingHelper.getTraceParent(),
           interactiveTransaction,

packages/client/src/runtime/core/engines/binary/BinaryEngine.ts

@@ -792,6 +792,7 @@ You very likely have the wrong "binaryTarget" defined in the schema.prisma file.
         max_wait: arg.maxWait,
         timeout: arg.timeout,
         isolation_level: arg.isolationLevel,
+        new_tx_id: arg?.newTxId,
       })
 
       const result = await Connection.onHttpError(

packages/client/src/runtime/core/engines/common/types/Transaction.ts

@@ -10,6 +10,7 @@ export type Options = {
   maxWait?: number
   timeout?: number
   isolationLevel?: IsolationLevel
+  newTxId?: string
 }
 
 export type InteractiveTransactionInfo<Payload = unknown> = {

packages/client/src/runtime/core/engines/data-proxy/DataProxyEngine.ts

@@ -443,6 +443,7 @@ export class DataProxyEngine implements Engine<DataProxyTxInfoPayload> {
             max_wait: arg.maxWait,
             timeout: arg.timeout,
             isolation_level: arg.isolationLevel,
+            new_tx_id: arg?.newTxId,
           })
 
           const url = await this.url('transaction/start')

packages/client/src/runtime/core/engines/library/LibraryEngine.ts

@@ -195,6 +195,7 @@ export class LibraryEngine implements Engine<undefined> {
         max_wait: arg.maxWait,
         timeout: arg.timeout,
         isolation_level: arg.isolationLevel,
+        new_tx_id: arg?.newTxId,
       })
 
       result = await this.engine?.startTransaction(jsonOptions, headerStr)

packages/client/src/runtime/core/types/exported/itxClientDenyList.ts

@@ -1,4 +1,4 @@
-const denylist = ['$connect', '$disconnect', '$on', '$transaction', '$use', '$extends'] as const
+const denylist = ['$connect', '$disconnect', '$on', '$use', '$extends'] as const
 
 export const itxClientDenyList = denylist as ReadonlyArray<string | symbol>
 

packages/client/src/runtime/getPrismaClient.ts

@@ -782,17 +782,21 @@ Or read our docs at https://www.prisma.io/docs/concepts/components/prisma-client
      */
     async _transactionWithCallback({
       callback,
-      options,
+      options = {},
     }: {
       callback: (client: Client) => Promise<unknown>
-      options?: Options
+      options?: Options & { newTxId?: string }
     }) {
+      if (this[TX_ID]) {
+        options.newTxId = this[TX_ID]
+      }
       const headers = { traceparent: this._tracingHelper.getTraceParent() }
 
       const optionsWithDefaults: Options = {
         maxWait: options?.maxWait ?? this._engineConfig.transactionOptions.maxWait,
         timeout: options?.timeout ?? this._engineConfig.transactionOptions.timeout,
         isolationLevel: options?.isolationLevel ?? this._engineConfig.transactionOptions.isolationLevel,
+        newTxId: options.newTxId,
       }
       const info = await this._engine.transaction('start', headers, optionsWithDefaults)
 
@@ -803,7 +807,6 @@ Or read our docs at https://www.prisma.io/docs/concepts/components/prisma-client
 
         result = await callback(this._createItxClient(transaction))
 
-        // it went well, then we commit the transaction
         await this._engine.transaction('commit', headers, info)
       } catch (e: any) {
         // it went bad, then we rollback the transaction

packages/client/src/runtime/utils/getRuntime.ts

@@ -5,7 +5,8 @@ const runtimesPrettyNames = {
   workerd: 'Cloudflare Workers',
   deno: 'Deno and Deno Deploy',
   netlify: 'Netlify Edge Functions',
-  'edge-light': 'Edge Runtime (Vercel Edge Functions, Vercel Edge Middleware, Next.js (Pages Router) Edge API Routes, Next.js (App Router) Edge Route Handlers or Next.js Middleware)',
+  'edge-light':
+    'Edge Runtime (Vercel Edge Functions, Vercel Edge Middleware, Next.js (Pages Router) Edge API Routes, Next.js (App Router) Edge Route Handlers or Next.js Middleware)',
 } as const
 
 type GetRuntimeOutput = {

packages/client/tests/functional/extensions/defineExtension.ts

@@ -220,7 +220,6 @@ function itxWithinGenericExtension() {
 
     void xclient.$transaction((tx) => {
       expectTypeOf(tx).toHaveProperty('helperMethod')
-      expectTypeOf(tx).not.toHaveProperty('$transaction')
       expectTypeOf(tx).not.toHaveProperty('$extends')
       return Promise.resolve()
     })

packages/client/tests/functional/extensions/itx.ts

@@ -315,7 +315,7 @@ testMatrix.setupTestSuite(
             if (isTransaction) {
               expect(ctx.$connect).toBeUndefined()
               expect(ctx.$disconnect).toBeUndefined()
-              expect(ctx.$transaction).toBeUndefined()
+              expect(ctx.$transaction).toBeDefined()
               expect(ctx.$extends).toBeUndefined()
             } else {
               expect(ctx.$connect).toBeDefined()

packages/client/tests/functional/extensions/query.ts

@@ -829,7 +829,7 @@ testMatrix.setupTestSuite(
               expectTypeOf(args).not.toBeAny()
               expectTypeOf(query).toBeFunction()
 
-              expectTypeOf(operation).toMatchTypeOf <
+              expectTypeOf(operation).toMatchTypeOf<
                 | 'findFirst'
                 | 'findFirstOrThrow'
                 | 'findUnique'

packages/client/tests/functional/interactive-transactions/tests.ts

@@ -1,3 +1,4 @@
+import { faker } from '@faker-js/faker'
 import { ClientEngineType } from '@prisma/internals'
 import { copycat } from '@snaplet/copycat'
 
@@ -30,7 +31,8 @@ testMatrix.setupTestSuite(
 
       await prisma
         // @ts-expect-error: Type 'void' is not assignable to type 'Promise<unknown>'
-        .$transaction(/* note how there's no `async` here */ (tx) => {
+        .$transaction(
+          /* note how there's no `async` here */ (tx) => {
             console.log('1')
             console.log(tx)
             console.log('2')
@@ -211,11 +213,77 @@ testMatrix.setupTestSuite(
       await expect(result).resolves.toHaveLength(2)
     })
 
+    /**
+     * If a parent transaction is rolled back, the child transaction should also rollback
+     * - This is only supported in SQL derived servers
+     */
+    testIf(provider === Providers.POSTGRESQL)('sql: nested rollback', async () => {
+      const rand1 = Math.floor(Math.random() * 1000)
+      const rand2 = rand1 + 1
+      const email1 = 'user_' + rand1 + '@website.com'
+      const email2 = 'user_' + rand2 + '@website.com'
+      const client = prisma
+      await expect(
+        client.$transaction(async (tx) => {
+          await tx.user.create({
+            data: {
+              email: email1,
+            },
+          })
+
+          await tx.$transaction(async (tx2) => {
+            await tx2.user.create({
+              data: {
+                email: email2,
+              },
+            })
+          })
+
+          // Abort the outer transaction
+          throw new Error('Rollback')
+        }),
+      ).rejects.toThrow(/Rollback/)
+
+      const result = await prisma.user.findMany({
+        where: {
+          email: {
+            in: [email1, email2],
+          },
+        },
+      })
+
+      // Both transactions should rollback
+      expect(result).toHaveLength(0)
+    })
+
+    testIf(provider === Providers.POSTGRESQL)('sql: multiple interactive transactions', async () => {
+      const existingEmail = faker.internet.email()
+
+      await prisma.$transaction(async (tx) => {
+        await tx.user.create({ data: { email: existingEmail } })
+      })
+
+      await prisma.$transaction(async (tx) => {
+        await tx.user.create({ data: { email: existingEmail + 1 } })
+      })
+
+      const result = await prisma.user.findMany({
+        where: {
+          email: {
+            in: [existingEmail, existingEmail + 1],
+          },
+        },
+      })
+
+      // Both transactions should succeed
+      expect(result).toHaveLength(2)
+    })
+
     /**
      * We don't allow certain methods to be called in a transaction
      */
     test('forbidden', async () => {
-      const forbidden = ['$connect', '$disconnect', '$on', '$transaction', '$use']
+      const forbidden = ['$connect', '$disconnect', '$on', '$use']
       expect.assertions(forbidden.length + 1)
 
       const result = prisma.$transaction((prisma) => {

packages/client/tests/functional/skip/_matrix.ts

@@ -1,6 +1,4 @@
 import { defineMatrix } from '../_utils/defineMatrix'
 import { allProviders } from '../_utils/providers'
 
-export default defineMatrix(() => [
-  allProviders,
-])
+export default defineMatrix(() => [allProviders])

packages/client/tests/functional/strictUndefinedChecks/_matrix.ts

@@ -1,6 +1,4 @@
 import { defineMatrix } from '../_utils/defineMatrix'
 import { allProviders } from '../_utils/providers'
 
-export default defineMatrix(() => [
-  allProviders,
-])
+export default defineMatrix(() => [allProviders])

packages/driver-adapter-utils/src/binder.ts

@@ -77,6 +77,7 @@ const bindTransaction = (errorRegistry: ErrorRegistryInternal, transaction: Tran
     options: transaction.options,
     queryRaw: wrapAsync(errorRegistry, transaction.queryRaw.bind(transaction)),
     executeRaw: wrapAsync(errorRegistry, transaction.executeRaw.bind(transaction)),
+    begin: wrapAsync(errorRegistry, transaction.begin.bind(transaction)),
     commit: wrapAsync(errorRegistry, transaction.commit.bind(transaction)),
     rollback: wrapAsync(errorRegistry, transaction.rollback.bind(transaction)),
   }

packages/driver-adapter-utils/src/types.ts

@@ -177,6 +177,10 @@ export interface Transaction extends Queryable {
    * Transaction options.
    */
   readonly options: TransactionOptions
+  /**
+   * Begin the transaction.
+   */
+  begin(): Promise<Result<void>>
   /**
    * Commit the transaction.
    */

packages/engines/package.json

@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@prisma/debug": "workspace:*",
-    "@prisma/engines-version": "6.2.0-14.4123509d24aa4dede1e864b46351bf2790323b69",
+    "@prisma/engines-version": "6.3.0-2.integration-sql-nested-transactions5-9a074425ccc05b5ec12b88ec141ba5dea21472b7",
     "@prisma/fetch-engine": "workspace:*",
     "@prisma/get-platform": "workspace:*"
   },
@@ -39,4 +39,4 @@
     "scripts"
   ],
   "sideEffects": false
-}
+}

packages/fetch-engine/package.json

@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@prisma/debug": "workspace:*",
-    "@prisma/engines-version": "6.2.0-14.4123509d24aa4dede1e864b46351bf2790323b69",
+    "@prisma/engines-version": "6.3.0-2.integration-sql-nested-transactions5-9a074425ccc05b5ec12b88ec141ba5dea21472b7",
     "@prisma/get-platform": "workspace:*"
   },
   "scripts": {
@@ -57,4 +57,4 @@
     "dist"
   ],
   "sideEffects": false
-}
+}