Sequelize ORM

Common errors

• SequelizeConnectionError: connect ECONNREFUSED 127.0.0.1:5432

  cause The database server is not running, is inaccessible, or connection details are incorrect.
  fix Ensure your database server is running and accessible. Verify host, port, username, and password in your Sequelize configuration. Check firewall rules if applicable.

• Error: Please install 'pg' module manually

  cause The database dialect driver required by Sequelize (e.g., 'pg', 'mysql2') has not been installed.
  fix Install the correct driver for your database: `npm install pg` (PostgreSQL), `npm install mysql2` (MySQL/MariaDB), `npm install sqlite3` (SQLite).

• SequelizeUniqueConstraintError: Validation error

  cause An attempt was made to insert or update a record with a value that violates a unique constraint on a database field.
  fix Implement checks (e.g., using `Model.findOrCreate`) before creating records, or catch the `SequelizeUniqueConstraintError` and handle the duplicate entry gracefully.

• SequelizeDatabaseError: ER_BAD_FIELD_ERROR: Unknown column '...' in 'field list'

  cause The database schema does not match the Sequelize model definition, often due to missing or outdated migrations.
  fix Run database migrations to ensure your schema is up-to-date with your Sequelize models. Double-check column names and aliases in your queries.

Warnings

• breaking Upgrading from Sequelize v5 to v6 introduces several breaking changes that require code modifications.
  Fix: Refer to the official upgrade guide for detailed instructions: https://sequelize.org/docs/v6/other-topics/upgrade-to-v6
• breaking A security vulnerability (CVE-2026-30951) allowed validation bypass in JSON where clauses, potentially leading to SQL injection.
  Fix: Upgrade to Sequelize v6.37.8 or higher immediately to apply the security fix.
• gotcha Sequelize requires a separate database dialect driver package to be installed manually (e.g., 'pg' for PostgreSQL, 'mysql2' for MySQL, 'sqlite3' for SQLite).
  Fix: Install the appropriate driver for your database, e.g., `npm install pg` for PostgreSQL.
• gotcha The Sequelize project is actively seeking new maintainers, which might impact the pace of feature development or critical bug fixes for future major versions if not enough contributors join.
  Fix: Consider engaging with the community or contributing if specific features or urgent fixes are critical for your project. Join their Slack at sequelize.org/slack.

Install

• npm install sequelize npm
• yarn add sequelize yarn
• pnpm add sequelize pnpm

Imports

• Sequelize
  wrong:

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

  correct:

  import { Sequelize } from 'sequelize';

• DataTypes
  wrong:

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

  correct:

  import { DataTypes } from 'sequelize';

• Model
  wrong:

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

  correct:

  import { Model } from 'sequelize';

Quickstart

This quickstart demonstrates how to connect to an SQLite database, define a User model, synchronize the schema, create a new user, and fetch all users. It uses `sequelize.sync({ force: true })` for simplicity, which will drop and re-create tables on each run.

import { Sequelize, DataTypes, Model } from 'sequelize';

const sequelize = new Sequelize({
  dialect: 'sqlite',
  storage: 'database.sqlite',
  logging: false // Disable logging for cleaner output
});

class User extends Model {}

User.init({
  id: {
    type: DataTypes.INTEGER,
    autoIncrement: true,
    primaryKey: true
  },
  username: {
    type: DataTypes.STRING,
    allowNull: false,
    unique: true
  },
  email: {
    type: DataTypes.STRING,
    allowNull: false,
    unique: true
  }
}, {
  sequelize,
  modelName: 'User'
});

async function run() {
  try {
    await sequelize.authenticate();
    console.log('Connection has been established successfully.');

    await sequelize.sync({ force: true }); // This will drop existing tables
    console.log('All models were synchronized successfully.');

    const jane = await User.create({ username: 'JaneDoe', email: 'jane.doe@example.com' });
    console.log(`Created user: ${jane.username}`);

    const users = await User.findAll();
    console.log('All users:', users.map(u => u.toJSON()));

  } catch (error) {
    console.error('Unable to connect to the database:', error);
  } finally {
    await sequelize.close();
  }
}

run();