TypeORM Patterns Skill | Agent Skills

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

Agent Skills: TypeORM Patterns

Install this agent skill to your local

Skill Files