Sequelize CLI

6.6.5 · active · verified Wed Apr 22

The Sequelize CLI is the official command-line interface for the Sequelize ORM, providing essential tools for managing Sequelize projects. It is currently stable at version 6.6.5, with minor releases and bug fixes occurring every few months, demonstrating active maintenance. The CLI facilitates common database operations such as creating and dropping databases, managing schema migrations (applying, reverting, checking status), generating and running seed files for initial data population, and scaffolding new models, migrations, and seeders. Its key differentiator is its tight integration with the Sequelize ORM, making it the de facto tool for many Sequelize workflows, especially for projects utilizing its migration system. It supports both CommonJS and ESM configuration files, and since v6.2.0, allows for TypeScript migration files, adapting to modern JavaScript ecosystems.

Common errors

```
Error: Cannot find module 'sequelize'
```
cause The `sequelize` ORM package is not installed as a dependency in your project's `node_modules`.

fix Run `npm install sequelize` or `yarn add sequelize` to add the `sequelize` package to your project.
```
Database 'your_database_name' does not exist
```
cause The database specified in your `config/config.js` for the current `NODE_ENV` has not been created on your database server.

fix Execute `npx sequelize db:create` to create the database as defined in your configuration.
```
Unable to resolve 'config/config.json'. Did you mean 'config/config.js'?
```
cause The `sequelize-cli` could not find your database configuration file at the expected path and/or with the expected file extension.

fix Ensure your configuration file is correctly named (e.g., `config/config.js` for CommonJS, `config/config.mjs` for ESM, or `config/config.ts` for TypeScript) and located in the `config` directory relative to your project root. Verify your `package.json` `type` field if using ESM.
```
No migrations were executed, this could be because they have already been executed, or they are not in the migrations folder.
```
cause There are no new migration files to apply, or the specified migration files are not found in the `migrations` directory, or `NODE_ENV` is incorrectly set, causing the CLI to look at the wrong database/migration history.

fix Check the `migrations` directory for new migration files. Verify their names follow the `YYYYMMDDHHMMSS-migration-name.js` format. Ensure `NODE_ENV` is set correctly to target the desired environment, and use `npx sequelize db:migrate:status` to see the current migration status.

Warnings

breaking Major versions (e.g., v4 to v5, v5 to v6) have introduced significant changes, particularly in configuration file handling, command-line argument parsing, and default paths. Upgrading across major versions may require manual adjustments to your project's `config` files and `package.json` scripts.
Fix: Review the official migration guides for each major version upgrade. Ensure your `config/config.js` (or `.json`/`.ts`) and `models/index.js` files are aligned with the new conventions. Consider initializing a new project with the target CLI version to see the expected structure.
gotcha Global installation of `sequelize-cli` (`npm install -g sequelize-cli`) can lead to version conflicts and unexpected behavior, as it might not match the version of `sequelize` or `sequelize-cli` installed locally in your project.
Fix: Always prefer running `sequelize-cli` commands using `npx sequelize <command>`. This ensures that the version of `sequelize-cli` installed in your local `node_modules` is used, maintaining consistency within your project.
gotcha The `sequelize-cli` is tightly coupled with the `sequelize` ORM. If the `sequelize` package is not installed as a dependency in your project, or if there's a significant version mismatch, CLI commands will likely fail with 'module not found' errors or other unexpected issues.
Fix: Ensure that `sequelize` is installed as a project dependency (`npm install sequelize`) and that its version is compatible with your `sequelize-cli` version. Consult the `sequelize-cli` GitHub repository for recommended `sequelize` ORM version compatibility.
gotcha Database connection strings containing special characters, particularly colons (`:`) in passwords, could cause parsing errors in older `sequelize-cli` versions, leading to connection failures.
Fix: Upgrade `sequelize-cli` to version 6.6.2 or newer, which includes a fix for parsing passwords with colons. Alternatively, ensure special characters in passwords are correctly URI-encoded if not upgrading immediately.
gotcha The CLI uses the `NODE_ENV` environment variable to determine which environment configuration (e.g., `development`, `test`, `production`) to use from your `config/config.js`. Failing to set `NODE_ENV` or setting it incorrectly can lead to commands running against the wrong database.
Fix: Always explicitly set `NODE_ENV` when running `sequelize-cli` commands, e.g., `NODE_ENV=production npx sequelize db:migrate`. You can also define a default environment in your `config/config.js` or ensure your CI/CD pipeline correctly sets this variable.

Install

npm install sequelize-cli npm
yarn add sequelize-cli yarn
pnpm add sequelize-cli pnpm

Imports

sequelize
wrong:
```
require('sequelize-cli'); // Does not provide a clean programmatic API to run specific commands.
import { sequelize } from 'sequelize-cli'; // Not a direct JS export for CLI execution.
```
correct:
```
npx sequelize <command>
```
The primary and recommended way to interact with sequelize-cli is through the `npx` command runner, executing CLI commands directly. Direct JavaScript imports for command execution are not idiomatic for typical use cases.
init
wrong:
```
import { init } from 'sequelize-cli'; // The `init` command is a CLI command, not a JavaScript function export for direct import.
```
correct:
```
npx sequelize init
```
This command initializes the basic project structure for Sequelize, including a configuration file, migrations, models, and seeders directories. It is run via the command line.
db:migrate
wrong:
```
const { migrate } = require('sequelize-cli').db; // There's no exposed programmatic API like this for running migrations.
import { runMigrations } from 'sequelize-cli'; // Not a direct JS export.
```
correct:
```
npx sequelize db:migrate
```
Runs all pending migrations defined in the migrations directory. Ensure your database configuration for the current `NODE_ENV` is correctly specified in your `config/config.js` or `config/config.ts` file.

Quickstart

This quickstart demonstrates how to set up a new Sequelize project using sequelize-cli, including initialization, database creation, model and migration generation, running migrations, and seeding initial data.

npm install --save-dev sequelize-cli sequelize mysql2

# Initialize a new Sequelize project structure
npx sequelize init

# Adjust config/config.js to your database settings. For example (using environment variables):
# module.exports = {
#   development: {
#     username: process.env.DB_USER ?? 'root',
#     password: process.env.DB_PASSWORD ?? '',
#     database: process.env.DB_NAME ?? 'my_sequelize_db_dev',
#     host: process.env.DB_HOST ?? '127.0.0.1',
#     dialect: 'mysql'
#   }
# };

# Create the database specified in your configuration
npx sequelize db:create

# Generate a new model and its corresponding migration file
npx sequelize model:generate --name User --attributes firstName:string,lastName:string,email:string

# Run pending migrations to apply schema changes to the database
npx sequelize db:migrate

# Generate a seeder file for initial data population
npx sequelize seed:generate --name initial-users

# Edit the generated seeder file (e.g., seeders/<timestamp>-initial-users.js) to insert data:
# module.exports = {
#   up: async (queryInterface, Sequelize) => {
#     await queryInterface.bulkInsert('Users', [{
#       firstName: 'Jane', lastName: 'Doe', email: 'jane.doe@example.com',
#       createdAt: new Date(), updatedAt: new Date()
#     }], {});
#   },
#   down: async (queryInterface, Sequelize) => {
#     await queryInterface.bulkDelete('Users', null, {});
#   }
# };

# Run all seeders to populate the database with initial data
npx sequelize db:seed:all

view raw JSON →