feat(transactional-adapter-drizzle-orm): support better-sqlite3 via transactionMode option

[rodrigobnogueira]

Fixes #571.

Problem

@nestjs-cls/transactional-adapter-drizzle-orm wraps the inner Drizzle db.transaction(callback) callback in async. That works for async Drizzle drivers (libsql, node-postgres, postgres-js, mysql2) but breaks better-sqlite3 — its client.transaction(fn) is synchronous:

• On older better-sqlite3 versions, the driver sees the async callback's immediately-returned Promise as a successful sync return and runs BEGIN → callback → COMMIT before any work happens. The transaction commits empty and writes happen outside the tx scope.
• On better-sqlite3 v12+, the driver explicitly throws TypeError: Transaction function cannot return a promise.

See the linked issue for a self-contained in-memory repro.

Fix

New opt-in option on the adapter constructor:

transactionMode?: 'async' | 'sync' // default 'async'

In 'sync' mode, the adapter calls the driver's transaction(fn, options) with a synchronous callback and wraps the result in Promise.resolve(...) to satisfy the plugin's wrapWithTransaction: Promise<T> contract. The @Transactional()-decorated method must itself be sync (no async, no await inside) — the same constraint better-sqlite3 imposes on its own transaction callbacks. The decorator still returns Promise<T> to the caller.

Backward-compatible: every existing user passes no option, gets the default 'async', behaves exactly as before. The new code path is only entered when transactionMode: 'sync' is explicitly set.

Same shape applied to wrapWithNestedTransaction so savepoints work in sync mode too.

Tests

New file test/transactional-adapter-drizzle-orm-sync.spec.ts using better-sqlite3 in-memory (no docker required):

• T1 — insert + read inside @Transactional persists
• T2 — throw inside @Transactional rolls back (no rows)
• T3a — nested @Transactional commits both savepoints when outer succeeds
• T3b — outer throw rolls back nested savepoints
• T4 — outside @Transactional, falls back to raw client
• Two unit assertions on the transactionMode default vs explicit override

Existing Postgres async tests are unchanged. The 'async' code path is byte-identical to before; the new 'sync' branch is only entered when explicitly opted into.

Docs

Added a "better-sqlite3 (synchronous mode)" section to the Drizzle adapter docs page with the transactionMode: 'sync' example, the sync-method constraint, and the rationale. Existing pg/libsql examples are unchanged.

Discovered via

Building https://github.com/nest-native/reference-app — a reference app that uses @nestjs-cls/transactional with better-sqlite3 for local dev. The reference app currently ships an inlined version of this same adapter as a workaround; with this PR merged, it will drop the local file in favor of the upstream adapter with transactionMode: 'sync'.

[Papooch]

Thanks for the find and PR. I tried investigating if we can somehow auto-detect the driver and found out that Drizzle internally uses resultKind: sync|async`` to branch the transaction behavior. Curently it is used for better-sqlite3 and `bun-sqlite`.

It is a private field on the drizzleInstance, but I'm inclined to use it for auto-detection ((drizzleInstance as any).resultKind). I am not opposed to an explicit option, though, to force the behavior should the auto-detection fail for any reason.

[Papooch]

issue: I don't like that we have to go through an if every time at runtime. We can select the correct implementation at setup-time and assign a lambda directly:

const runTx = transactionMode == 'sync'
        ? (client: TClient, options: DrizzleTransactionOptions<TClient>, fn: () => any, setClient: (client?: TClient) => void) =>
            Promise.resolve(
                client.transaction((tx) => {
                    setClient(tx as TClient);
                    return fn();
                }, options),
            )
        : (client: TClient, options: DrizzleTransactionOptions<TClient>, fn: () => any, setClient: (client?: TClient) => void) =>
            client.transaction(async (tx) => {
                setClient(tx as TClient);
                return fn();
            }, options);

    return {
        wrapWithTransaction: (options, fn, setClient) =>
            runTx(drizzleInstance, options, fn, setClient),
        wrapWithNestedTransaction: (options, fn, setClient, client) =>
            runTx(client, options, fn, setClient),
        getFallbackInstance: () => drizzleInstance,

[rodrigobnogueira]

Done in 225f384: applied your pattern almost verbatim. runTx selected once inside optionsFactory; both wrap*Transaction are plain delegators now

[Papooch]

suggestion: on a second though, I guess we can just remove the async modifier here - it's redundant anyway. The behavior will be identical and support both sync and async callbacks.

Correct me if I'm wrong, but the suggested implementation only works around the typing of AnyDrizzleClient (with async transaction method), but does not add any runtime guarantees. I think we can instead relax that interface, knowing that Sqlite3 instance requires a sync method.

[Papooch]

@rodrigobnogueira I am confused, you put thumbs up on both of my comments, but commited something else

[rodrigobnogueira]

I'm sorry. I was working and you are fast :D

Done in 225f384

[rodrigobnogueira]

Thanks @Papooch for checking this PR.

Pushed in 92a465d. Auto-detection via (drizzleInstance as { resultKind?: unknown }).resultKind === 'sync'; explicit transactionMode: 'sync' | 'async' kept as an override.

One note: the pattern covers more than better-sqlite3 + bun-sqlite — resultKind: 'sync' is set on all five synchronous sqlite drivers (better-sqlite3, bun-sqlite, expo-sqlite, sql-js, durable-sqlite). Async sqlite drivers (libsql, op-sqlite, d1) carry resultKind: 'async'; non-sqlite drivers (node-postgres, postgres-js, mysql2) don't have the field. The === 'sync' check discriminates the first group from everything else.

Sync behavioral suite now omits transactionMode: 'sync' to prove auto-detect works; the existing Postgres suite is unchanged and still passes.

[rodrigobnogueira]

Refactored in 225f384: runTx selected once at setup time, AnyDrizzleClient relaxed (sync drivers' callbacks no longer have to pretend to return Promise), async dropped from both wrap*Transaction.

One small deviation: sync runTx keeps a try/catch -> Promise.reject(err) because better-sqlite3 throws synchronously on rollback, and the plugin contract needs that surfaced as a rejection.
Happy to drop it if you have a cleaner pattern in mind.

[Papooch]

Thank you, I still have one minor suggestion - if you have time, please address it.

[Papooch]

issue: the implementation here is still selected at run time (each time when runTx is called), not at setup time. I'd like it better if the correct runTx (perhaps effectiveRunTx) implementation was selected before being assigned passed to wrapWithTransaction and wrapWithNestedTransaction.

[Papooch]

cocnern: this is annoying, the linter is going to complain that we're awaiting a non-promise, but I can't think of a better solution in these circumstances