Imagine a simple money transfer scenario. John sends money to his friend Sarah. The system successfully deducts money from John's account, but before it can credit Sarah's account, the application crashes. Without proper safeguards, John's money would disappear from the system, creating inconsistent and unreliable financial records.
To prevent this type of problem, database transactions are used. Transactions ensure that a group of related database operations either complete successfully together or fail together. If any part of the process encounters an error, all changes are reverted, ensuring that the database remains consistent.
Transactions make database operations atomic. Atomicity means that all operations inside a transaction are treated as a single unit of work. Either every operation succeeds and is committed to the database, or all operations fail and are rolled back. Partial updates are never permanently stored.
A database transaction is a group of one or more database operations executed as a single unit. Either all operations succeed together or all operations fail together. This guarantees database consistency even if an application crashes, a network failure occurs, or an unexpected error is encountered during execution.
It is important to understand that a transaction is not simply a single database query. While individual queries such as save, update, or delete interact with the database, a transaction wraps multiple queries inside a controlled all-or-nothing boundary. This prevents partial updates and ensures data integrity throughout the process.
Prerequisites
Before starting, make sure you have the following:
- Basic knowledge of NestJS
- Basic understanding of TypeORM
- Basic knowledge of PostgreSQL
- Understanding of basic database operations (save, update, delete) in TypeORM
Project Setup
In this article, we will create a simple NestJS application to demonstrate the importance of transactional queries when multiple database write or update operations must be executed together.
1 Create a New NestJS Application
Run the following command to create a new NestJS project:
nest new nestjs-transaction
2 Configure TypeORM
Create a config folder in the project root and create a file named typeorm.config.ts.
Install the required packages, including TypeORM, the PostgreSQL driver, and the configuration package:
npm i @nestjs/typeorm @nestjs/config typeorm pg
Now paste the following code into config/typeorm.config.ts:
import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { DataSource, DataSourceOptions } from 'typeorm';
ConfigModule.forRoot({ isGlobal: true });
const configService = new ConfigService();
const DB_PORT = configService.getOrThrow<number>('DATABASE_PORT');
export const typeOrmConfig: TypeOrmModuleOptions = {
type: 'postgres',
host: configService.getOrThrow<string>('HOST_NAME'),
port: DB_PORT,
username: configService.getOrThrow<string>('DATABASE_USERNAME'),
password: configService.getOrThrow<string>('DATABASE_PASSWORD'),
database: configService.getOrThrow<string>('DATABASE_NAME'),
entities: [__dirname + '/../**/*.entity.{js,ts}'],
migrations: [__dirname + '/../src/migrations/*.{js,ts}'],
synchronize: true,
};
export const dataSource = new DataSource(
typeOrmConfig as DataSourceOptions,
);
3 Environment Variables
Create a .env file in the project root and add the following values. Replace them with your own database credentials.
Make sure to create a PostgreSQL database named nestjs_transaction.
HOST_NAME=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=your_username
DATABASE_PASSWORD=your_password
DATABASE_NAME=nestjs_transaction
4 Create Entity
Create a file named user.entity.ts inside the src/user folder:
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
@Entity('user')
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column({ unique: true })
email: string;
@Column('decimal', {
precision: 10,
scale: 2,
default: 0,
})
balance: number;
}
5 Register TypeORM in AppModule
Register the database configuration in the application module:
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { typeOrmConfig } from '../config/typeorm.config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UserModule } from './user/user.module';
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
TypeOrmModule.forRoot(typeOrmConfig),
UserModule,
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}
6 Register User Entity, Providers, and Controllers in the User Module
Configure the User module to register the entity, repository, service, and controller:
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './user.entity';
import { UserRepository } from './user.repository';
import { UserService } from './user.service';
import { UserController } from './user.controller';
@Module({
imports: [TypeOrmModule.forFeature([User])],
providers: [UserRepository, UserService],
controllers: [UserController],
})
export class UserModule {}
7 Setup Service and Repository Demonstration Methods for Database Transactions
The official NestJS documentation recommends using the QueryRunner class when working with transactions because it provides complete control over transaction management. TypeORM supports multiple approaches for handling transactions, but QueryRunner offers the most flexibility and visibility into the transaction lifecycle.
The complete source code is available in the GitHub repository linked later in this article. Since the implementation contains additional supporting code, only the core transactional logic is discussed here.
// Send 500 from John to Sarah — with QueryRunner transaction
// Validation (existence + balance) happens here in the service
async sendMoney(): Promise<{ message: string }> {
const fromEmail = 'john@example.com';
const toEmail = 'sarah@example.com';
const amount = 500;
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
const sender = await this.userRepository.findByEmail(
fromEmail,
queryRunner,
);
if (!sender) throw new NotFoundException(`User ${fromEmail} not found`);
const receiver = await this.userRepository.findByEmail(
toEmail,
queryRunner,
);
if (!receiver) throw new NotFoundException(`User ${toEmail} not found`);
if (Number(sender.balance) < amount) {
throw new BadRequestException(
`Insufficient balance. John has ${sender.balance}, needs ${amount}`,
);
}
await this.userRepository.updateBalance(
sender.id,
Number(sender.balance) - amount,
queryRunner,
);
await this.userRepository.updateBalance(
receiver.id,
Number(receiver.balance) + amount,
queryRunner,
);
await queryRunner.commitTransaction();
return {
message: `Successfully transferred ${amount} from ${fromEmail} to ${toEmail}`,
};
} catch (err) {
await queryRunner.rollbackTransaction();
throw err;
} finally {
await queryRunner.release();
}
}
- The statement await queryRunner.startTransaction(); marks the beginning of the transaction. From this point onward, all database operations are executed within the transaction scope. Although changes are made during execution, none of them are permanently stored in the database until the transaction is committed.
- The statement await queryRunner.commitTransaction(); commits the transaction. When this line is executed successfully, all changes performed within the transaction become permanent and visible in the database.
- The statement await queryRunner.rollbackTransaction(); reverts all changes made within the transaction. Because it is located inside the catch block, it executes whenever an exception occurs before the transaction is committed. Any updates performed after the transaction started are undone, returning the database to its previous consistent state.
This transaction guarantees atomicity. Referring back to the original money transfer example, only one of the following outcomes is possible:
- The money is successfully deducted from John and credited to Sarah.
- No money is deducted from John at all.
A situation where money is removed from John's account without being credited to Sarah can never occur because the transaction prevents partial updates from being permanently stored.
8 Prepare APIs to Test Them
The GitHub project contains five APIs that demonstrate the difference between transactional and non-transactional database operations. These endpoints help visualize how transactions protect data integrity during failures.
POST http://localhost:3000/user/setup
Creates John with a balance of 1000 and Sarah with a balance of 500 inside a single transaction.
POST http://localhost:3000/user/send-money
Transfers 500 from John to Sarah using a QueryRunner transaction.
POST http://localhost:3000/user/send-money-no-transaction
Deducts 500 from John and then intentionally throws an error. Since no transaction is used, the deduction remains permanently stored in the database.
POST http://localhost:3000/user/send-money-with-transaction
Deducts 500 from John and then intentionally throws an error. Because a transaction is being used, the rollback mechanism restores John's original balance.
GET http://localhost:3000/user/balances
Returns all users and their current account balances.
By comparing the results of the transactional and non-transactional endpoints, the benefits of database transactions become immediately visible. The endpoint without a transaction leaves the database in an inconsistent state after failure, while the transactional endpoint automatically restores consistency through rollback.
Conclusion
Database transactions are one of the most important mechanisms for maintaining data integrity in modern applications. They ensure that related database operations execute as a single atomic unit, preventing partial updates and protecting the system from inconsistencies caused by failures, crashes, or unexpected exceptions.
Transactions provide guarantees such as atomicity, consistency, isolation, and durability, commonly known as the ACID properties. These guarantees are especially important in financial systems, inventory management platforms, booking systems, and any application where multiple database operations must succeed together.
In the money transfer example presented in this article, transactions ensure that funds are either completely transferred or not transferred at all. This creates reliability, trust, and confidence in the system.
As a general rule, whenever a service method performs multiple related database write operations that must succeed together, transactions should be considered an essential part of the implementation rather than an optional enhancement.
Contact
If you have any questions, feel free to reach out:
- LinkedIn: https://linkedin.com/in/dawit-girma-7b8867228/
- Email: realdavis7779@gmail.com
- GitHub: https://github.com/dedawit
The final code is available in the public repository:
https://github.com/dedawit/nestjs-transaction.git