Instances

Building a not-persistant instance

In order to create instances of defined classes just do as follows. You might recognize the syntax if you coded Ruby in the past. Using thebuild-method will return an unsaved object, which you explicitly have to save.

var project = Project.build({
  title: 'my awesome project',
  description: 'woot woot. this will make me a rich man'
})
 
var task = Task.build({
  title: 'specify the project idea',
  description: 'bla',
  deadline: new Date()
})

Built instances will automatically get default values when they were defined:

// first define the model
var Task = sequelize.define('Project', {
  title: Sequelize.STRING,
  rating: { type: Sequelize.STRING, defaultValue: 3 }
})
 
// now instantiate an object
var task = Task.build({title: 'very important task'})
 
task.title  // ==> 'very important task'
task.rating // ==> 3

To get it stored in the database, use thesave-method and catch the events … if needed:

project.save().success(function() {
  // my nice callback stuff
})
 
task.save().error(function(error) {
  // mhhh, wth!
})
 
// you can also build, save and access the object with chaining:
Task
  .build({ title: 'foo', description: 'bar', deadline: new Date() })
  .save()
  .success(function(anotherTask) {
    // you can now access the currently saved task with the variable anotherTask... nice!
  }).error(function(error) {
    // Ooops, do some error-handling
  })

Creating persistant instances

Besides constructing objects, that needs an explicit save call to get stored in the database, there is also the possibility to do all those steps with one single command. It's calledcreate.

Task.create({ title: 'foo', description: 'bar', deadline: new Date() }).success(function(task) {
  // you can now access the newly created task via the variable task
})

Sequelizev1.5.0introduced the possibility to define attributes which can be set via the create method. This can be especially very handy if you create database entries based on a form which can be filled by a user. Using that would for example allow you to restrict theUsermodel to set only a username and an address but not an admin flag:

User.create({ username: 'barfooz', isAdmin: true }, [ 'username' ]).success(function(user) {
  // let's assume the default of isAdmin is false:
  console.log(user.values) // => { username: 'barfooz', isAdmin: false }
})

Updating / Saving / Persisting an instance

Now lets change some values and save changes to the database... There are two ways to do that:

// way 1
task.title = 'a very different title now'
task.save().success(function() {})
 
// way 2
task.updateAttributes({
  title: 'a very different title now'
}).success(function() {})

Sincev1.4.1it's also possible to define which attributes should be saved when callingsave, by passing an array of column names. This is useful when you set attributes based on a previously defined object. E.g. if you get the values of an object via a form of a web app. Furthermore this is used internally forupdateAttributes. This is how it looks like:

task.title = 'foooo'
task.description = 'baaaaaar'
task.save(['title']).success(function() {
 // title will now be 'foooo' but description is the very same as before
})
 
// The equivalent call using updateAttributes looks like this:
task.updateAttributes({ title: 'foooo', description: 'baaaaaar'}, ['title']).success(function() {
 // title will now be 'foooo' but description is the very same as before
})

Destroying / Deleting persistant instances

Once you created an object and got a reference to it, you can delete it from the database. The relevant method isdestroy:

Task.create({ title: 'a task' }).success(function(task) {
  // now you see me...
 
  task.destroy().success(function() {
    // now i'm gone :)
  })
})

Working in bulk (updating multiple rows at once)

In addition to updating a single instance, you can also create, update, and delete multiple instances at once. The functions you are looking for are called

  • Model.bulkCreate
  • Model.update
  • Model.destroy

Since you are working with multiple models, the callbacks will not return DAO instances. BulkCreate will return an array of model instances/DAOs, they will however, unlike create, not have the resulting values of autoIncrement attributes. update and destroywill return the number of affected rows.

First lets look at bulkCreate

User.bulkCreate([
  { username: 'barfooz', isAdmin: true },
  { username: 'foo', isAdmin: true },
  { username: 'bar', isAdmin: false }
]).success(function() { // Notice: There are no arguments here, as of right now you'll have to...
  User.findAll().success(function(users) {
    console.log(users) // ... in order to get the array of user objects
  })
})

To update several rows at once:

Task.bulkCreate([
  {subject: 'programming', status: 'executing'},
  {subject: 'reading', status: 'executing'},
  {subject: 'programming', status: 'finished'}
]).success(function() {
  Task.update(
    {status: 'inactive'} /* set attributes' value */, 
    {subject: 'programming'} /* where criteria */
  ).success(function(affectedRows) {
    // affectedRows will be 2
    Task.findAll().success(function(tasks) {
      console.log(tasks) // the 'programming' tasks will both have a status of 'inactive'
    })
  })
})

And delete them:

Task.bulkCreate([
  {subject: 'programming', status: 'executing'},
  {subject: 'reading', status: 'executing'},
  {subject: 'programming', status: 'finished'}
]).success(function() {
  Task.destroy(
    {subject: 'programming'} /* where criteria */,
    {truncate: true /* truncate the whole table, ignoring where criteria */} /* options */
  ).success(function(affectedRows) {
    // affectedRows will be 2
    Task.findAll().success(function(tasks) {
      console.log(tasks) // no programming, just reading :(
    })
  })
})

If you are accepting values directly from the user, it might be beneficial to limit the columns that you want to actually insert.bulkCreate()accepts a second parameter (an array) to let it know which fields you want to build explicitly

User.bulkCreate([
  { username: 'foo' },
  { username: 'bar', admin: true}
], ['username']).success(function() {
  // nope bar, you can't be admin! 
})
 
// an easier way to keep track of which fields you want to explicitly build, use Object.keys() like so
var objects = [
  { username: 'foo' },
  { username: 'bar' }
]
 
User.bulkCreate(objects, Object.keys(objects)).success(function() {
  // ...
})

bulkCreate()was originally made to be a mainstream/fast way of inserting records, however, sometimes you want the luxury of being able to insert multiple rows at once without sacrificing model validations even when you explicitly tell Sequelize which columns to sift through. You can do by adding a third parameter of an object with the value of{validate: true}

var Tasks = sequelize.define('Task', {
  name: {
    type: Sequelize.STRING,
    validate: {
      notNull: { args: true, msg: 'name cannot be null' }
    }
  },
  code: {
    type: Sequelize.STRING,
    validate: {
      len: [3, 10]
    }
  }
})
 
Tasks.bulkCreate([
  {name: 'foo', code: '123'},
  {code: '1234'},
  {name: 'bar', code: '1'}
], null, {validate: true}).error(function(errors) {
  /* console.log(errors) would look like:
  [
    {
      "record": {
        "code": "1234"
      },
      "errors": {
        "name": [
          "name cannot be null"
        ]
      }
    },
    {
      "record": {
        "name": "bar",
        "code": "1"
      },
      "errors": {
        "code": [
          "String is not in range: code"
        ]
      }
    }
  ]
  */
})

Values of an instance

If you log an instance you will notice, that there is a lot of additional stuff. In order to hide such stuff and reduce it to the very interesting information, you can use thevalues-attribute. Calling it will return only the values of an instance.

Person.create({
  name: 'Rambow',
  firstname: 'John'
}).success(function(john) {
  console.log(john.values)
})
 
// result:
 
// { name: 'Rambow',
//   firstname: 'John',
//   id: 1,
//   createdAt: Tue, 01 May 2012 19:12:16 GMT,
//   updatedAt: Tue, 01 May 2012 19:12:16 GMT
// }

Hint:You can also transform an instance into JSON by usingJSON.stringify(instance). This will basically return the very same asvalues.

Reloading instances

If you need to get your instance in sync, you can use the methodreload. It will fetch the current data from the database and overwrite the attributes of the model on which the method has been called on.

Person.find({ where: { name: 'john' } }).success(function(person) {
  person.name = 'jane'
  console.log(person.name) // 'jane'
 
  person.reload().success(function() {
    console.log(person.name) // 'john'
  })
})

Incrementing certain values of an instance

In order to increment values of an instance without running into concurrency issues, you may useincrement.

First of all you can define a field and the value you want to add to it.

User.find(1).success(function(user) {
  user.increment('my-integer-field', 2).success(/* ... */)
})

Second, you can define multiple fields and the value you want to add to them.

User.find(1).success(function(user) {
  user.increment([ 'my-integer-field', 'my-very-other-field' ], 2).success(/* ... */)
})

Third, you can define an object containing fields and its increment values.

User.find(1).success(function(user) {
  user.increment({
    'my-integer-field':    2,
    'my-very-other-field': 3
  }).success(/* ... */)
})

Decrementing certain values of an instance

In order to decrement values of an instance without running into concurrency issues, you may usedecrement.

First of all you can define a field and the value you want to add to it.

User.find(1).success(function(user) {
  user.decrement('my-integer-field', 2).success(/* ... */)
})

Second, you can define multiple fields and the value you want to add to them.

User.find(1).success(function(user) {
  user.decrement([ 'my-integer-field', 'my-very-other-field' ], 2).success(/* ... */)
})

Third, you can define an object containing fields and its decrement values.

User.find(1).success(function(user) {
  user.decrement({
    'my-integer-field':    2,
    'my-very-other-field': 3
  }).success(/* ... */)
})
© Sascha Depold, et al. 2006 - 2022