Налаштування TypeORM для веб-застосунку: сутності, міграції, репозиторії

При розробці на Node.js і TypeScript багато хто стикається з однією і тією ж болем: ручне написання SQL-запитів і синхронізація схеми з кодом. Помилка в SQL-запиті — і production лежить. TypeORM вирішує цю проблему, але його налаштування вимагає врахування десятка нюансів: від конфігурації підключення до генерації міграцій. Ми допоможемо вам налаштувати TypeORM під ваш проєкт — від простого сервера до складного NestJS-застосунку. Наші інженери мають понад 10 років досвіду роботи з реляційними базами даних і гарантують стабільність вашої схеми.

Чому стандартне налаштування TypeORM часто призводить до проблем?

N+1 запит TypeORM — класична проблема при роботі з ORM. Без оптимізації завантаження 100 статей з авторами породить 101 запит. TypeORM дозволяє легко налаштувати жадібне завантаження через relations або використовувати Query Builder для точного контролю. Ще одна біль — synchronize: true в production: це призводить до втрати даних при зміні схеми. Правильне налаштування міграцій з генерацією diff-файлів — єдиний безпечний спосіб оновлювати базу. Третя проблема — продуктивність: неоптимізовані запити створюють зайве навантаження. TypeORM дає інструменти для моніторингу та тонкого налаштування: subscribers для кешування, пул підключень, логування повільних запитів. При типовому навантаженні 10 000 запитів на хвилину грамотне налаштування знижує кількість запитів на 60%.

Як ми налаштовуємо TypeORM: розбір кейсу

Наш клієнт мав проєкт з PostgreSQL і навантаженням 10 000 запитів на хвилину. Ми зіткнулися з падінням продуктивності через N+1 при завантаженні пов'язаних тегів. Рішення: використали Query Builder з leftJoinAndSelect і пагінацію через skip/take. Додатково налаштували пул з'єднань з max: 20 і idleTimeoutMillis: 30000, що знизило час відповіді на 40%. Використання Query Builder дозволило виконати складний запит у 3 рази швидше порівняно із завантаженням через relations. Правильне налаштування пулу з'єднань заощадило клієнту близько 150 000 грн на рік на інфраструктурі. Замовте налаштування TypeORM — отримайте консультацію інженера протягом години.

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

export const AppDataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  entities: [User, Post],
  migrations: ['dist/db/migrations/*.js'],
  migrationsTableName: 'migrations',
  synchronize: false,  // НІКОЛИ true в production
  logging: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
  extra: {
    max: 20,
    idleTimeoutMillis: 30000,
  }
})

// Ініціалізація
await AppDataSource.initialize()

Що входить в налаштування TypeORM?

Процес роботи проходить п'ять етапів:

1. Аналітика — вивчаємо поточну схему БД, навантаження та профіль запитів.
2. Проектування — обираємо патерн (Active Record або Data Mapper), проектуємо сутності та зв'язки.
3. Реалізація — налаштовуємо підключення, пишемо сутності з декораторами, створюємо міграції та репозиторії.
4. Тестування — перевіряємо продуктивність, відсутність N+1 та коректність міграцій.
5. Деплой та моніторинг — розгортаємо на production, налаштовуємо логування та алерти.

У результат налаштування входить:

• Конфігурація DataSource з пулом та SSL (під будь-яку БД: PostgreSQL, MySQL, SQLite).
• Репозиторії та сутності з індексами та зв'язками.
• Міграції (генерація, запуск, відкат).
• Query Builder для типових запитів.
• Інтеграція з NestJS (модуль, сервіси, контролери).
• Підписки (subscribers) для кешування та сповіщень.
• Документація по API та архітектурі.
• Гарантія на 30 днів після здачі — виправляємо помилки безкоштовно.

Порівняння патернів та вибір сутності

Наші інженери завжди рекомендують Data Mapper для проєктів з бізнес-логікою, оскільки він дає більше контролю та спрощує тестування. Але якщо вам потрібне швидке прототипування — Active Record теж робочий варіант. Правильний вибір сутності критичний для продуктивності. Використовуйте @PrimaryGeneratedColumn('uuid') для розподілених систем, @Index() для полів, які часто фільтруються. Репозиторій — це прошарок між бізнес-логікою та БД. Обгортайте в репозиторій всі запити до сутності: це робить код перевикористовуваним і тестованим.

Приклад репозиторію з пагінацією:

const postRepository = AppDataSource.getRepository(Post)

async function findPosts(opts: { page: number; limit: number; search?: string }) {
  const { page, limit, search } = opts
  const qb = postRepository.createQueryBuilder('post')
    .leftJoinAndSelect('post.author', 'author')
    .leftJoinAndSelect('post.tags', 'tag')
    .where('post.published = :published', { published: true })
    .orderBy('post.createdAt', 'DESC')
    .skip((page - 1) * limit)
    .take(limit)

  if (search) {
    qb.andWhere(
      'post.title ILIKE :search OR post.content ILIKE :search',
      { search: `%${search}%` }
    )
  }

  const [items, total] = await qb.getManyAndCount()
  return { items, total, pages: Math.ceil(total / limit) }
}

// Складні агрегати
const stats = await AppDataSource.query(`
  SELECT
    date_trunc('week', created_at) AS week,
    count(*) AS posts,
    count(*) FILTER (WHERE published = true) AS published
  FROM posts
  WHERE created_at >= now() - interval '90 days'
  GROUP BY 1
  ORDER BY 1
`)

Чому міграції важливі для продакшену?

Згідно з офіційною документацією TypeORM, міграції — єдиний безпечний спосіб управління схемою в production. Міграції дозволяють версіонувати зміни схеми бази даних і застосовувати їх послідовно. TypeORM вміє автоматично генерувати міграції на основі змін у сутностях. Це економить до 50% часу на розробку міграцій порівняно з ручним написанням SQL. Приклад генерації та застосування:

# Генерація міграції з diff схеми
npx typeorm migration:generate -n AddUserProfile -d dist/db/data-source.js

# Створити пусту міграцію вручну
npx typeorm migration:create -n AddIndexes

# Застосувати
npx typeorm migration:run -d dist/db/data-source.js

# Відкотити останню
npx typeorm migration:revert -d dist/db/data-source.js

// db/migrations/1234567890-AddUserProfile.ts
import { MigrationInterface, QueryRunner } from 'typeorm'

export class AddUserProfile1234567890 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
      CREATE TABLE profiles (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        user_id UUID NOT NULL UNIQUE REFERENCES users(id) ON DELETE CASCADE,
        bio TEXT,
        avatar_url VARCHAR(500),
        updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
      )
    `)
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP TABLE profiles`)
  }
}

Інтеграція з NestJS та підписки на події

У NestJS налаштування TypeORM зводиться до імпорту TypeOrmModule з конфігурацією. Додатково можна впроваджувати репозиторії через декоратор @InjectRepository. Subscribers (підписки) дозволяють реагувати на зміни сутностей: після вставки оновити пошуковий індекс, після публікації — відправити сповіщення. Це потужний інструмент, якщо не зловживати. Приклад налаштування NestJS:

// app.module.ts
import { TypeOrmModule } from '@nestjs/typeorm'

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        url: config.get('DATABASE_URL'),
        entities: [__dirname + '/**/*.entity{.ts,.js}'],
        migrations: [__dirname + '/db/migrations/*{.ts,.js}'],
        migrationsRun: true,
        synchronize: false,
      })
    }),
    TypeOrmModule.forFeature([User, Post])
  ]
})
export class AppModule {}

Орієнтовні терміни та вартість

Базова настройка TypeORM з сутностями, міграціями та репозиторіями: 1–2 дні. Інтеграція в NestJS-проєкт з модулями та тестами: 2–3 дні. Переведення існуючого проєкту з іншого ORM на TypeORM: 3–5 днів. Вартість базової конфігурації TypeORM починається від 35 000 грн і залежить від складності проєкту. Зв'яжіться з нами для оцінки — це безкоштовно і займе не більше години.

TypeORM на GitHub

TypeORM має понад 30 000 зірок на GitHub та понад 400 контриб'юторів, що свідчить про його популярність і активний розвиток.

Послуги бекенд-розробки: production-grade надійність

На production-сервері о 3:14 ночі черга Laravel Jobs перестала оброблятися — 40 000 необроблених завдань у Redis. Причина: worker упав через memory leak у статичній змінній Eloquent observer, supervisor не перезапустив через misconfigured stopwaitsecs. Ми розбирали такий інцидент на проекті з 500 RPS: діагностика 4 години, фікс — 20 хвилин. Щоб ви не втрачали гроші, пропонуємо послуги бекенд-розробки з акцентом на production-grade надійність — 10+ років досвіду, 50+ проектів, 5 років на ринку. Оцінимо ваш проект за 2 дні.

Які проблеми вирішуємо

N+1 запити: головний вбивця швидкості

N+1 — найпоширеніша причина повільних сторінок у Laravel-додатках. Стандартна історія: сторінка працювала нормально на dev з 10 записами, на production з 10 000 — 8-секундне завантаження.

Laravel Debugbar у dev-оточенні показує кількість запитів. Більше 20 — сигнал для audit.

Model::preventLazyLoading(! app()->isProduction());

Telescope для профілювання: логує всі запити, jobs, mail, notifications з деталізацією. Після впровадження eager loading час завантаження сторінки падає з 8 с до 0.3 с — у 27 разів.

Memory leak у статичних змінних

У Laravel Octane або Swoole додаток тримається в пам’яті між запитами. Статичні змінні не скидаються — призводять до неконтрольованого росту пам’яті. Використовуємо defer-функції та контейнерні біндинги для коректного скидання стану.

Неправильний connection pool

Rails, Laravel, Django відкривають нове з'єднання PostgreSQL на кожен PHP/Python процес. 100 воркерів — 100 з'єднань. PostgreSQL деградує від 200+ активних з'єднань через overhead на управління.

PgBouncer у transaction pooling: 1000 воркерів → 20–50 реальних з'єднань. Це знижує latency на 40% та зменшує витрати на хостинг на 30% — при середній вартості хостингу $2,000/міс економить $600/міс. GIN-індекс для JSONB до 100 разів швидший за B-tree при пошуку.

Як Octane справляється з високим навантаженням?

Laravel Octane (RoadRunner або Swoole) прибирає overhead bootstrap на кожен HTTP-запит. Приріст: 3–8x на синтетичних бенчмарках, 2–4x на реальних додатках. Важливо: не зберігати стан у статичних змінних — застосовуємо це на проектах >1000 RPS.

Як PostgreSQL допомагає уникнути повільних запитів?

Використовуємо composite indexes для WHERE + ORDER BY, partial indexes для фільтрів з високою селективністю, GIN-індекси для JSONB та full-text search. to_tsvector + GIN замість LIKE '%query%' — запобігає seq scan навіть на мільйонах записів. Аналізуємо плани через EXPLAIN ANALYZE та pg_stat_statements.

Як обрати стек для вашого проекту?

Node.js виправданий для realtime: Laravel публікує події в Redis Pub/Sub, Node.js підписується та транслює клієнтам. Go — для goroutines (10k з'єднань на сервер — норма), але розробка повільніша, ніж Laravel.

Чому Redis критичний для продуктивності?

Redis виконує кілька ролей:

Redis Cluster для горизонтального масштабування, Sentinel для автоматичного failover. Замовте консультацію щодо оптимізації Redis для вашого проекту.

Що входить в роботу під ключ

• Архітектурне проектування (документація API, схема БД, діаграма сервісів)
• Реалізація за узгодженим ТЗ з code review
• Налаштування CI/CD (GitHub Actions, Docker), моніторингу (Sentry, Grafana), алертингу
• Навантажувальне тестування (k6, wrk) зі звітом
• Передача вихідних кодів, доступів, інструкція з деплою
• Навчання команди замовника (2–3 сесії)
• Гарантійна підтримка 1 місяць після здачі

Орієнтири по термінах

Вартість розраховується індивідуально після аналізу вимог до навантаження, інтеграцій та бізнес-логіки. Зв'яжіться з нами для безкоштовного аудиту вашого поточного backend — отримайте план оптимізації за 2 дні. Замовте консультацію та дізнайтеся, як знизити витрати на інфраструктуру на 30% без втрати продуктивності.