Negligible Participation Metric


npm’s 2019 JavaScript ecosystem survey analysis is now available! Get your copy here »


0.13.0-rc1 • Public • Published

Waterline logo

NPM version Master Branch Build Status Master Branch Build Status (Windows) StackOverflow (waterline) StackOverflow (sails)

Waterline is a brand new kind of storage and retrieval engine.

It provides a uniform API for accessing stuff from different kinds of databases, protocols, and 3rd party APIs. That means you write the same code to get and store things like users, whether they live in Redis, MySQL, MongoDB, or Postgres.

Waterline strives to inherit the best parts of ORMs like ActiveRecord, Hibernate, and Mongoose, but with a fresh perspective and emphasis on modularity, testability, and consistency across adapters.

For detailed documentation, see the Sails documentation.

Looking for the version of Waterline used in Sails v0.12? See


Install from NPM.

  $ npm install waterline


Waterline uses the concept of an adapter to translate a predefined set of methods into a query that can be understood by your data store. Adapters allow you to use various datastores such as MySQL, PostgreSQL, MongoDB, Redis, etc. and have a clear API for working with your model data.

Waterline supports a wide variety of adapters both core and community maintained.


Need help or have a question? Click here.

Bugs   NPM version

To report a bug, click here.


Please observe the guidelines and conventions laid out in our contribution guide when opening issues or submitting pull requests.


All tests are written with mocha and should be run with npm:

  $ npm test

Meta Keys

As of Waterline 0.13 (Sails v1.0), these keys allow end users to modify the behaviour of Waterline methods. You can pass them as the meta query key, or via the .meta() query modifier method:

  skipAllLifecycleCallbacks: true

These keys are not set in stone, and may still change prior to release. (They're posted here now as a way to gather feedback and suggestions.)

Meta Key Default Purpose
cascade false Set to true to automatically "empty out" (i.e. call replaceCollection(..., ..., [])) on plural ("collection") associations when deleting a record. Note: In order to do this when the fetch meta key IS NOT enabled (which it is NOT by default), Waterline must do an extra .find().select('id') before actually performing the .destroy() in order to get the IDs of the records that would be destroyed.
fetch false For adapters: When performing .update() or .create(), set this to true to tell the database adapter to send back all records that were updated/destroyed. Otherwise, the second argument to the .exec() callback is undefined. Warning: Enabling this key may cause performance issues for update/destroy queries that affect large numbers of records.
skipAllLifecycleCallbacks false Set to true to prevent lifecycle callbacks from running in the query.
skipRecordVerification false Set to true to skip Waterline's post-query verification pass of any records returned from the adapter(s). Useful for tools like sails-hook-orm's automigrations. Warning: Enabling this flag causes Waterline to ignore customToJSON!
skipExpandingDefaultSelectClause false Set to true to force Waterline to skip expanding the select clause in criteria when it forges stage 3 queries (i.e. the queries that get passed in to adapter methods). Normally, if a model declares schema: true, then the S3Q select clause is expanded to an array of column names, even if the S2Q had factory default select/omit clauses (which is also what it would have if no explicit select or omit clauses were included in the original S1Q.) Useful for tools like sails-hook-orm's automigrations, where you want temporary access to properties that aren't necessarily in the current set of attribute definitions. Warning: Do not use this flag in your web application backend-- or at least ask for help first.

Related model settings

To provide per-model/orm-wide defaults for the cascade or fetch meta keys, there are a few different model settings you might take advantage of:

  attributes: {...},
  primaryKey: 'id',
  cascadeOnDestroy: true,
  fetchRecordsOnUpdate: true,
  fetchRecordsOnDestroy: true,
  fetchRecordsOnCreate: true,
  fetchRecordsOnCreateEach: true,

Not every meta key will necessarily have a model setting that controls it-- in fact, to minimize peak configuration complexity, most will probably not.


MIT. Copyright © 2012-2017 Mike McNeil, Balderdash Design Co., & The Sails Company

Waterline, like the rest of the Sails framework, is free and open-source under the MIT License.



npm i waterline

Downloadsweekly downloads








last publish


  • avatar
  • avatar
  • avatar
  • avatar
Report a vulnerability