Using TypeORM for Database Access in Node.js

Introduction

Working with relational databases in Node.js often requires a clean abstraction layer that simplifies queries, reduces boilerplate, and promotes predictable application structure. TypeORM provides these advantages through a mature and flexible ORM built for TypeScript and JavaScript. It supports multiple relational databases, integrates smoothly with modern backend frameworks like NestJS and Express, and encourages a domain-driven design approach. In this guide, you will learn how TypeORM works, how to structure your project for long-term maintainability, and which best practices help you build reliable data layers in Node.js applications.

Why TypeORM Is a Strong Choice for Node.js

Selecting the right ORM influences the quality and performance of your entire backend. TypeORM uses decorators, strong typing, and repository patterns that provide a natural development flow for TypeScript developers.

TypeORM supports PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, and Oracle, making it suitable for a wide range of architectures. The decorator-based entity definitions keep your domain logic close to your data model. Built-in migrations provide controlled schema evolution. Repository and Data Mapper patterns offer flexibility for different project sizes and team preferences.

These features make TypeORM more complete than many alternatives in the Node.js ecosystem.

Getting Started with TypeORM

Before building your first entity, you need to set up a project and configure a database connection.

Install TypeORM and Database Driver

npm install typeorm reflect-metadata pg
npm install -D @types/node typescript

PostgreSQL is used in this example, but you may install a different driver depending on your database choice.

Create a Data Source Configuration

import 'reflect-metadata';
import { DataSource } from 'typeorm';
import { User } from './entities/User';
import { Order } from './entities/Order';

export const AppDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  username: process.env.DB_USER || 'postgres',
  password: process.env.DB_PASSWORD || 'password',
  database: process.env.DB_NAME || 'app_db',
  synchronize: false, // Use migrations in production
  logging: process.env.NODE_ENV === 'development',
  entities: [User, Order],
  migrations: ['src/migrations/*.ts'],
  subscribers: ['src/subscribers/*.ts'],
});

// Initialize connection
AppDataSource.initialize()
  .then(() => console.log('Database connected'))
  .catch((error) => console.error('Database connection failed:', error));

Setting synchronize: false is essential for production environments where you want controlled schema changes through migrations rather than automatic modifications.

Defining Entities with TypeORM

Entities represent database tables. With TypeORM, decorators define fields, relations, and behaviors in a readable and structured way.

import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  Index,
  OneToMany,
} from 'typeorm';
import { Order } from './Order';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ length: 50, unique: true })
  @Index()
  username: string;

  @Column({ length: 255, unique: true })
  email: string;

  @Column({ select: false }) // Exclude from default queries
  passwordHash: string;

  @Column({ default: true })
  isActive: boolean;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @OneToMany(() => Order, (order) => order.user)
  orders: Order[];
}

The select: false option on passwordHash prevents sensitive data from being included in query results by default. Indexes on frequently queried columns improve performance significantly.

Working with Repositories

TypeORM provides repositories to encapsulate common database operations. Repositories abstract away direct query building for routine tasks.

import { AppDataSource } from './data-source';
import { User } from './entities/User';

const userRepository = AppDataSource.getRepository(User);

// Create and save a user
async function createUser(username: string, email: string, passwordHash: string) {
  const user = userRepository.create({
    username,
    email,
    passwordHash,
  });
  return await userRepository.save(user);
}

// Find user by username
async function findByUsername(username: string) {
  return await userRepository.findOne({
    where: { username },
    relations: ['orders'],
  });
}

// Update user
async function updateUser(id: string, updates: Partial) {
  await userRepository.update(id, updates);
  return await userRepository.findOneBy({ id });
}

// Soft delete (if using @DeleteDateColumn)
async function deactivateUser(id: string) {
  await userRepository.update(id, { isActive: false });
}

Repositories simplify data access and encourage consistent patterns across your project.

Relations and Joins

Real applications require relations between entities. TypeORM supports multiple relation types with intuitive decorators.

import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  ManyToOne,
  CreateDateColumn,
  JoinColumn,
} from 'typeorm';
import { User } from './User';

@Entity('orders')
export class Order {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column('decimal', { precision: 10, scale: 2 })
  total: number;

  @Column({ default: 'pending' })
  status: string;

  @ManyToOne(() => User, (user) => user.orders, { onDelete: 'CASCADE' })
  @JoinColumn({ name: 'user_id' })
  user: User;

  @Column()
  userId: string;

  @CreateDateColumn()
  createdAt: Date;
}

The onDelete: 'CASCADE' option automatically removes orders when their associated user is deleted. Including both the relation (user) and the foreign key column (userId) provides flexibility in how you access related data.

Querying Relations

// Eager loading with relations
const usersWithOrders = await userRepository.find({
  relations: ['orders'],
  where: { isActive: true },
});

// Query builder for complex queries
const activeUsersWithRecentOrders = await userRepository
  .createQueryBuilder('user')
  .leftJoinAndSelect('user.orders', 'order')
  .where('user.isActive = :active', { active: true })
  .andWhere('order.createdAt > :date', { date: new Date('2025-01-01') })
  .orderBy('order.createdAt', 'DESC')
  .getMany();

Migrations and Schema Management

Database migrations are essential for stable, controlled evolution of your schema. TypeORM includes a CLI that makes migration workflows straightforward.

# Generate migration from entity changes
npx typeorm migration:generate src/migrations/AddUserFields -d src/data-source.ts

# Create empty migration for custom SQL
npx typeorm migration:create src/migrations/SeedInitialData

# Run pending migrations
npx typeorm migration:run -d src/data-source.ts

# Revert last migration
npx typeorm migration:revert -d src/data-source.ts

A typical migration file looks like this:

import { MigrationInterface, QueryRunner } from 'typeorm';

export class AddUserFields1704067200000 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise {
    await queryRunner.query(`
      ALTER TABLE users ADD COLUMN phone VARCHAR(20)
    `);
    await queryRunner.query(`
      CREATE INDEX idx_users_phone ON users(phone)
    `);
  }

  public async down(queryRunner: QueryRunner): Promise {
    await queryRunner.query(`DROP INDEX idx_users_phone`);
    await queryRunner.query(`ALTER TABLE users DROP COLUMN phone`);
  }
}

Using migrations ensures consistency across development, staging, and production environments.

Working with Transactions

Transactions ensure data consistency when multiple operations must succeed or fail together.

import { AppDataSource } from './data-source';

async function createOrderWithItems(userId: string, items: OrderItem[]) {
  return await AppDataSource.transaction(async (manager) => {
    const orderRepo = manager.getRepository(Order);
    const itemRepo = manager.getRepository(OrderItem);

    const order = orderRepo.create({
      userId,
      total: items.reduce((sum, item) => sum + item.price, 0),
      status: 'pending',
    });
    await orderRepo.save(order);

    for (const item of items) {
      const orderItem = itemRepo.create({ ...item, orderId: order.id });
      await itemRepo.save(orderItem);
    }

    return order;
  });
}

If any operation within the transaction fails, all changes are rolled back automatically.

Real-World Production Scenario

Consider an e-commerce backend with 15-20 entities handling users, products, orders, inventory, and payments. The team uses TypeORM with PostgreSQL, running behind a NestJS API layer.

Initially, the project used synchronize: true during rapid development. As the team approached production, they switched to migration-based schema management. This transition required generating a baseline migration from the existing schema, but prevented accidental data loss from automatic schema changes.

Performance tuning involved adding indexes to frequently filtered columns like order.status and product.categoryId. The team discovered N+1 query issues when loading orders with their items and resolved them by using relations or query builder joins instead of lazy loading.

Connection pooling configuration proved important under load. Adjusting pool size and connection timeout settings prevented connection exhaustion during traffic spikes.

When to Use TypeORM

TypeORM fits well when your project needs a typed ORM with decorators that integrate naturally with TypeScript. The flexible repository pattern works for both small and large codebases. Built-in migrations provide controlled schema evolution. Clear relations between entities map well to domain models. The structure scales effectively as team size grows.

When NOT to Use TypeORM

For extremely simple applications with few tables, TypeORM’s learning curve might outweigh benefits. High-performance analytics queries often work better with raw SQL or query builders like Knex. If you prefer a more opinionated ORM with simpler configuration, Prisma offers a different approach that some teams find more intuitive.

Common Mistakes

Using synchronize: true in production risks data loss from automatic schema changes. Always use migrations for production environments.

Forgetting to add indexes on frequently queried columns causes slow queries as data grows. Review query plans regularly.

Not handling connection pool exhaustion leads to timeout errors under load. Configure appropriate pool sizes for your expected concurrency.

Loading relations unnecessarily with every query wastes resources. Use relations only when you need the related data.

Conclusion

TypeORM provides a clean and structured way to work with relational databases in Node.js. With its strong TypeScript support, decorators, repositories, and migrations, it helps teams build scalable and maintainable data layers. Start with simple entities and repositories, add migrations early, and optimize queries as your data grows.

If you want to continue exploring backend technologies, read “GraphQL Servers with Apollo & Express.” For guidance on choosing a backend framework, see “Framework Showdown: Flask vs FastAPI vs Django in 2025.” To learn more, visit the official TypeORM documentation. With the right patterns and structure, TypeORM becomes a powerful foundation for secure and efficient database access in Node.js.