typeorm-patterns

TypeORM Patterns

Overview

This skill enforces TypeORM implementation patterns for the NestJS backend project. It ensures consistent database configuration, entity design, repository patterns, and observability across the codebase.

Core Requirements

Configuration Requirements

Requirement	Details
Module Pattern	TypeOrmModule.forRootAsync() with dataSourceFactory
Naming Strategy	SnakeNamingStrategy from typeorm-naming-strategies
Synchronize	Always false - migrations only, no auto-sync
Entity Loading	Explicit entity exports via index.ts (esbuild compatibility)
Database	PostgreSQL (local Docker, AWS Aurora Serverless v2 production)

Environment-Based Configuration

Environment	Connection Type	Authentication
Local	Direct connection	Environment variables
Production	Read-write replication	AWS RDS Signer (IAM)

Entity Requirements

Requirement	Details
Abstract Base	All entities extend TimestampedEntity (NOT TypeORM's BaseEntity)
Primary Key	UUID via @PrimaryGeneratedColumn("uuid")
Column Comments	Required on all columns via @Column({ comment: "..." })
Foreign Keys	Must be indexed via @Index() decorator
Cascade Deletes	Use orphanedRowAction: "delete" on OneToMany relations

Note: We use TimestampedEntity to avoid confusion with TypeORM's built-in BaseEntity class which provides Active Record pattern methods. Our abstract class only provides column inheritance.

Observability Requirements

Requirement	Details
Logger	Custom TypeOrmXRayLogger for distributed tracing
Graceful Degradation	Logger must work locally without X-Ray SDK
Query Tracking	Extract query type and table name for metrics

Quick Reference

Database Module Setup

Use the standard NestJS TypeOrmModule.forRootAsync() with dataSourceFactory for full control:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { DataSource } from "typeorm";
import { createTypeOrmOptions } from "./database.config";

/**
 * Database module using official NestJS TypeORM integration.
 *
 * @remarks
 * Uses forRootAsync with dataSourceFactory for:
 * - Async configuration (environment-based)
 * - Custom DataSource initialization
 * - Replication support with dynamic passwords
 */
@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      useFactory: createTypeOrmOptions,
      dataSourceFactory: async (options) => {
        const dataSource = new DataSource(options);
        return dataSource.initialize();
      },
    }),
  ],
})
export class DatabaseModule {}

Creating a New Entity

import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from "typeorm";
import { TimestampedEntity } from "./timestamped.entity";

/**
 * Represents a user in the system.
 *
 * @remarks
 * Users belong to organizations and can have multiple watchlists.
 */
@Entity({ comment: "Application users with organization membership" })
export class User extends TimestampedEntity {
  @Column({ comment: "User email address for authentication" })
  @Index()
  email: string;

  @Column({ comment: "User display name", nullable: true })
  name: string | null;

  @Column({ comment: "Foreign key to organization", type: "uuid" })
  @Index()
  organizationId: string;

  @ManyToOne(() => Organization, { onDelete: "SET NULL", nullable: true })
  @JoinColumn()
  organization: Organization;

  @OneToMany(() => Watchlist, w => w.user, { orphanedRowAction: "delete" })
  watchlists: Watchlist[];
}

Important: The abstract TimestampedEntity does NOT have an @Entity() decorator - only concrete child entities get this decorator.

Adding Entity to Exports

After creating any entity, add it to src/database/entities/index.ts:

export { User } from "./user.entity";
export { Organization } from "./organization.entity";
// Add new entity here

Using Repository Injection

With TypeOrmModule, use @InjectRepository() for standard repository access:

import { Injectable } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Repository } from "typeorm";
import { User } from "../entities/user.entity";

@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>
  ) {}

  async findByEmail(email: string): Promise<User | null> {
    return this.userRepository.findOne({ where: { email } });
  }
}

Creating a Custom Repository (When Needed)

Only create custom repositories when you need reusable query methods:

import { Injectable } from "@nestjs/common";
import { DataSource, Repository } from "typeorm";
import { User } from "../entities/user.entity";

/**
 * Custom repository for complex User queries.
 */
@Injectable()
export class UserRepository extends Repository<User> {
  constructor(private readonly dataSource: DataSource) {
    super(User, dataSource.createEntityManager());
  }

  /**
   * Find users with full-text search.
   */
  async searchByName(query: string): Promise<User[]> {
    return this.createQueryBuilder("user")
      .where("user.name ILIKE :query", { query: `%${query}%` })
      .getMany();
  }
}

Custom Repositories in Transactions

Critical: Class-based repositories extending Repository<T> do NOT work correctly inside transactions. Per TypeORM documentation, you must use withRepository():

// WRONG - repository uses wrong EntityManager, won't be transactional
async transferFunds(fromId: string, toId: string, amount: number): Promise<void> {
  await this.dataSource.transaction(async manager => {
    const from = await this.accountRepository.findOne({ where: { id: fromId } });
    // This query runs OUTSIDE the transaction!
  });
}

// CORRECT - use withRepository() for transactional operations
async transferFunds(fromId: string, toId: string, amount: number): Promise<void> {
  await this.dataSource.transaction(async manager => {
    const accountRepo = manager.withRepository(this.accountRepository);
    const from = await accountRepo.findOne({ where: { id: fromId } });
    // This query runs INSIDE the transaction
  });
}

Read-Write Routing

TypeORM automatically routes queries based on operation type when replication is configured:

Operation	Endpoint	Method Examples
Read	Slave (read replica)	find(), findOne(), query() with SELECT
Write	Master	save(), insert(), update(), delete()

To force a specific connection:

// Force master for reads (when consistency required)
await this.userRepository.manager.transaction(async manager => {
  const user = await manager.findOne(User, { where: { id } });
  // This read uses master connection
});

// QueryRunner for explicit control
const queryRunner = dataSource.createQueryRunner("master");
try {
  await queryRunner.query("SELECT * FROM users WHERE id = $1", [id]);
} finally {
  await queryRunner.release();
}

Migration Workflow

Always use the migration scripts - never modify migration files directly:

# Generate migration from entity changes
bun migration:generate --name=AddUserEmailIndex

# Run pending migrations
bun migration:run

# Revert last migration
bun migration:revert

File Structure

src/database/
├── database.module.ts          # NestJS module with TypeOrmModule.forRootAsync
├── database.config.ts          # Configuration factory
├── typeorm-xray-logger.ts      # Custom X-Ray logger
├── entities/
│   ├── index.ts                # Explicit entity exports
│   ├── timestamped.entity.ts   # Abstract base entity (no @Entity decorator)
│   ├── user.entity.ts
│   └── ...
├── repositories/               # Only if custom repositories needed
│   ├── index.ts
│   ├── user.repository.ts
│   └── ...
└── migrations/
    └── {timestamp}-{name}.ts

Detailed References

For comprehensive implementation details, see:

• references/configuration-patterns.md - TypeOrmModule setup, replication, environment configuration
• references/entity-patterns.md - Base entity, relationships, indexes, enums, views
• references/observability-patterns.md - X-Ray logger implementation with graceful degradation