Proposal: Implicit Transaction Context in Drizzle ORM

[agcty]

Problem Statement

Currently, when working with transactions in Drizzle ORM, one we need to explicitly pass the transaction object to every function that needs to participate in the transaction. This leads to verbose code and makes it challenging to manage transactions across multiple function calls, especially in complex business logic.

Example of current approach:

async function inviteUserToOrganization(db, email, organizationId, roleName) {
  return db.transaction(async (trx) => {
    const organization = await findOrganization(trx, organizationId);
    if (!organization) throw new Error("Organization not found");

    const membership = await createPendingMembership(trx, email, organizationId);
    await addRoleToMembership(trx, membership.id, roleName);

    return membership;
  });
}

async function findOrganization(trx, organizationId) {
  return trx.query.organizations.findFirst({
    where: eq(schema.organizations.id, organizationId),
  });
}

async function createPendingMembership(trx, email, organizationId) {
  // Implementation using trx
}

async function addRoleToMembership(trx, membershipId, roleName) {
  // Implementation using trx
}

Proposed Solution

Implement an implicit transaction context using AsyncLocalStorage or a similar mechanism. This would allow functions to access the current transaction without explicitly passing it as an argument.

Example of proposed approach:

import { createTransactionContext } from 'drizzle-orm/transaction-context';

const { withTransaction, useTransaction } = createTransactionContext(db);

async function inviteUserToOrganization(email, organizationId, roleName) {
  return withTransaction(async () => {
    const organization = await findOrganization(organizationId);
    if (!organization) throw new Error("Organization not found");

    const membership = await createPendingMembership(email, organizationId);
    await addRoleToMembership(membership.id, roleName);

    return membership;
  });
}

async function findOrganization(organizationId) {
  const trx = useTransaction();
  return trx.query.organizations.findFirst({
    where: eq(schema.organizations.id, organizationId),
  });
}

async function createPendingMembership(email, organizationId) {
  const trx = useTransaction();
  // Implementation using trx
}

async function addRoleToMembership(membershipId, roleName) {
  const trx = useTransaction();
  // Implementation using trx
}

Benefits

1. Cleaner function signatures without the need to pass transaction objects explicitly.
2. Easier to manage transactions across multiple function calls and nested operations.
3. Improved readability and maintainability of business logic.
4. Flexibility to use transactions implicitly or explicitly as needed.

Implementation Considerations

1. Use AsyncLocalStorage or a similar mechanism to store the current transaction context.
2. Provide helper functions like withTransaction to create transaction contexts and useTransaction to access the current transaction.
3. Ensure proper error handling and transaction rollback in case of exceptions.
4. Consider providing options for transaction isolation levels and timeouts.

Questions for Discussion

1. Should this be implemented as a core feature of Drizzle ORM or as an optional plugin/extension?
2. How can we ensure this approach doesn't introduce significant performance overhead?
3. Are there any potential pitfalls or edge cases we should be aware of with this approach?
4. How can we make this feature TypeScript-friendly and provide good type inference?

Related Discussion

An old issue #1473 already brought up this idea and I think it has a valid point. It mentions https://www.baeldung.com/spring-transactional-propagation-isolation which could be taken as a reference for a drizzle implementation.

What are your thoughts on this? How are people rolling transaction context at the moment?

[bpdid]

This should probably be moved to the Ideas section because it might get "lost" in General.

[nickdeis]

Hey @agcty and @bpdid,

When I saw this, I thought it was a great idea, so I implemented it with some extras (savepoints + "safe mode").

Here's my opinion after doing so:

How can we ensure this approach doesn't introduce significant performance overhead?

In node v24+, the performance impact is non-existent.

In older versions, it's about ~7-20% cpu overhead (older versions being much worse). This typically equates to only added ms and is probably not noticeable compared to IO overhead.

However, I think I'd like to do my own performance tests at some point against in memory database instances. If you have any pointers, let me know!

Should this be implemented as a core feature of Drizzle ORM or as an optional plugin/extension?

As per my answer above: maybe this should be a plugin as performance is determined by the chosen runtime. Once node 24 becomes the next LTS, it should probably be added in.

Are there any potential pitfalls or edge cases we should be aware of with this approach?

Some common pitfalls can happen, which is why I implemented "safe mode" (naming? maybe debug mode?).

• Calling withTransaction within another withTransaction execution scope
• Calling withSavePoint outside of a withTransaction execution scope
• Calling useTransaction outside of a withTransaction execution scope
• Calling useSavePoint outside of a withSavePoint execution scope

I've implemented some workarounds that log the error as a warning. This is meant to lead a developer to fix these problems. When safe mode is off, these are thrown as errors.

How can we make this feature TypeScript-friendly and provide good type inference?

To be honest, this was probably the hardest thing to implement. I think I did a decent job since the database is correctly interfaced between a union type of Postgres, MySQL, and SQLite with a function overloading type to differentiate the three. From what I'm seeing: if I pass in PGLite, it resolves to showing PGLite as the database.

If either of you have any pointers, please let me know! And thank you for writing this spec @agcty , I made sure to credit you in the README 😃

[agcty]

Very cool, thanks for implementing this! Will try it out. In the meanwhile we have standardized on passing db as the last param for all our functions and with postgres this works fine. However, the problem with that approach is that you can easily nest transactions without knowing and depending on your db driver this might or might not be supported. Personally I'm curious toe see if drizzle effect will make this any easier by default.

[nickdeis]

Hey @agcty,

I may have handle that issue!

See here, where a nested transaction will either:

• Throw an error (if safe mode is off)
• Log that error as a warning, and execute that function within the same execution scope (if safe mode is on)

For savepoints, they usually can be nested, but apparently in some implementations they can't be? Not sure which ones though.