Class Sequelize

View code This is the main class, the entry point to sequelize. To use it, you just need to import sequelize:

var Sequelize = require('sequelize');

In addition to sequelize, the connection library for the dialect you want to use should also be installed in your project. You don't need to import it however, as sequelize will take care of that.

new Sequelize(database, [username=null], [password=null], [options={}])

View code Instantiate sequelize with name of database, username and password

Example usage

// without password and options
var sequelize = new Sequelize('database', 'username')

// without options
var sequelize = new Sequelize('database', 'username', 'password')

// without password / with blank password
var sequelize = new Sequelize('database', 'username', null, {})

// with password and options
var sequelize = new Sequelize('my_database', 'john', 'doe', {})

// with uri (see below)
var sequelize = new Sequelize('mysql://localhost:3306/database', {})

Params:

Name Type Description
database String The name of the database
[username=null] String The username which is used to authenticate against the database.
[password=null] String The password which is used to authenticate against the database.
[options={}] Object An object with options.
[options.dialect='mysql'] String The dialect you of the database you are connecting to. One of mysql, postgres, sqlite and mariadb
[options.dialectModulePath=null] String If specified, load the dialect library from this path. For example, if you want to use pg.js instead of pg when connecting to a pg database, you should specify 'pg.js' here
[options.dialectOptions] Object An object of additional options, which are passed directly to the connection library
[options.storage] String Only used by sqlite. Defaults to ':memory:'
[options.host='localhost'] String The host of the relational database.
[options.port=] Integer The port of the relational database.
[options.protocol='tcp'] String The protocol of the relational database.
[options.define={}] Object Default options for model definitions. See sequelize.define for options
[options.query={}] Object Default options for sequelize.query
[options.set={}] Object Default options for sequelize.set
[options.sync={}] Object Default options for sequelize.sync
[options.timezone='+00:00'] String The timezone used when converting a date from the database into a javascript date. The timezone is also used to SET TIMEZONE when connecting to the server, to ensure that the result of NOW, CURRENT_TIMESTAMP and other time related functions have in the right timezone. For best cross platform performance use the format +/-HH:MM.
[options.logging=console.log] Function A function that gets executed everytime Sequelize would log something.
[options.omitNull=false] Boolean A flag that defines if null values should be passed to SQL queries or not.
[options.queue=true] Boolean Queue queries, so that only maxConcurrentQueries number of queries are executing at once. If false, all queries will be executed immediately.
[options.maxConcurrentQueries=50] Integer The maximum number of queries that should be executed at once if queue is true.
[options.native=false] Boolean A flag that defines if native library shall be used or not. Currently only has an effect for postgres
[options.replication=false] Boolean Use read / write replication. To enable replication, pass an object, with two properties, read and write. Write should be an object (a single server for handling writes), and read an array of object (several servers to handle reads). Each read/write server can have the following properties: host, port, username, password, database
[options.pool={}] Object Should sequelize use a connection pool. Default is true
[options.pool.maxConnections] Integer
[options.pool.minConnections] Integer
[options.pool.maxIdleTime] Integer The maximum time, in milliseconds, that a connection can be idle before being released
[options.pool.validateConnection] Function A function that validates a connection. Called with client. The default function checks that client is an object, and that its state is not disconnected
[options.quoteIdentifiers=true] Boolean Set to false to make table names and attributes case-insensitive on Postgres and skip double quoting of them.

new Sequelize(uri, [options={}])

View code Instantiate sequlize with an URI

Params:

Name Type Description
uri String A full database URI
[options={}] object See above for possible options

models

View code Models are stored here under the name given to sequelize.define

Sequelize

View code A reference to Sequelize constructor from sequelize. Useful for accessing DataTypes, Errors etc.

See:

Utils

View code A reference to sequelize utilities. Most users will not need to use these utils directly. However, you might want to use Sequelize.Utils._, which is a reference to the lodash library, if you don't already have it imported in your project.

See:

Promise

View code A modified version of bluebird promises, that allows listening for sql events

See:

Validator

View code Exposes the validator.js object, so you can extend it with custom validation functions. The validator is exposed both on the instance, and on the constructor.

See:

Transaction

View code A reference to the sequelize transaction class. Use this to access isolationLevels when creating a transaction

See:

Instance

View code A reference to the sequelize instance class.

See:

Error

View code A general error class

See:

ValidationError

View code Emitted when a validation fails

See:

ValidationErrorItem

View code Describes a validation error on an instance path

See:

DatabaseError

View code A base class for all database related errors.

See:

TimeoutError

View code Thrown when a database query times out because of a deadlock

See:

UniqueConstraintError

View code Thrown when a unique constraint is violated in the database

See:

ForeignKeyConstraintError

View code Thrown when a foreign key constraint is violated in the database

See:

getDialect() -> String

View code Returns the specified dialect.

Returns: The specified dialect.

getQueryInterface() -> QueryInterface

View code Returns an instance of QueryInterface.

See:

Returns: An instance (singleton) of QueryInterface.

getMigrator([options={}], [force=false]) -> Migrator

View code Returns an instance (singleton) of Migrator.

See:

Params:

Name Type Description
[options={}] Object See Migrator for options
[force=false] Boolean A flag that defines if the migrator should get instantiated or not.

Returns: An instance of Migrator.

define(modelName, attributes, [options]) -> Model

View code Define a new model, representing a table in the DB.

The table columns are define by the hash that is given as the second argument. Each attribute of the hash represents a column. A short table definition might look like this:

sequelize.define('modelName', {
    columnA: {
        type: Sequelize.BOOLEAN,
        validate: {
          is: ["[a-z]",'i'],        // will only allow letters
          max: 23,                  // only allow values <= 23
          isIn: {
            args: [['en', 'zh']],
            msg: "Must be English or Chinese"
          }
        },
        field: 'column_a'
        // Other attributes here
    },
    columnB: Sequelize.STRING,
    columnC: 'MY VERY OWN COLUMN TYPE'
})

sequelize.models.modelName // The model will now be available in models under the name given to define

As shown above, column definitions can be either strings, a reference to one of the datatypes that are predefined on the Sequelize constructor, or an object that allows you to specify both the type of the column, and other attributes such as default values, foreign key constraints and custom setters and getters.

For a list of possible data types, see http://sequelizejs.com/docs/latest/models#data-types

For more about getters and setters, see http://sequelizejs.com/docs/latest/models#getters---setters

For more about instance and class methods, see http://sequelizejs.com/docs/latest/models#expansion-of-models

For more about validation, see http://sequelizejs.com/docs/latest/models#validations

See:

Params:

Name Type Description
modelName String The name of the model. The model will be stored in sequelize.models under this name
attributes Object An object, where each attribute is a column of the table. Each column can be either a DataType, a string or a type-description object, with the properties described below:
attributes.column String | DataType Object
attributes.column.type String | DataType A string or a data type
[attributes.column.allowNull=true] Boolean If false, the column will have a NOT NULL constraint, and a not null validation will be run before an instance is saved.
[attributes.column.defaultValue=null] Any A literal default value, a javascript function, or an SQL function (see sequelize.fn)
[attributes.column.unique=false] String | Boolean If true, the column will get a unique constraint. If a string is provided, the column will be part of a composite unique index. If multiple columns have the same string, they will be part of the same unique index
[attributes.column.primaryKey=false] Boolean
[attributes.column.field=null] String If set, sequelize will map the attribute name to a different name in the database
[attributes.column.autoIncrement=false] Boolean
[attributes.column.comment=null] String
[attributes.column.references] String | Model If this column references another table, provide it here as a Model, or a string
[attributes.column.referencesKey='id'] String The column of the foreign table that this column references
[attributes.column.onUpdate] String What should happen when the referenced key is updated. One of CASCADE, RESTRICT, SET DEFAULT, SET NULL or NO ACTION
[attributes.column.onDelete] String What should happen when the referenced key is deleted. One of CASCADE, RESTRICT, SET DEFAULT, SET NULL or NO ACTION
[attributes.column.get] Function Provide a custom getter for this column. Use this.getDataValue(String) to manipulate the underlying values.
[attributes.column.set] Function Provide a custom setter for this column. Use this.setDataValue(String, Value) to manipulate the underlying values.
[attributes.validate] Object An object of validations to execute for this column every time the model is saved. Can be either the name of a validation provided by validator.js, a validation function provided by extending validator.js (see the DAOValidator property for more details), or a custom validation function. Custom validation functions are called with the value of the field, and can possibly take a second callback argument, to signal that they are asynchronous. If the validator is sync, it should throw in the case of a failed validation, it it is async, the callback should be called with the error text.
[options] Object These options are merged with the default define options provided to the Sequelize constructor
[options.defaultScope] Object Define the default search scope to use for this model. Scopes have the same form as the options passed to find / findAll
[options.scopes] Object More scopes, defined in the same way as defaultScope above. See Model.scope for more information about how scopes are defined, and what you can do with them
[options.omitNull] Boolean Don't persits null values. This means that all columns with null values will not be saved
[options.timestamps=true] Boolean Adds createdAt and updatedAt timestamps to the model.
[options.paranoid=false] Boolean Calling destroy will not delete the model, but instead set a deletedAt timestamp if this is true. Needs timestamps=true to work
[options.underscored=false] Boolean Converts all camelCased columns to underscored if true
[options.underscoredAll=false] Boolean Converts camelCased model names to underscored tablenames if true
[options.freezeTableName=false] Boolean If freezeTableName is true, sequelize will not try to alter the DAO name to get the table name. Otherwise, the dao name will be pluralized
[options.name] Object An object with two attributes, singular and plural, which are used when this model is associated to others.
[options.name.singular=inflection.singularize(modelName)] String
[options.name.plural=inflection.pluralize(modelName)] String
[options.indexes] Array<Object>
[options.indexes[].name] String The name of the index. Defaults to model name + _ + fields concatenated
[options.indexes[].type] String Index type. Only used by mysql. One of UNIQUE, FULLTEXT and SPATIAL
[options.indexes[].method] String The method to create the index by (USING statement in SQL). BTREE and HASH are supported by mysql and postgres, and postgres additionally supports GIST and GIN.
[options.indexes[].unique=false] Boolean Should the index by unique? Can also be triggered by setting type to UNIQUE
[options.indexes[].concurrently=false] Boolean PostgreSQL will build the index without taking any write locks. Postgres only
[options.indexes[].fields] Array<String | Object> An array of the fields to index. Each field can either be a string containing the name of the field, or an object with the following attributes: attribute (field name), length (create a prefix index of length chars), order (the direction the column should be sorted in), collate (the collation (sort order) for the column)
[options.createdAt] String | Boolean Override the name of the createdAt column if a string is provided, or disable it if false. Timestamps must be true
[options.updatedAt] String | Boolean Override the name of the updatedAt column if a string is provided, or disable it if false. Timestamps must be true
[options.deletedAt] String | Boolean Override the name of the deletedAt column if a string is provided, or disable it if false. Timestamps must be true
[options.tableName] String Defaults to pluralized model name, unless freezeTableName is true, in which case it uses model name verbatim
[options.getterMethods] Object Provide getter functions that work like those defined per column. If you provide a getter method with the same name as a column, it will be used to access the value of that column. If you provide a name that does not match a column, this function will act as a virtual getter, that can fetch multiple other values
[options.setterMethods] Object Provide setter functions that work like those defined per column. If you provide a setter method with the same name as a column, it will be used to update the value of that column. If you provide a name that does not match a column, this function will act as a virtual setter, that can act on and set other values, but will not be persisted
[options.instanceMethods] Object Provide functions that are added to each instance (DAO). If you override methods provided by sequelize, you can access the original method using this.constructor.super_.prototype, e.g. this.constructor.super_.prototype.toJSON.apply(this, arguments)
[options.classMethods] Object Provide functions that are added to the model (Model). If you override methods provided by sequelize, you can access the original method using this.constructor.prototype, e.g. this.constructor.prototype.find.apply(this, arguments)
[options.schema='public'] String
[options.engine] String
[options.charset] String
[options.comment] String
[options.collate] String
[options.hooks] Object An object of hook function that are called before and after certain lifecycle events. The possible hooks are: beforeValidate, afterValidate, beforeBulkCreate, beforeBulkDestroy, beforeBulkUpdate, beforeCreate, beforeDestroy, beforeUpdate, afterCreate, afterDestroy, afterUpdate, afterBulkCreate, afterBulkDestory and afterBulkUpdate. See Hooks for more information about hook functions and their signatures. Each property can either be a function, or an array of functions.
[options.validate] Object An object of model wide validations. Validations have access to all model values via this. If the validator function takes an argument, it is asumed to be async, and is called with a callback that accepts an optional error.

model(modelName) -> Model

View code Fetch a DAO factory which is already defined

Params:

Name Type Description
modelName String The name of a model defined with Sequelize.define

isDefined(modelName) -> Boolean

View code Checks whether a model with the given name is defined

Params:

Name Type Description
modelName String The name of a model defined with Sequelize.define

import(path) -> Model

View code Imports a model defined in another file

Imported models are cached, so multiple calls to import with the same path will not load the file multiple times

See https://github.com/sequelize/sequelize/blob/master/examples/using-multiple-model-files/Task.js for a short example of how to define your models in separate files so that they can be imported by sequelize.import

Params:

Name Type Description
path String The path to the file that holds the model you want to import. If the part is relative, it will be resolved relatively to the calling file

query(sql, [callee], [options={}], [replacements]) -> Promise

View code Execute a query on the DB, with the posibility to bypass all the sequelize goodness.

If you do not provide other arguments than the SQL, raw will be assumed to the true, and sequelize will not try to do any formatting to the results of the query.

See:

Params:

Name Type Description
sql String
[callee] Instance If callee is provided, the returned data will be put into the callee
[options={}] Object Query options.
[options.raw] Boolean If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
[options.transaction=null] Transaction The transaction that the query should be executed under
[options.type='SELECT'] String The type of query you are executing. The query type affects how results are formatted before they are passed back. If no type is provided sequelize will try to guess the right type based on the sql, and fall back to SELECT. The type is a string, but Sequelize.QueryTypes is provided is convenience shortcuts. Current options are SELECT, BULKUPDATE and BULKDELETE
[options.nest=false] Boolean If true, transforms objects with . separated property names into nested objects using dottie.js. For example { 'user.username': 'john' } becomes { user: { username: 'john' }}
[replacements] Object | Array Either an object of named parameter replacements in the format :param or an array of unnamed replacements to replace ? in your SQL.

set(variables, options) -> Promise

View code Execute a query which would set an environment or user variable. The variables are set per connection, so this function needs a transaction. Only works for MySQL.

Params:

Name Type Description
variables Object Object with multiple variables.
options Object Query options.
options.transaction Transaction The transaction that the query should be executed under

createSchema(schema) -> Promise

View code Create a new database schema.

Note,that this is a schema in the postgres sense of the word, not a database table. In mysql and sqlite, this command will do nothing.

See:

Params:

Name Type Description
schema String Name of the schema

showAllSchemas() -> Promise

View code Show all defined schemas

Note,that this is a schema in the postgres sense of the word, not a database table. In mysql and sqlite, this will show all tables.

dropSchema(schema) -> Promise

View code Drop a single schema

Note,that this is a schema in the postgres sense of the word, not a database table. In mysql and sqlite, this drop a table matching the schema name

Params:

Name Type Description
schema String Name of the schema

dropAllSchemas() -> Promise

View code Drop all schemas

Note,that this is a schema in the postgres sense of the word, not a database table. In mysql and sqlite, this is the equivalent of drop all tables.

sync([options={}]) -> Promise

View code Sync all defined DAOs to the DB.

Params:

Name Type Description
[options={}] Object
[options.force=false] Boolean If force is true, each DAO will do DROP TABLE IF EXISTS ..., before it tries to create its own table
[options.match] RegEx Match a regex against the database name before syncing, a safety check for cases where force: true is used in tests but not live code
[options.logging=console.log] Boolean | function A function that logs sql queries, or false for no logging
[options.schema='public'] String The schema that the tables should be created in. This can be overriden for each table in sequelize.define

drop(options) -> Promise

View code Drop all tables defined through this sequelize instance. This is done by calling Model.drop on each model

See:

Params:

Name Type Description
options object The options passed to each call to Model.drop

authenticate() -> Promise

View code Test the connection by trying to authenticate

Aliases: validate

fn (fn, args) -> Sequelize.fn

View code Creates a object representing a database function. This can be used in search queries, both in where and order parts, and as default values in column definitions. If you want to refer to columns in your function, you should use sequelize.col, so that the columns are properly interpreted as columns and not a strings.

Convert a user's username to upper case

instance.updateAttributes({
  username: self.sequelize.fn('upper', self.sequelize.col('username'))
})

See:

Params:

Name Type Description
fn String The function you want to call
args any All further arguments will be passed as arguments to the function

col(col) -> Sequelize.col

View code Creates a object representing a column in the DB. This is often useful in conjunction with sequelize.fn, since raw string arguments to fn will be escaped.

See:

Params:

Name Type Description
col String The name of the column

cast(val, type) -> Sequelize.cast

View code Creates a object representing a call to the cast function.

Params:

Name Type Description
val any The value to cast
type String The type to cast it to

literal(val) -> Sequelize.literal

View code Creates a object representing a literal, i.e. something that will not be escaped.

Params:

Name Type Description
val any

Aliases: asIs

and(args) -> Sequelize.and

View code An AND query

See:

Params:

Name Type Description
args String | Object Each argument will be joined by AND

or(args) -> Sequelize.or

View code An OR query

See:

Params:

Name Type Description
args String | Object Each argument will be joined by OR

json(conditions, [value]) -> Sequelize.json

View code Creates an object representing nested where conditions for postgres's json data-type.

See:

Params:

Name Type Description
conditions String | Object A hash containing strings/numbers or other nested hash, a string using dot notation or a string using postgres json syntax.
[value] String | Number Boolean

where(attr, [comparator='='], logic) -> Sequelize.where

View code A way of specifying attr = condition.

The attr can either be an object taken from Model.rawAttributes (for example Model.rawAttributes.id or Model.rawAttributes.name). The attribute should be defined in your model definition. The attribute can also be an object from one of the sequelize utility functions (sequelize.fn, sequelize.col etc.)

For string attributes, use the regular { where: { attr: something }} syntax. If you don't want your string to be escaped, use sequelize.literal.

See:

Params:

Name Type Description
attr Object The attribute, which can be either an attribute object from Model.rawAttributes or a sequelize object, for example an instance of sequelize.fn. For simple string attributes, use the POJO syntax
[comparator='='] string
logic String | Object The condition. Can be both a simply type, or a further condition (.or, .and, .literal etc.)

Aliases: condition

transaction([options={}]) -> Promise

View code Start a transaction. When using transactions, you should pass the transaction in the options argument in order for the query to happen under that transaction

sequelize.transaction().then(function (t) {
  return User.find(..., { transaction: t}).then(function (user) {
    return user.updateAttributes(..., { transaction: t});
  })
  .then(t.commit.bind(t))
  .catch(t.rollback.bind(t));
})

A syntax for automatically committing or rolling back based on the promise chain resolution is also supported:

sequelize.transaction(function (t) { // Note that we use a callback rather than a promise.then()
  return User.find(..., { transaction: t}).then(function (user) {
    return user.updateAttributes(..., { transaction: t});
  });
}).then(function () {
  // Commited
}).catch(function (err) {
  // Rolled back
  console.error(err);
});

See:

Params:

Name Type Description
[options={}] Object
[options.autocommit=true] Boolean
[options.isolationLevel='REPEATABLE String READ'] See Sequelize.Transaction.ISOLATION_LEVELS for possible options

This document is automatically generated based on source code comments. Please do not edit it directly, as your changes will be ignored. Please write on IRC, open an issue or a create a pull request if you feel something can be improved. For help on how to write source code documentation see JSDoc and dox