TypeORM — synchronize: true Wiped a Production Table

TypeORM is the most popular ORM for TypeScript/Node.js applications. It follows the Active Record or Data Mapper pattern, letting you interact with your database using TypeScript classes and decorators rather than writing raw SQL.

The main advantage over raw queries: type safety. Refactoring column names propagates through the application with TypeScript compiler errors, not runtime bugs. The main disadvantage: complex queries are often easier to read as SQL than as QueryBuilder chains.

What TypeORM's Synchronize Flag Actually Does

TypeORM's `synchronize: true` is a development convenience that automatically creates database tables and columns based on your entity definitions at application startup. It mirrors your entity schema to the database schema on every application boot, effectively running DDL statements like CREATE TABLE, ALTER TABLE, and ADD COLUMN without explicit migrations.

In practice, this means TypeORM reads your entity decorators (e.g., @Entity, @Column) and generates corresponding SQL DDL. If you add a new column to an entity, synchronize will ALTER TABLE to add it. If you rename a column, synchronize will drop the old column and create a new one — losing all data in that column. It does not perform data migrations; it only ensures the schema structure matches the entity definitions at that moment.

Use `synchronize: true` only in local development or isolated test environments where data loss is acceptable. In any shared environment — staging, QA, or production — disable it and use proper migration scripts. The flag is not a substitute for version-controlled migrations; it is a rapid prototyping tool that becomes a liability the moment you have real data.

Setting Up TypeORM

The DataSource is the central hub of TypeORM — it holds the connection pool and entity registry. You configure it once at startup, usually in a separate file. The synchronize option should always be false in production; use migrations for schema evolution.

import { DataSource } from 'typeorm';
import { User } from './entities/User';
import { Post } from './entities/Post';

export const AppDataSource = new DataSource({
    type: 'postgres',
    host: 'localhost',
    port: 5432,
    username: 'postgres',
    password: 'password',
    database: 'myapp',
    entities: [User, Post],
    synchronize: false,       // NEVER use true in production — use migrations
    logging: ['query', 'error'],
});

// Initialize once at app startup
await AppDataSource.initialize();
console.log('Database connected');

Defining Entities

Entities are TypeScript classes decorated with @Entity. Each entity maps to a database table. Columns are defined with @Column, @PrimaryGeneratedColumn, etc. Relations use @OneToMany, @ManyToOne, @ManyToMany, and @JoinColumn to define foreign keys. Always specify the inverse side for bidirectional relations.

import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, OneToMany } from 'typeorm';
import { Post } from './Post';

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

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

    @Column()
    name: string;

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

    @CreateDateColumn()
    createdAt: Date;

    @OneToMany(() => Post, (post) => post.author)
    posts: Post[];
}

CRUD with Repository

The Repository pattern is the simplest way to interact with a single entity. Use dataSource.getRepository(Entity) to get a repository instance. For simple operations like create, read, update, delete, the repository methods are enough. For complex queries — joins, aggregations, subqueries — switch to QueryBuilder.

const userRepo = AppDataSource.getRepository(User);

// CREATE
const user = userRepo.create({ name: 'Alice', email: 'alice@example.com' });
await userRepo.save(user);
console.log('Created user:', user.id);

// READ
const found = await userRepo.findOne({ where: { email: 'alice@example.com' } });
const all   = await userRepo.find({ where: { isActive: true } });

// READ with relations
const withPosts = await userRepo.findOne({
    where: { id: 1 },
    relations: { posts: true }
});
console.log(withPosts?.posts.length);

// UPDATE
await userRepo.update({ id: 1 }, { name: 'Alice Smith' });

// DELETE
await userRepo.delete({ id: 1 });

// QueryBuilder for complex queries
const activeUsers = await userRepo
    .createQueryBuilder('user')
    .leftJoinAndSelect('user.posts', 'post')
    .where('user.isActive = :active', { active: true })
    .andWhere('post.id IS NOT NULL')
    .orderBy('user.createdAt', 'DESC')
    .getMany();

Relations: Loading Strategies and Pitfalls

TypeORM relations are lazy by default — they don't load related entities unless you explicitly ask for them. You can load relations via the 'relations' option in find/findOne, or via leftJoinAndSelect in QueryBuilder. Eager relations (set with { eager: true }) load automatically but can cause N+1 if used carelessly. The biggest production pitfall: assuming relations are always loaded.

// Lazy loading (default) — need to specify relations
const user = await userRepo.findOne({ where: { id: 1 } });
console.log(user.posts); // undefined — not loaded

// Eager loading
const user = await userRepo.findOne({
    where: { id: 1 },
    relations: { posts: true }
});
console.log(user.posts); // loaded

// QueryBuilder loading
const user = await userRepo
    .createQueryBuilder('user')
    .leftJoinAndSelect('user.posts', 'post')
    .where('user.id = :id', { id: 1 })
    .getOne();
console.log(user.posts); // loaded

Migrations: Safe Schema Evolution

Migrations are the only safe way to change your database schema in production. TypeORM's migration system generates SQL files based on entity changes. Always review the generated SQL before running. Use migration:generate to create a migration, then migration:run to apply. Never edit migration files manually unless you understand the full impact.

# Generate a migration after changing entities
npx typeorm migration:generate -d src/data-source.ts src/migrations/AddEmailVerifiedColumn

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

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

# Show status
npx typeorm migration:show -d src/data-source.ts

Who the Hell Is This For? (Audience)

You're already debugging a JOIN that's pulling 40MB of JSON into an Express route at 2 AM. That's who this is for.

TypeORM isn't a toy. It's an ORM that'll happily let you shoot your own foot if you treat it like a magical black box. This blog is for the developer who's been burned by an ORM before — someone who wants to know why synchronize: true just wrote 47 unintended indexes to production, not just how to flip the flag.

If you're still writing findOne with no where clause and hoping for the best, close the tab. Come back when you've cleaned up a migration conflict at 3 AM. Otherwise, keep reading — we're about to talk about the parts of TypeORM that the docs skip because they'd rather sell you a happy story.

What You’d Better Know Before Touching This Shit (Prerequisites)

TypeORM is a thin wrapper over SQL and TypeScript. If you can't write a raw SQL JOIN without panicking, you're going to have a bad time. Before you start wiring up entities and decorators, nail these:

• TypeScript basics — generics, decorators, async/await. If typeof vs instanceof confuses you, go read the handbook.
• SQL fundamentals — SELECT, INSERT, UPDATE, DELETE, and what an index actually does. TypeORM generates SQL; you need to read the query log to know when it's generating garbage.
• Relational database design — normalisation, foreign keys, cascade deletes (and why they're a trap). The ORM will enforce relations only if you let it.
• Node.js runtime — module resolution, transpilation, process lifecycle. TypeORM runs in Node, so know your event loop from your callback queue.

If you're missing any of these, save yourself the headache. Install SQLite, write a few raw queries, then come back. You'll thank me when your first migration doesn't nuke the user table.

// io.thecodeforge — database tutorial

-- Can you read this query and predict its execution plan?
SELECT 
  u.id,
  u.email,
  o.total_amount,
  o.created_at
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE o.created_at > '2024-01-01'
  AND u.is_active = true
ORDER BY o.total_amount DESC;

-- If not, go learn SQL first. TypeORM hides complexity, not competence.

Operators in TypeORM Query Builder

TypeORM's Query Builder gives you fine-grained control over SQL operators. Without them, you're stuck with basic equality queries. Operators let you filter by patterns (LIKE), ranges (BETWEEN), inclusion (IN), and null checks (IS NULL). Each operator maps directly to a Query Builder method: .where('age BETWEEN :min AND :max') or .andWhere('name LIKE :name'). The key insight: operator methods return the same query builder, so you chain them. Use :param placeholders instead of string interpolation to prevent injection. Start with Where, add AndWhere or OrWhere for compound conditions. The NOT operator inverts: .notBrackets() wraps exclusions. Logical operators combine with brackets for precedence. This replaces writing raw SQL strings while keeping full expressiveness.

// io.thecodeforge — database tutorial

-- TypeORM Query Builder operators
WHERE age BETWEEN :minAge AND :maxAge
AND name LIKE :searchPattern
AND role IN (:...roles)
AND deletedAt IS NULL
AND (status = 'active' OR status = 'pending')

// Parameterized: safer than string concat
.createQueryBuilder('user')
.where('user.age BETWEEN :min AND :max', { min: 18, max: 65 })
.andWhere('user.name LIKE :name', { name: '%John%' })
.andWhere('user.role IN (:...roles)', { roles: ['admin', 'mod'] })

Working Directory Gotchas with TypeOrm

TypeORM resolves entity paths, migration files, and config relative to the process working directory—not your project root. Run npm run from a subfolder? TypeORM might fail to find entity/*.ts. Fix it: set process.env.NODE_PATH or use absolute paths in ormconfig.ts. The root directory determines where TypeORM writes migration files and reads entities. Migration g:co generates files in the current working directory. If your CI runs from a different directory, migrations won't match. Always store TypeORM config with __dirname-based paths to decouple from runtime cwd. Test by running commands from random directories. Common failure: No entity metadata found because entity glob resolves to a wrong relative path.

// io.thecodeforge — database tutorial

-- Use __dirname for reliable path resolution
import { DataSource } from 'typeorm';
import path from 'path';

export const AppDataSource = new DataSource({
  type: 'postgres',
  entities: [path.join(__dirname, 'entity/*.{ts,js}')],
  migrations: [path.join(__dirname, 'migration/*.{ts,js}')],
  // Never rely on relative './' — fails on different cwd
});

// Test: run from /app/src/ but cwd is /app/
// With above: 'entity/*.ts' resolves correctly

Importing from TypeORM Correctly

TypeORM exports dozens of decorators, functions, and types. Importing the wrong thing causes cryptic errors. Core rule: Entity, Column, PrimaryGeneratedColumn come from typeorm main package. Repository methods (find, save, delete) live on Repository type, also from typeorm. The biggest trap: importing EntityRepository (deprecated) instead of using @Injectable() in NestJS or dataSource.getRepository(). For Query Builder, import SelectQueryBuilder from typeorm only when you need its type. For runtime usage, the actual object is returned by createQueryBuilder(). Avoid star imports (import * as ...) — they pull everything. Use named imports with only what you need: import { Entity, Column, BaseEntity } from 'typeorm'.

// io.thecodeforge — database tutorial

// Correct imports (TypeORM 0.3+)
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  ManyToOne,
  JoinColumn,
  Repository,
} from 'typeorm';

// Wrong: cannot use deprecated EntityRepository
// const repo = await getRepository(User); // old API

// Right: use dataSource.getRepository()
const userRepo: Repository<User> = dataSource.getRepository(User);
const users = await userRepo.find({ where: { isActive: true } });

TypeORM in 2026: Current State and Migration to Prisma or Drizzle

As of 2026, TypeORM remains a widely-used ORM for TypeScript and JavaScript, but its ecosystem has evolved significantly. While TypeORM still receives maintenance updates, newer ORMs like Prisma and Drizzle have gained traction due to their type safety, performance, and developer experience. Prisma offers a declarative schema language and auto-generated queries, while Drizzle provides a lightweight, SQL-like query builder with full TypeScript support. If you are considering migrating from TypeORM, evaluate factors such as query complexity, migration tooling, and team familiarity. For example, migrating a simple CRUD app to Prisma involves rewriting entity definitions as Prisma schema and replacing repository calls with Prisma Client. A migration to Drizzle might require converting TypeORM query builders to Drizzle's SQL-like syntax. Both Prisma and Drizzle support PostgreSQL, MySQL, SQLite, and other databases. However, TypeORM still excels in complex relationships and legacy codebases. The decision should be based on project requirements, not hype. Below is an example of a TypeORM entity and its equivalent in Prisma and Drizzle.

-- TypeORM Entity (for reference)
CREATE TABLE "user" (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
);

-- Prisma Schema equivalent
-- model User {
--   id    Int     @id @default(autoincrement())
--   name  String
--   email String  @unique
-- }

-- Drizzle Schema equivalent
-- import { pgTable, serial, varchar } from 'drizzle-orm/pg-core';
-- export const users = pgTable('users', {
--   id: serial('id').primaryKey(),
--   name: varchar('name', { length: 255 }).notNull(),
--   email: varchar('email', { length: 255 }).notNull().unique(),
-- });

TypeORM Data Mapper vs Active Record Patterns

TypeORM supports both the Data Mapper and Active Record patterns, each with distinct trade-offs. In the Active Record pattern, entities themselves contain methods for persistence (e.g., user.save(), user.remove()). This pattern is simpler and intuitive for small projects but can lead to tight coupling between business logic and database access. In contrast, the Data Mapper pattern separates entities (plain objects) from repositories that handle persistence. This promotes cleaner separation of concerns and testability, especially in larger applications. TypeORM's default is Active Record, but you can switch to Data Mapper by defining repositories. For example, with Active Record, you define an entity extending BaseEntity: class User extends BaseEntity { ... }. With Data Mapper, you define a plain entity and a repository: const userRepository = dataSource.getRepository(User). The choice impacts scalability and maintainability. In production, Data Mapper is generally preferred for complex domains, while Active Record can be acceptable for simple CRUD apps. Below is a comparison of both patterns in TypeORM.

-- Active Record Pattern (Entity with save method)
-- CREATE TABLE "user" (
--     id SERIAL PRIMARY KEY,
--     name VARCHAR(255) NOT NULL
-- );
-- In code: const user = new User(); user.name = 'John'; await user.save();

-- Data Mapper Pattern (Repository-based)
-- Same table, but in code:
-- const user = new User(); user.name = 'John';
-- await userRepository.save(user);

TypeORM Migrations: Production Deployment Workflow

Running migrations in production requires a careful workflow to avoid data loss or downtime. TypeORM migrations are JavaScript/TypeScript files that define up and down methods. The typical production workflow involves: (1) Generate a migration using typeorm migration:create or typeorm migration:generate after schema changes. (2) Review the generated SQL for correctness, especially for destructive operations like DROP COLUMN or ALTER TABLE. (3) Run migrations in a staging environment first. (4) In production, use a CI/CD pipeline that runs migrations as a separate step before deploying the application code. Never use synchronize: true in production. Instead, rely on migrations. For zero-downtime deployments, consider using expand-contract pattern: add new columns without removing old ones, then migrate data, and finally remove old columns in a later migration. Always back up the database before running migrations. Example migration file below.

-- Example migration: Add 'age' column to 'user' table
-- Up migration
ALTER TABLE "user" ADD COLUMN "age" integer NOT NULL DEFAULT 0;

-- Down migration (rollback)
ALTER TABLE "user" DROP COLUMN "age";

-- In TypeORM migration file:
-- import { MigrationInterface, QueryRunner } from "typeorm";
-- export class AddAgeColumn1234567890123 implements MigrationInterface {
--     name = 'AddAgeColumn1234567890123';
--     public async up(queryRunner: QueryRunner): Promise<void> {
--         await queryRunner.query(`ALTER TABLE "user" ADD "age" integer NOT NULL DEFAULT '0'`);
--     }
--     public async down(queryRunner: QueryRunner): Promise<void> {
--         await queryRunner.query(`ALTER TABLE "user" DROP COLUMN "age"`);
--     }
-- }