Как выполнять raw SQL-запросы в Sequelize?

Sequelize — это ORM для Node.js, но иногда возможностей моделей и методов вроде findAll не хватает: нужны сложные JOIN, оконные функции, специфичные для СУБД конструкции или оптимизированные запросы. В таких случаях Sequelize позволяет выполнять сырой SQL через метод sequelize.query().

Базовый синтаксис

Метод принимает SQL-строку и объект опций. Без опций возвращается массив из двух элементов: результаты и метаданные (например, affectedRows).

const [results, metadata] = await sequelize.query(
  'SELECT * FROM users WHERE age > 18'
);
console.log(results); // массив строк

Указание типа запроса

Чтобы сразу получить массив строк без метаданных, используй QueryTypes:

const { QueryTypes } = require('sequelize');

const users = await sequelize.query(
  'SELECT * FROM users WHERE age > :age',
  {
    replacements: { age: 18 },
    type: QueryTypes.SELECT
  }
);

Защита от SQL-инъекций

Никогда не склеивай значения в строку вручную. Sequelize предлагает два механизма:

• replacements — подстановка значений с экранированием, работает и для массивов (IN-списки).
• bind — настоящие параметризованные запросы, значения передаются отдельно от SQL.

// replacements
await sequelize.query(
  'SELECT * FROM users WHERE id IN (:ids)',
  { replacements: { ids: [1, 2, 3] }, type: QueryTypes.SELECT }
);

// bind
await sequelize.query(
  'SELECT * FROM users WHERE id = $1',
  { bind: [1], type: QueryTypes.SELECT }
);

Другие типы запросов

QueryTypes.INSERT, UPDATE, DELETE возвращают метаданные с количеством затронутых строк. Для вызова хранимых процедур используй QueryTypes.RAW.

Итог: применяй sequelize.query, когда ORM-методы неэффективны или невозможны, но всегда используй replacements или bind для безопасности и явно указывай type для удобства.