View on GitHub


Test Coverage
_Please note!_ The github issue tracker should only be used for feature requests and bugs with a clear description of the issue and the expected behaviour (see below). All questions belong on [Slack](, [StackOverflow]( or [Google groups](!forum/sequelize).

# Issues
Issues are always very welcome - after all, they are a big part of making sequelize better. However, there are a couple of things you can do to make the lives of the developers _much, much_ easier:

### Tell us:

* What you are doing?
  * Post a _minimal_ code sample that reproduces the issue, including models and associations
  * What do you expect to happen?
  * What is actually happening?
* Which dialect you are using (postgres, mysql etc)?
* Which sequelize version you are using?

When you post code, please use [Github flavored markdown](, in order to get proper syntax highlighting!

If you can even provide a pull request with a failing unit test, we will love you long time! Plus your issue will likely be fixed much faster.

# Pull requests
We're glad to get pull request if any functionality is missing or something is buggy. However, there are a couple of things you can do to make life easier for the maintainers:

* Explain the issue that your PR is solving - or link to an existing issue
* Make sure that all existing tests pass
* Make sure you followed [coding guidelines](
* Add some tests for your new functionality or a test exhibiting the bug you are solving. Ideally all new tests should not pass _without_ your changes.
  - Use [async/await]( in all new tests. Specifically this means:
    - don't use `EventEmitter`, `QueryChainer` or the `success`, `done` and `error` events
    - don't use a done callback in your test, just return the promise chain.
  - Small bugfixes and direct backports to the 4.x branch are accepted without tests.
* If you are adding to / changing the public API, remember to add API docs, in the form of [JSDoc style]( comments. See [section 4a](#4a-check-the-documentation) for the specifics.

Interested? Coolio! Here is how to get started:

### 1. Prepare your environment
Here comes a little surprise: You need [Node.JS](

### 2. Install the dependencies

Just "cd" into sequelize directory and run `npm ci`, see an example below:

$ cd path/to/sequelize
$ npm ci

### 3. Database

Database instances for testing can be started using Docker or you can use local instances of MySQL and PostgreSQL.

#### 3.a Local instances

For MySQL and PostgreSQL you'll need to create a DB called `sequelize_test`.
For MySQL this would look like this:

$ echo "CREATE DATABASE sequelize_test;" | mysql -uroot

**HINT:** by default, your local MySQL install must be with username `root` without password. If you want to customize that, you can set the environment variables `SEQ_DB`, `SEQ_USER`, `SEQ_PW`, `SEQ_HOST` and `SEQ_PORT`.

For Postgres, creating the database and (optionally) adding the test user this would look like:

$ psql

# create database sequelize_test;
# create user postgres with superuser; -- optional; usually built-in

You may need to specify credentials using the environment variables `SEQ_PG_USER` and `SEQ_PG_PW` when running tests or set a password of 'postgres' for the postgres user on your local database to allow sequelize to connect via TCP to localhost. Refer to `test/config/config.js` for the default credentials and environment variables.

For Postgres you may also need to install the `postgresql-postgis` package (an optional component of some Postgres distributions, e.g. Ubuntu). The package will be named something like: `postgresql-<pg_version_number>-postgis-<postgis_version_number>`, e.g. `postgresql-9.5-postgis-2.2`. You should be able to find the exact package name on a Debian/Ubuntu system by running the command: `apt-cache search -- -postgis`.

Create the following extensions in the test database:

#### 3.b Docker

Make sure `docker` and `docker-compose` are installed.

If running on macOS, install [Docker for Mac](

Now launch the docker mysql and postgres servers with this command (you can add `-d` to run them in daemon mode):

$ docker-compose up postgres-95 mysql-57 mssql

> **_NOTE:_** If you get the following output:
>Creating mysql-57 ... error
>ERROR: for mysql-57  Cannot create container for service mysql-57: b'create .: volume name is too short, names should be at least two alphanumeric characters'
>ERROR: for mysql-57  Cannot create container for service mysql-57: b'create .: volume name is too short, names should be at least two alphanumeric characters'
>ERROR: Encountered errors while bringing up the project.
>You need to set the variables `MARIADB_ENTRYPOINT` and `MYSQLDB_ENTRYPOINT` accordingly:
>$ export MARIADB_ENTRYPOINT="$PATH_TO_PROJECT/test/config/mariadb"
>$ export MYSQLDB_ENTRYPOINT="$PATH_TO_PROJECT/test/config/mysql"

**MSSQL:** Please run `npm run setup-mssql` to create the test database.

**POSTGRES:** Sequelize uses [special]( Docker image for PostgreSQL, which install all the extensions required by tests.

### 4. Running tests

All tests are located in the `test` folder (which contains the
lovely [Mocha]( tests).

$ npm run test-all || test-mysql || test-sqlite || test-mssql || test-postgres || test-postgres-native

$ # alternatively you can pass database credentials with $variables when testing
$ DIALECT=dialect SEQ_DB=database SEQ_USER=user SEQ_PW=password npm test

For docker users you can use these commands instead

$ DIALECT=mysql npm run test-docker # Or DIALECT=postgres for Postgres SQL

# Only integration tests
$ DIALECT=mysql npm run test-docker-integration

### 5. Commit

Sequelize follows the [AngularJS Commit Message Conventions](

    feat(pencil): add 'graphiteWidth' option

Commit messages are used to automatically generate a changelog. They will be validated automatically using [commitlint](

Then push and send your pull request. Happy hacking and thank you for contributing.

# Coding guidelines

Have a look at our [.eslintrc.json]( file for the specifics. As part of the test process, all files will be linted, and your PR will **not** be accepted if it does not pass linting.

# Contributing to the documentation

For contribution guidelines for the documentation, see [](

# Publishing a release (For Maintainers)

1. Ensure that latest build on master is green
2. Ensure your local code is up to date (`git pull origin master`)
3. `npm version patch|minor|major` (see [Semantic Versioning](
4. Update changelog to match version number, commit changelog
5. `git push --tags origin master`
6. `npm publish .`
7. Copy changelog for version to release notes for version on github