TypeORM Development Guidelines

You are an expert in TypeORM, TypeScript, and database design with a focus on the Data Mapper pattern and enterprise application architecture.

Core Principles

• TypeORM supports both Active Record and Data Mapper patterns
• Uses TypeScript decorators for entity and column definitions
• Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, and more
• Works in Node.js, Browser, Ionic, Cordova, React Native, NativeScript, Expo, and Electron
• First-class support for database migrations

TypeScript Configuration

Required settings in tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node"
  }
}

experimentalDecorators and emitDecoratorMetadata are both mandatory — without them decorators won't compile and column metadata won't resolve.

Entity Definition

A representative entity uses a generated primary key, typed @Columns, and the managed timestamp columns:

import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
} from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: 'varchar', length: 255, unique: true })
  email!: string;

  @Column({ type: 'varchar', length: 255, nullable: true })
  name!: string | null;

  @Column({ type: 'boolean', default: true })
  isActive!: boolean;

  @CreateDateColumn()
  createdAt!: Date;

  @UpdateDateColumn()
  updatedAt!: Date;
}

For the full primary-key options (UUID, custom, composite), the complete column decorator/option set (numeric, enum, JSON, soft-delete, version), and all relation types (one-to-one, one-to-many/many-to-one, many-to-many), see reference.md.

Data Source Configuration

// data-source.ts
import { DataSource } from 'typeorm';
import { User } from './entities/User';
import { Post } from './entities/Post';

export const AppDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,

  // Entity configuration
  entities: [User, Post],
  // Or use glob pattern: entities: ["src/entities/**/*.ts"]

  // Migrations
  migrations: ['src/migrations/**/*.ts'],

  // Synchronize - NEVER use in production
  synchronize: false,

  // Logging
  logging: process.env.NODE_ENV === 'development',

  // Connection pool
  poolSize: 10,

  // SSL (for production)
  ssl:
    process.env.NODE_ENV === 'production'
      ? { rejectUnauthorized: false }
      : false,
});

// Initialize connection
AppDataSource.initialize()
  .then(() => console.log('Data Source initialized'))
  .catch((error) => console.error('Error initializing Data Source:', error));

Quick Guidance

• Get a repository with AppDataSource.getRepository(Entity), then use find, findOne, create, save, update, delete, and softDelete.
• Load relations explicitly with relations: ['posts'] (or a leftJoinAndSelect in the query builder) instead of eager: true, to avoid N+1 query storms.
• Never use synchronize: true in production — generate and run migrations for every schema change.
• Index columns you frequently filter or look up via @Index().
• Always release() a manually created QueryRunner in a finally block.

Full API detail — repository methods, custom repositories, the query builder, migrations, transactions, framework integration, and best practices — lives in the reference.

Additional resources

• For the full entity/relation/query-builder/migration reference, see reference.md
• To scaffold a new entity file, run scripts/new-entity.sh <EntityName>
• To scaffold a new timestamped migration, run scripts/new-migration.sh <MigrationName>