Настройка ORM Sequelize для веб-приложения

Настройка ORM Sequelize для веб-приложения

Sequelize — зрелый ORM для Node.js, поддерживающий PostgreSQL, MySQL, MariaDB, SQLite и MSSQL. Устанавливаем версию 6.x: она принесла полный переход на промисы и улучшенные typescript-типы по сравнению с пятой веткой.

npm install sequelize pg pg-hstore
# или для MySQL
npm install sequelize mysql2

Инициализация подключения

Подключение лучше оформить как синглтон, который разделяется между модулями приложения. Создаём src/db/sequelize.ts:

import { Sequelize } from 'sequelize';

const sequelize = new Sequelize(process.env.DATABASE_URL!, {
  dialect: 'postgres',
  dialectOptions: {
    ssl: process.env.NODE_ENV === 'production'
      ? { require: true, rejectUnauthorized: false }
      : false,
  },
  pool: {
    max: 10,
    min: 2,
    acquire: 30000,
    idle: 10000,
  },
  logging: process.env.NODE_ENV !== 'production' ? console.log : false,
  define: {
    underscored: true,
    timestamps: true,
  },
});

export default sequelize;

Параметр underscored: true автоматически преобразует camelCase имена полей в snake_case колонки. Это важно: без него Sequelize создаст createdAt, а не created_at.

Определение моделей

Sequelize 6 поддерживает два стиля объявления моделей — class-based и объектный. Class-based предпочтителен для TypeScript:

import {
  Model, DataTypes, InferAttributes,
  InferCreationAttributes, CreationOptional,
} from 'sequelize';
import sequelize from '../db/sequelize';

class User extends Model<
  InferAttributes<User>,
  InferCreationAttributes<User>
> {
  declare id: CreationOptional<number>;
  declare email: string;
  declare passwordHash: string;
  declare role: 'admin' | 'editor' | 'viewer';
  declare createdAt: CreationOptional<Date>;
  declare updatedAt: CreationOptional<Date>;
}

User.init({
  id: {
    type: DataTypes.INTEGER,
    primaryKey: true,
    autoIncrement: true,
  },
  email: {
    type: DataTypes.STRING(320),
    allowNull: false,
    unique: true,
    validate: { isEmail: true },
  },
  passwordHash: {
    type: DataTypes.STRING(255),
    allowNull: false,
  },
  role: {
    type: DataTypes.ENUM('admin', 'editor', 'viewer'),
    defaultValue: 'viewer',
  },
}, {
  sequelize,
  tableName: 'users',
  modelName: 'User',
});

export default User;

Ассоциации

Объявляем связи после определения всех моделей, в отдельном файле src/db/associations.ts:

import User from '../models/User';
import Post from '../models/Post';
import Comment from '../models/Comment';
import Tag from '../models/Tag';

User.hasMany(Post, { foreignKey: 'authorId', as: 'posts' });
Post.belongsTo(User, { foreignKey: 'authorId', as: 'author' });

Post.hasMany(Comment, { foreignKey: 'postId', as: 'comments' });
Comment.belongsTo(Post, { foreignKey: 'postId', as: 'post' });

Post.belongsToMany(Tag, {
  through: 'post_tags',
  foreignKey: 'postId',
  otherKey: 'tagId',
  as: 'tags',
});
Tag.belongsToMany(Post, {
  through: 'post_tags',
  foreignKey: 'tagId',
  otherKey: 'postId',
  as: 'posts',
});

Функцию из этого файла вызываем один раз при старте приложения, до любых запросов к БД.

Запросы с eager loading

Распространённая ошибка — загрузка связанных данных N+1 запросами. В Sequelize используем include:

const posts = await Post.findAll({
  where: { status: 'published' },
  include: [
    {
      model: User,
      as: 'author',
      attributes: ['id', 'email'],
    },
    {
      model: Tag,
      as: 'tags',
      through: { attributes: [] }, // скрываем поля промежуточной таблицы
    },
  ],
  order: [['createdAt', 'DESC']],
  limit: 20,
  offset: 0,
});

Транзакции

Для операций, затрагивающих несколько таблиц, обязательно используем транзакции:

import sequelize from '../db/sequelize';

async function createPostWithTags(
  data: { title: string; body: string; tagIds: number[] },
  authorId: number,
) {
  return sequelize.transaction(async (t) => {
    const post = await Post.create(
      { title: data.title, body: data.body, authorId, status: 'draft' },
      { transaction: t },
    );

    if (data.tagIds.length > 0) {
      await post.setTags(data.tagIds, { transaction: t });
    }

    return post;
  });
}

При исключении внутри коллбека транзакция откатывается автоматически.

Миграции через sequelize-cli

Для управления схемой БД в CI/CD используем sequelize-cli:

npm install --save-dev sequelize-cli
npx sequelize-cli init

Создаём конфиг .sequelizerc:

const path = require('path');
module.exports = {
  config: path.resolve('src/db', 'config.json'),
  'models-path': path.resolve('src', 'models'),
  'seeders-path': path.resolve('src/db', 'seeders'),
  'migrations-path': path.resolve('src/db', 'migrations'),
};

Создаём миграцию:

npx sequelize-cli migration:generate --name create-users

// src/db/migrations/20240315120000-create-users.js
'use strict';

module.exports = {
  up: async (queryInterface, Sequelize) => {
    await queryInterface.createTable('users', {
      id: {
        type: Sequelize.INTEGER,
        primaryKey: true,
        autoIncrement: true,
      },
      email: {
        type: Sequelize.STRING(320),
        allowNull: false,
        unique: true,
      },
      password_hash: {
        type: Sequelize.STRING(255),
        allowNull: false,
      },
      role: {
        type: Sequelize.ENUM('admin', 'editor', 'viewer'),
        defaultValue: 'viewer',
      },
      created_at: { type: Sequelize.DATE, allowNull: false },
      updated_at: { type: Sequelize.DATE, allowNull: false },
    });

    await queryInterface.addIndex('users', ['email']);
  },

  down: async (queryInterface) => {
    await queryInterface.dropTable('users');
  },
};

Хуки и валидация

Sequelize поддерживает хуки жизненного цикла. Например, хеширование пароля перед сохранением:

import bcrypt from 'bcrypt';

User.addHook('beforeCreate', async (user: User) => {
  if (user.passwordHash) {
    user.passwordHash = await bcrypt.hash(user.passwordHash, 12);
  }
});

User.addHook('beforeUpdate', async (user: User) => {
  if (user.changed('passwordHash')) {
    user.passwordHash = await bcrypt.hash(user.passwordHash, 12);
  }
});

Сроки и объём работ

Настройка Sequelize для нового проекта с нуля: 1–2 дня. Включает подключение к БД, базовый набор моделей, ассоциации, миграции, seed-данные и тесты подключения. Если в проекте уже есть база и нужно обратное проектирование (генерация моделей из существующей схемы) — добавьте ещё 1 день на sequelize-auto и ручную доводку типов.