Edit Page

Upgrading to Sails v0.12

Sails v0.12 comes with an upgrade to Socket.io and Express, as well as many bug fixes and performance enhancements. While you should find that this version is mostly backwards compatible with Sails v0.11, there are some major changes to sails.sockets.* methods which may affect your app. Those changes are addressed in the migration guide below, so if you are upgrading an existing app from v0.11 and are using sails.sockets methods, please be sure and carefully read the information below. Aside from those changes, running sails lift in an existing project should just work.

The sections below provide a high-level overview of what's changed, major bug fixes, enhancements and new features, as well as a basic tutorial on how to upgrade your v0.11.x Sails app to v0.12.

Installing the update

#

Run the following command from the root of your Sails app:

npm install sails@~0.12.0 --force --save

The --force flag will override the existing Sails dependency installed in your node_modules/ folder with the latest patch release of Sails v0.12, and the --save flag will update your package.json file so that future npm installs will also use the new version.

Things to do immediately after upgrading

#

Overview of changes in v0.12

#

For a full list of changes, see the changelog file for Sails, as well as those for Waterline, sails-hook-sockets and sails.io.js.

Socket Methods

#

Without question, the biggest change in Sails v0.12 is to the API of the low-level sails.sockets methods exposed by the sockets hook. In order to ensure that Sails apps perform flawlessly in a multi-server (aka "multi-node" or "clustered") environment, several low-level methods have been deprecated and some new ones have been added.

The following sails.sockets methods have been deprecated:

If you are using any of those methods in your app, they will still work in v0.12 but you should replace them as soon as possible as they may be removed from Sails in the next version. See the individual doc pages for each method for more information.

Resourceful PubSub Methods

#

The .subscribers() resourceful PubSub method has been deprecated for the same reasons as sails.sockets.subscribers(). Follow the guidelines in the docs for replacing this method if you are using it in your code.

Waterline (ORM) Updates

#

Sails v0.12 comes with the latest version of the Waterline ORM (v0.11.0). There are two API changes to be aware of:

.save() no longer provides a second argument to its callback
#

The callback to the .save() instance method no longer receives a second argument. While requiring the second argument was convenient, it made .save() less performant, especially for apps working with millions of records. This change resolves those issues by eliminating the need to build redundant queries, and preventing your database from having to process them.

If there are places in your app where you have code like this:

sierra.save(function (err, modifiedSierra){
  if (err) { /* ... */  return; }

  // ...
});

You should replace it with:

sierra.save(function (err){
  if (err) { /* ... */  return; }

  // ...
});
Custom column/field names for built-in timestamps
#

You can now configure a custom column name (i.e. field name, for Mongo/Redis folks) for the built-in createdAt and updatedAt attributes. In the past, the top-level autoCreatedAt and autoUpdatedAt model settings could be specified as false to disable the automatic injection of createdAt and updatedAt altogether. That still works as it always has, but now you can also specify string values for one or both of these settings instead. If a string is specified, it will be understood as the custom column (/field) name to use for the automatic timestamp.

{
  attributes: {},
  autoCreatedAt: 'my_cool_created_when_timestamp',
  autoUpdatedAt: 'my_cool_updated_at_timestamp'
}

If you were using the workaround suggested by @sgress454 here, you may want to take advantage of this simpler approach instead.

SQL Adapter Performance

#

Sails-PostgreSQL and Sails-MySQL recieved patch updates that significantly improved performance when populating associations. Thanks to @jianpingw for digging into the source and finding a bug that was processing database records too many times. If you are using either of these adapters, upgrading to `sails-postgresql@0.11.1orsails-mysql@0.11.3` will give you a significant performance boost.

Contributing

#

While not technically part of the release, Sails v0.12 is accompanied by some major improvements to the tools and resources available to contributors. More core hooks are now fully documented (controllers|grunt|logger|cors|responses|orm), and the team has put together a Code of Conduct for contributing to the Sails project.

The biggest change for contributors is the updated contribution guide, which contains the new, streamlined process for feature/enhancement proposals and for merging features, enhancements, and patches into core. As the Sails framework has grown (both the code base and the user base), it's become necessary to establish clearer processes for how issue contributions, code contributions, and contributions to the documentation are reviewed and merged.

Documentation

#

This release also comes with a deep clean of the official reference documentation, and some minor usability improvements to the online docs at https://sailsjs.com/documentation. The entire Sails website is now available in Japanese, and four other translation projects are underway for Korean, Brazillian Portugese, Taiwanese Mandarin, and Spanish.

In addition, the Sails.js project (finally) has an official blog. The Sails.js blog is the new source for all longform updates and announcements about Sails, as well as for our related projects like Waterline, Skipper, and the machine specification.

Need Help?

#

If you run into an unexpected issue upgrading your Sails app to v0.12.0, please review our contribution guide and submit an issue in the Sails GitHub repo.

Need help upgrading?

If your company has the budget, consider purchasing Flagship support. It's a great way to support the ongoing development of the open source tools you use every day. And it gives you an extra lifeline to the Sails core team.

Upgrading