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

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

Почему стандартная настройка TypeORM часто приводит к проблемам?

N+1 запрос — классическая проблема при работе с 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 рублей и зависит от сложности проекта. Свяжитесь с нами для оценки — это бесплатно и займёт не более часа.

Услуги бэкенд-разработки: Laravel, Node.js, Go, Django, PostgreSQL

На production-сервере в 3:14 ночи очередь Laravel Jobs перестала обрабатываться. 40 000 необработанных задач в Redis. Причина: worker упал из-за memory leak в одном из Jobs (утечка через статическую переменную в Eloquent observer), supervisor не перезапустил его из-за misconfigured stopwaitsecs. Это не гипотетический сценарий — это вторник. Мы разбирали такой инцидент на проекте с нагрузкой 500 RPS: диагностика заняла 4 часа, фикс — 20 минут. Чтобы вы не теряли деньги на простоях, предлагаем услуги бэкенд-разработки с акцентом на production-grade надёжность. Оценим ваш проект за 2 дня.

Backend — это то, что работает когда никто не смотрит. Или не работает. Гарантируем, что у вас будет первый вариант.

Что мы делаем с первого дня правильно

Service Layer поверх Fat Controllers. Controller получает HTTP-запрос, валидирует его через Form Request, передаёт данные в Service, возвращает ответ. Бизнес-логика в Service, не в Controller. Это звучит банально, но большинство legacy-проектов — это контроллеры по 500 строк с SQL-запросами внутри.

Repository Pattern используем осторожно. Если вы просто оборачиваете Model::where(...) в метод репозитория — это бойлерплейт без пользы. Repository оправдан когда: нужно абстрагироваться от источника данных (БД + кеш + внешний API) или когда логика запросов достаточно сложна для изоляции.

Jobs, Events, Listeners. Всё, что можно сделать асинхронно — делаем асинхронно. Отправка email, генерация PDF, синхронизация с внешним API, пересчёт агрегатов — в Queue. Laravel Horizon для мониторинга очередей в Redis: видно throughput, failed jobs, время обработки по очередям.

Как Octane справляется с высокой нагрузкой

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

Что делать с N+1 запросами

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

Laravel Debugbar в dev-окружении показывает количество запросов на страницу. Более 20 запросов на одну страницу — сигнал для audit.

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

Telescope для профилирования в staging: логирует все запросы, jobs, mail, notifications с детализацией по времени. Цифры: после внедрения eager loading время загрузки страницы падает с 8 с до 0.3 с — в 27 раз.

PostgreSQL: индексы, которые реально нужны

PostgreSQL 14+ — основная БД на всех проектах. Используем связку PgBouncer + PostgreSQL. Опыт 10+ лет, более 50 backend-проектов, 5 лет на рынке.

Как PostgreSQL помогает избежать медленных запросов

Composite indexes для частых WHERE + ORDER BY. Если у вас WHERE user_id = ? AND status = ? ORDER BY created_at DESC — нужен (user_id, status, created_at DESC). Индекс по (user_id) отдельно плохо помогает с сортировкой.

Partial indexes. Если 95% запросов идут по WHERE status = 'active':

CREATE INDEX idx_orders_active ON orders (created_at DESC)
WHERE status = 'active';

Индекс маленький, быстрый, покрывает основную нагрузку.

GIN-индексы для JSONB и массивов. @> оператор без GIN-индекса — seq scan. С индексом — быстро даже на миллионах записей.

GIN для full-text search. to_tsvector + GIN вместо LIKE '%query%'. LIKE без индекса — всегда seq scan. С pg_trgm extension и gin_trgm_ops — поддержка LIKE с индексом, полезно для CRM-поиска по частичному совпадению.

Connection pooling: почему важнее чем кажется

Rails, Laravel, Django открывают новое соединение с PostgreSQL на каждый PHP/Python процесс. На 100 воркерах — 100 соединений. PostgreSQL начинает деградировать от 200–300 активных соединений — overhead на управление соединениями становится значительным.

PgBouncer — connection pooler перед PostgreSQL. Режим transaction pooling: соединение с PostgreSQL занято только на время транзакции, между запросами возвращается в пул. 1000 приложений-воркеров → 20–50 реальных соединений к PostgreSQL. Это снижает latency на 40% и уменьшает затраты на хостинг на 30%.

Node.js с Fastify: когда это лучше Laravel

Node.js оправдан для:

• Realtime: WebSocket-серверы, Server-Sent Events, чат, live-обновления
• Streaming: большие файлы, видео, данные потоком
• High I/O concurrency: много параллельных запросов к внешним API без тяжёлой бизнес-логики
• Serverless: Lambda/Cloud Functions — Node.js стартует быстрее PHP

Fastify вместо Express: в 2–3 раза быстрее на benchmarks, встроенная JSON Schema валидация, лучшая TypeScript поддержка, plugin-архитектура.

Типичная архитектура realtime: Laravel — основная бизнес-логика и REST API. Node.js + Socket.io или ws — WebSocket сервер. Laravel публикует события в Redis Pub/Sub, Node.js подписывается и транслирует клиентам. Это разделение позволяет масштабировать WebSocket-сервер независимо от основного приложения.

Go: микросервисы и высокая нагрузка

Go используем для:

• Высоконагруженных микросервисов (> 10 000 RPS)
• Фоновых воркеров с жёсткими требованиями к latency
• Инструментов DevOps и CLI
• gRPC-сервисов в микросервисной архитектуре

Goroutines — дешевле OS-потоков в тысячи раз. 10 000 конкурентных соединений на Go — норма на одном сервере.

Но Go — не волшебная таблетка. Разработка медленнее чем на Laravel: больше бойлерплейта, нет ORM уровня Eloquent, обработка ошибок через if err != nil везде. Оправдан только когда производительность — реальное требование, не предположение.

Django и Python backend

Django с DRF (Django REST Framework) — для задач где нужен Python: ML-пайплайны, обработка данных, интеграции с AI-инструментами.

Celery для фоновых задач — аналог Laravel Queue, но сложнее в конфигурации. Celery Beat для cron-задач.

Django ORM vs raw SQL: ORM удобен для CRUD. Для аналитических запросов с несколькими JOIN, оконными функциями и CTE — connection.execute() с raw SQL читаемее и предсказуемее.

Redis: не только кеш

Redis в наших проектах выполняет несколько ролей:

Redis Cluster для горизонтального масштабирования. Sentinel для автоматического failover на standalone установках.

Деплой и инфраструктура

Docker + docker-compose — стандарт для локальной разработки и production. Каждый сервис в контейнере: PHP-FPM/Octane, Nginx, PostgreSQL, Redis, Queue Worker, Scheduler.

CI/CD через GitHub Actions:

1. Прогон тестов (PHPUnit / Pest, Vitest, Playwright)
2. Сборка Docker-образа
3. Push в Container Registry
4. Deploy: docker pull → docker-compose up -d на сервере, или Kubernetes rolling update

Zero-downtime deploy для Laravel: php artisan down --secret=TOKEN не нужен при правильной настройке. Стратегия: новый контейнер стартует рядом со старым, Nginx переключает трафик после health check, старый контейнер останавливается.

Мониторинг: Sentry для exception tracking с alerting в Slack/Telegram. Grafana + Prometheus (или Grafana Cloud) для метрик: CPU, memory, request rate, queue depth, database connection count. Алерт на: error rate > 1%, p99 latency > 2s, queue depth > 1000 jobs.

Что входит в работу под ключ

• Архитектурное проектирование (документация API, схема БД, диаграмма сервисов)
• Реализация по согласованному ТЗ с code review
• Настройка CI/CD, мониторинга, алертинга
• Нагрузочное тестирование (k6, wrk) с отчётом
• Передача исходников, доступов, инструкция по деплою
• Обучение команды заказчика (2-3 сессии)
• Гарантийная поддержка 1 месяц после сдачи

Ориентиры по срокам

Стоимость рассчитывается индивидуально после анализа требований к нагрузке, интеграциям и бизнес-логике. Типичный бюджет backend-проекта — от 500 000 до 2 000 000 рублей в зависимости от сложности. Свяжитесь с нами для бесплатного аудита вашего текущего backend — получите план оптимизации за 2 дня. Закажите консультацию.