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.
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.
socket.io-redis
adapter, upgrade to at least version 1.0.0 (npm install --save socket.io-redis@^1.0.0
).assets/js/dependencies/sails.io.js
) on the front end, also install the newest version (sails generate sails.io.js --force
).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.
sails.getRouteFor()
and sails.getUrlFor()
methods.sails.socket.*
methods, and made additional adjustments and improvements related to the latest socket.io upgrade. Added a much tighter Redis integration that sits on top of socket.io-redis
, using a Redis client to implement cross-server communication rather than an additional socket client.sails.socket.*
methods, normalizing overloaded functions and deprecating methods which cause problems in multiserver deployments (more on that below)..leaveAll()
, .addRoomMembersToRooms()
, and .removeRoomMembersFromRooms()
.sails.sockets.id()
is now sails.sockets.getId()
(backwards compatible with deprecation message).sails.io.js
(the JavaScript Sails socket client). This upgrade bundles the latest version of socket.io-client
, as well as some more advanced functionality (including the ability to specify common headers for all virtual socket requests).grunt-contrib-*
dependencies (eliminates many NPM deprecation warnings and provides better error messages from NPM).sails new
will now run npm install
instead of symlinking your new app's initial dependencies. This is slower than you may be used to, but it is a necessary change due to changes in the way NPM handles nested dependencies. The core maintainers are working on a better long-term solution, but in the meantime if you frequently run sails new
and the slowdown is bugging you, consider temporarily downgrading to an earlier version of NPM (v2.x). If the installed version of NPM is prior to version 3, Sails will continue to take advantage of the classic symlinking strategy.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:
.emit()
.id()
(renamed to .getId()
).socketRooms()
.rooms()
.subscribers()
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.
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.
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 callbackThe 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; }
// ...
});
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.
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 `[email protected]or
[email protected]` will give you a significant performance boost.
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.
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.
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.