Начало работы

В этом руководстве вы узнаете, как настроить Sequelize для освоения основ.

Установка

Sequelize доступен через npm (или yarn).

npm install --save sequelize

Вам также потребуется вручную установить драйвер для выбранной базы данных:

# One of the following:
$ npm install --save pg pg-hstore # Postgres
$ npm install --save mysql2
$ npm install --save mariadb
$ npm install --save sqlite3
$ npm install --save tedious # Microsoft SQL Server

Настройка подключения

Для подключения к базе данных необходимо создать экземпляр Sequelize. Это можно сделать, передав параметры подключения отдельно в конструктор Sequelize или передав единственный URI подключения:

const Sequelize = require('sequelize');

// Option 1: Passing parameters separately
const sequelize = new Sequelize('database', 'username', 'password', {
  host: 'localhost',
  dialect: /* one of 'mysql' | 'mariadb' | 'postgres' | 'mssql' */
});

// Option 2: Passing a connection URI
const sequelize = new Sequelize('postgres://user:pass@example.com:5432/dbname');

Конструктор Sequelize принимает множество опций, которые документированы в справочнике по API конструктора Sequelize.

Примечание: настройка SQLite

Если вы используете SQLite, используйте следующее вместо этого:

const sequelize = new Sequelize({
  dialect: 'sqlite',
  storage: 'path/to/database.sqlite'
});

Примечание: пул подключений (производство)

Если вы подключаетесь к базе данных из одного процесса, вы должны создать только один экземпляр Sequelize. Sequelize настроит пул подключений при инициализации. Этот пул подключений можно настроить с помощью параметра конструктора options (используя options.pool), как показано в следующем примере:

const sequelize = new Sequelize(/* ... */, {
  // ...
  pool: {
    max: 5,
    min: 0,
    acquire: 30000,
    idle: 10000
  }
});

Подробнее см. в справочнике по API конструктора Sequelize. Если вы подключаетесь к базе данных из нескольких процессов, вам нужно создать по одному экземпляру на каждый процесс, но каждый экземпляр должен иметь максимальный размер пула подключений таким образом, чтобы общий максимальный размер соблюдался. Например, если вы хотите максимальный размер пула подключений 90, а у вас три процесса, экземпляр Sequelize каждого процесса должен иметь максимальный размер пула подключений 30.

Проверка подключения

Вы можете использовать функцию .authenticate() для проверки работоспособности подключения:

sequelize
  .authenticate()
  .then(() => {
    console.log('Connection has been established successfully.');
  })
  .catch(err => {
    console.error('Unable to connect to the database:', err);
  });

Закрытие подключения

Sequelize по умолчанию поддерживает открытое подключение и использует одно подключение для всех запросов. Если вам нужно закрыть подключение, вызовите sequelize.close() (это асинхронная функция, которая возвращает Promise).

Моделирование таблицы

Модель — это класс, который расширяет Sequelize.Model. Модели можно определить двумя эквивалентными способами. Первый — с помощью Sequelize.Model.init(attributes, options);

const Model = Sequelize.Model;
class User extends Model {}
User.init({
  // attributes
  firstName: {
    type: Sequelize.STRING,
    allowNull: false
  },
  lastName: {
    type: Sequelize.STRING
    // allowNull defaults to true
  }
}, {
  sequelize,
  modelName: 'user'
  // options
});

В качестве альтернативы, используя sequelize.define;

const User = sequelize.define('user', {
  // attributes
  firstName: {
    type: Sequelize.STRING,
    allowNull: false
  },
  lastName: {
    type: Sequelize.STRING
    // allowNull defaults to true
  }
}, {
  // options
});

Внутренне, sequelize.define вызывает Model.init.

Вышеприведенный код сообщает Sequelize ожидать таблицу с именем users в базе данных с полями firstName и lastName. Имя таблицы по умолчанию автоматически множественное (внутри используется библиотека inflection для этого). Это поведение можно отключить для конкретной модели, используя опцию freezeTableName: true, или для всех моделей, используя опцию define из конструктора Sequelize.

Sequelize также по умолчанию определяет поля id (первичный ключ), createdAt и updatedAt для каждой модели. Это поведение также можно изменить (см. справку по API, чтобы узнать больше об имеющихся опциях).

Изменение параметров модели по умолчанию

Конструктор Sequelize принимает параметр define, который изменит значения параметров по умолчанию для всех определённых моделей.

const sequelize = new Sequelize(connectionURI, {
  define: {
    // The `timestamps` field specify whether or not the `createdAt` and `updatedAt` fields will be created.
    // This was true by default, but now is false by default
    timestamps: false
  }
});

// Here `timestamps` will be false, so the `createdAt` and `updatedAt` fields will not be created.
class Foo extends Model {}
Foo.init({ /* ... */ }, { sequelize });

// Here `timestamps` is directly set to true, so the `createdAt` and `updatedAt` fields will be created.
class Bar extends Model {}
Bar.init({ /* ... */ }, { sequelize, timestamps: true });

Дополнительную информацию о создании моделей можно найти в справочнике по API Model.init или в справочнике по API sequelize.define.

Синхронизация модели с базой данных

Если вы хотите, чтобы Sequelize автоматически создал таблицу (или модифицировал её по необходимости) в соответствии с определением модели, вы можете использовать метод sync, как показано ниже:

// Note: using `force: true` will drop the table if it already exists
User.sync({ force: true }).then(() => {
  // Now the `users` table in the database corresponds to the model definition
  return User.create({
    firstName: 'John',
    lastName: 'Hancock'
  });
});

Синхронизация всех моделей одновременно

Вместо вызова sync() для каждой модели, вы можете вызвать sequelize.sync(), которое автоматически синхронизирует все модели.

Примечание для производства

В производственной среде рекомендуется использовать миграции вместо вызова sync() в коде. Дополнительную информацию см. в руководстве по миграциям.

Запросы

Ниже показаны несколько простых запросов:

// Find all users
User.findAll().then(users => {
  console.log("All users:", JSON.stringify(users, null, 4));
});

// Create a new user
User.create({ firstName: "Jane", lastName: "Doe" }).then(jane => {
  console.log("Jane's auto-generated ID:", jane.id);
});

// Delete everyone named "Jane"
User.destroy({
  where: {
    firstName: "Jane"
  }
}).then(() => {
  console.log("Done");
});

// Change everyone without a last name to "Doe"
User.update({ lastName: "Doe" }, {
  where: {
    lastName: null
  }
}).then(() => {
  console.log("Done");
});

Sequelize предоставляет множество опций для запросов. Вы узнаете больше об этом в следующих руководствах. Также возможно выполнить запросы на основе SQL, если это действительно необходимо.

Promises и async/await

Как показано выше, Sequelize активно использует вызовы .then. Это означает, что, если ваша версия Node поддерживает это, вы можете использовать синтаксис ES2017 async/await для всех асинхронных вызовов, выполненных с помощью Sequelize.

Кроме того, все обещания Sequelize фактически являются обещаниями Bluebird, поэтому вы также можете использовать богатый API Bluebird (например, используя finally, tap, tapCatch, map, mapSeries, и т. д.). Вы можете получить доступ к конструктору Bluebird, используемому внутри Sequelize, с помощью Sequelize.Promise, если хотите установить любые специфические для Bluebird опции.