Torben Sorensen
d356d9dfb6
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 43s
63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# ADR-002: Standardized Transaction Management and Unit of Work Pattern
|
|
|
|
**Date**: 2025-12-12
|
|
|
|
**Status**: Accepted
|
|
|
|
**Implemented**: 2026-01-07
|
|
|
|
## Context
|
|
|
|
Following the standardization of error handling in ADR-001, the next most common source of architectural inconsistency and potential bugs is database transaction management. Currently, several repository methods (`createUser`, `createFlyerAndItems`, etc.) implement their own transaction logic by manually acquiring a client from the connection pool, and then managing `BEGIN`, `COMMIT`, and `ROLLBACK` states.
|
|
|
|
This manual approach has several drawbacks:
|
|
**Repetitive Boilerplate**: The `try/catch/finally` block for transaction management is duplicated across multiple files.
|
|
**Error-Prone**: It is easy to forget to `client.release()` in all code paths, which can lead to connection pool exhaustion and bring down the application. 3. **Poor Composability**: It is difficult to compose multiple repository methods into a single, atomic "Unit of Work". For example, a service function that needs to update a user's points and create a budget in a single transaction cannot easily do so if both underlying repository methods create their own transactions.
|
|
|
|
## Decision
|
|
|
|
We will implement a standardized "Unit of Work" pattern through a high-level `withTransaction` helper function. This function will abstract away the complexity of transaction management.
|
|
|
|
1. **`withTransaction` Helper**: A new helper function, `withTransaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>`, will be created. This function will be responsible for:
|
|
- Acquiring a client from the database pool.
|
|
- Starting a transaction (`BEGIN`).
|
|
- Executing the `callback` function, passing the transactional client to it.
|
|
- If the callback succeeds, it will `COMMIT` the transaction.
|
|
- If the callback throws an error, it will `ROLLBACK` the transaction and re-throw the error.
|
|
- In all cases, it will `RELEASE` the client back to the pool.
|
|
|
|
2. **Repository Method Signature**: Repository methods that need to be part of a transaction will be updated to optionally accept a `PoolClient` in their constructor or as a method parameter. By default, they will use the global pool. When called from within a `withTransaction` block, they will be passed the transactional client.
|
|
3. **Service Layer Orchestration**: Service-layer functions that orchestrate multi-step operations will use `withTransaction` to ensure atomicity. They will instantiate or call repository methods, providing them with the transactional client from the callback.
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
// In a service file...
|
|
async function registerUserAndCreateDefaultList(userData) {
|
|
return withTransaction(async (client) => {
|
|
// Pass the transactional client to the repositories
|
|
const userRepo = new UserRepository(client);
|
|
const shoppingRepo = new ShoppingRepository(client);
|
|
|
|
const newUser = await userRepo.createUser(userData);
|
|
await shoppingRepo.createShoppingList(newUser.user_id, 'My First List');
|
|
|
|
return newUser;
|
|
});
|
|
}
|
|
```
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
**DRY (Don't Repeat Yourself)**: Transaction logic is defined in one place, eliminating boilerplate from repository and service files.
|
|
**Safety and Reliability**: Guarantees that clients are always released, preventing connection leaks. Ensures proper rollback on any error.
|
|
**Clear Composability**: Provides a clear and explicit pattern for composing multiple database operations into a single atomic unit.
|
|
**Improved Readability**: Service logic becomes cleaner, focusing on the business operations rather than the mechanics of transaction management.
|
|
|
|
### Negative
|
|
|
|
**Learning Curve**: Developers will need to learn and adopt the `withTransaction` pattern for all transactional database work.
|
|
**Refactoring Effort**: Existing methods that manually manage transactions (`createUser`, `createBudget`, etc.) will need to be refactored to use the new pattern.
|