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 } });