Skip to main content
Version: v7 - alpha

Getting Started

In this tutorial you will learn to make a simple setup of Sequelize.

Installing​

Sequelize is available via npm (or yarn).

info

The following commands will install Sequelize v7. If you're looking for Sequelize v6 (published as sequelize instead of @sequelize/core), visit the v6 documentation

# This will install Sequelize 7, the latest alpha release of Sequelize
npm i @sequelize/core@alpha

# You also need to install the driver for your database
npm i pg # PostgreSQL
npm i mysql2 # MySQL
npm i mariadb # MariaDB
npm i sqlite3 # SQLite
npm i tedious # Microsoft SQL Server
npm i ibm_db # DB2
npm i odbc # IBM i

Connecting to a database​

To connect to the database, you must create a Sequelize instance. This can be done by either passing the connection parameters separately to the Sequelize constructor or by passing a single connection URI:

import { Sequelize } from '@sequelize/core';

// Option 1: Passing a connection URI
const sequelize = new Sequelize('sqlite::memory:') // Example for sqlite
const sequelize = new Sequelize('postgres://user:pass@example.com:5432/dbname') // Example for postgres

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

// Option 3: Passing parameters separately (other dialects)
const sequelize = new Sequelize('database', 'username', 'password', {
  host: 'localhost',
  // one of our supported dialects:
  // 'mysql', 'mariadb', 'postgres', 'mssql', 'sqlite', 'snowflake', 'db2' or 'ibmi'
  dialect: 'postgres'
});

The Sequelize constructor accepts a lot of options. They are documented in the API Reference.

Testing the connection​

You can use the .authenticate() function to test if the connection is OK. Note that this is completely optional, but recommended as Sequelize fetches your Database version on the first connection. That version is then used to determine which SQL features are available.

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

Closing the connection​

Sequelize uses a connection pool to manage connections to the database. This means some connection can remain open even after you're done with them. If you wish to gracefully shut down your application, you can use sequelize.close() to close all active connections.

caution

Once sequelize.close() has been called, it's impossible to open a new connection. You will need to create a new Sequelize instance to access your database again.

Terminology convention​

Observe that, in the examples above, Sequelize refers to the library itself while the lowercase sequelize refers to an instance of Sequelize. This is the recommended convention, and it will be followed throughout the documentation.

TypeScript​

Sequelize provides built-in TypeScript support.

Head to the Version Policy page to know which versions of TypeScript are supported, and make sure that the @types/node package corresponding to your Node.js version is installed in your project.

CommonJS or ESM?​

Our documentation makes heavy use of ECMAScript Modules (ESM), but CommonJS is fully supported by Sequelize. To use Sequelize in a CommonJS project, simply use require instead of import:

// how you would import Sequelize in ESM
import { Sequelize, Op, Model, DataTypes } from '@sequelize/core';

// how you would import Sequelize in CommonJS
const { Sequelize, Op, Model, DataTypes } = require('@sequelize/core');

Most of the methods provided by Sequelize are asynchronous and therefore return Promises. we highly recommend using ECMAScript Modules, as they give you access to Top-Level Await, which we use extensively in our examples. Head to Node.js' documentation to learn how to use them in Node.js.

Logging​

By default, Sequelize will log to console every SQL query it performs. The options.logging option can be used to customize this behavior, by defining the function that gets executed every time Sequelize would log something. The default value is console.log and when using that only the first log parameter of log function call is displayed. For example, for query logging the first parameter is the raw query and the second (hidden by default) is the Sequelize object.

Common useful values for options.logging:

const sequelize = new Sequelize('sqlite::memory:', {
  // Choose one of the logging options
  logging: console.log,                  // Default, displays the first parameter of the log function call
  logging: (...msg) => console.log(msg), // Displays all log function call parameters
  logging: false,                        // Disables logging
  logging: msg => logger.debug(msg),     // Use custom logger (e.g. Winston or Bunyan), displays the first parameter
  logging: logger.debug.bind(logger)     // Alternative way to use custom logger, displays all messages
});

Next Step​

Now that you have a Sequelize instance, the next step to get started is to define your first models.