Налаштування 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 та ручну доводку типів.