{"id":16897,"library":"sequelize-cli","title":"Sequelize CLI","description":"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.","status":"active","version":"6.6.5","language":"javascript","source_language":"en","source_url":"git://github.com/sequelize/cli","tags":["javascript","sequelize","cli","typescript"],"install":[{"cmd":"npm install sequelize-cli","lang":"bash","label":"npm"},{"cmd":"yarn add sequelize-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add sequelize-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Sequelize ORM is a peer dependency and required for all CLI operations.","package":"sequelize","optional":false}],"imports":[{"note":"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.","wrong":"require('sequelize-cli'); // Does not provide a clean programmatic API to run specific commands.\nimport { sequelize } from 'sequelize-cli'; // Not a direct JS export for CLI execution.","symbol":"sequelize","correct":"npx sequelize <command>"},{"note":"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.","wrong":"import { init } from 'sequelize-cli'; // The `init` command is a CLI command, not a JavaScript function export for direct import.","symbol":"init","correct":"npx sequelize init"},{"note":"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.","wrong":"const { migrate } = require('sequelize-cli').db; // There's no exposed programmatic API like this for running migrations.\nimport { runMigrations } from 'sequelize-cli'; // Not a direct JS export.","symbol":"db:migrate","correct":"npx sequelize db:migrate"}],"quickstart":{"code":"npm install --save-dev sequelize-cli sequelize mysql2\n\n# Initialize a new Sequelize project structure\nnpx sequelize init\n\n# Adjust config/config.js to your database settings. For example (using environment variables):\n# module.exports = {\n#   development: {\n#     username: process.env.DB_USER ?? 'root',\n#     password: process.env.DB_PASSWORD ?? '',\n#     database: process.env.DB_NAME ?? 'my_sequelize_db_dev',\n#     host: process.env.DB_HOST ?? '127.0.0.1',\n#     dialect: 'mysql'\n#   }\n# };\n\n# Create the database specified in your configuration\nnpx sequelize db:create\n\n# Generate a new model and its corresponding migration file\nnpx sequelize model:generate --name User --attributes firstName:string,lastName:string,email:string\n\n# Run pending migrations to apply schema changes to the database\nnpx sequelize db:migrate\n\n# Generate a seeder file for initial data population\nnpx sequelize seed:generate --name initial-users\n\n# Edit the generated seeder file (e.g., seeders/<timestamp>-initial-users.js) to insert data:\n# module.exports = {\n#   up: async (queryInterface, Sequelize) => {\n#     await queryInterface.bulkInsert('Users', [{\n#       firstName: 'Jane', lastName: 'Doe', email: 'jane.doe@example.com',\n#       createdAt: new Date(), updatedAt: new Date()\n#     }], {});\n#   },\n#   down: async (queryInterface, Sequelize) => {\n#     await queryInterface.bulkDelete('Users', null, {});\n#   }\n# };\n\n# Run all seeders to populate the database with initial data\nnpx sequelize db:seed:all","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Database connection strings containing special characters, particularly colons (`:`) in passwords, could cause parsing errors in older `sequelize-cli` versions, leading to connection failures.","severity":"gotcha","affected_versions":"<6.6.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install sequelize` or `yarn add sequelize` to add the `sequelize` package to your project.","cause":"The `sequelize` ORM package is not installed as a dependency in your project's `node_modules`.","error":"Error: Cannot find module 'sequelize'"},{"fix":"Execute `npx sequelize db:create` to create the database as defined in your configuration.","cause":"The database specified in your `config/config.js` for the current `NODE_ENV` has not been created on your database server.","error":"Database 'your_database_name' does not exist"},{"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.","cause":"The `sequelize-cli` could not find your database configuration file at the expected path and/or with the expected file extension.","error":"Unable to resolve 'config/config.json'. Did you mean 'config/config.js'?"},{"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.","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.","error":"No migrations were executed, this could be because they have already been executed, or they are not in the migrations folder."}],"ecosystem":"npm","meta_description":null}