waterline 0,2,5,3,8,0,5,0 editorconfig eslint travis-ci Bower npm

An adapter-based ORM for Node.js with support for mysql, mongo, postgres, redis, and more

Star Fork Watch Issue Download
1 week after MIT

Waterline logo

NPM version Master Branch Build Status Master Branch Build Status (Windows) [StackOverflow (waterline)]( http://stackoverflow.com/questions/tagged/waterline) [StackOverflow (sails)]( http://stackoverflow.com/questions/tagged/sails.js)

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 Waterline documentation.

Looking for the version of Waterline used in Sails v0.12? See https://github.com/balderdashy/waterline/tree/0.11.x.

Installation

Install from NPM.

  $ npm install waterline

Overview

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.

It also allows an adapter to define its own methods that don't necessarily fit into the CRUD methods defined by default in Waterline. If an adapter defines a custom method, Waterline will simply pass the function arguments down to the adapter.

Community Adapters

Help

Need help or have a question? Click here.

Bugs   NPM version

To report a bug, click here.

Contribute

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

Tests

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:

SomeModel.create({...})
.meta({
  skipAllLifecycleCallbacks: true
})
.exec(...);

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
skipAllLifecycleCallbacks false Set to true to prevent lifecycle callbacks from running in the query.
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.
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 automigration support.

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,
}

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

New methods

Rough draft of documentation for a few new methods available in Waterline v0.13.

replaceCollection()

Replace the specified collection of one or more parent records with a new set of members.

// For users 3 and 4, change their "pets" collection to contain ONLY pets 99 and 98.
User.replaceCollection([3,4], 'pets')
.members([99,98])
.exec(function (err) {
  // ...
});

Under the covers, what this method actually does varies depending on whether the association passed in uses a junction or not.

We know a plural association must use a junction if either (A) it is one-way ("via-less") or (B) it reciprocates another plural association.

If the association uses a junction, then any formerly-ascribed junction records are deleted, and junction records are created for the new members. Otherwise, if the association doesn't use a junction, then the value of the reciprocal association in former child records is set to null, and the same value in newly-ascribed child records is set to the parent record's ID. (Note that, with this second category of association, there can only ever be one parent record. Attempting to pass in multiple parent records will result in an error.)

addToCollection()

Add new members to the specified collection of one or more parent records.

// For users 3 and 4, add pets 99 and 98 to the "pets" collection.
// > (if either user record already has one of those pets in its "pets",
// > then we just silently skip over it)
User.addToCollection([3,4], 'pets')
.members([99,98])
.exec(function(err){
  // ...
});

removeFromCollection()

Remove members from the the specified collection of one or more parent records.

// For users 3 and 4, remove pets 99 and 98 from their "pets" collection.
// > (if either user record does not actually have one of those pets in its "pets",
// > then we just silently skip over it)
User.removeFromCollection([3,4], 'pets')
.members([99,98])
.exec(function(err) {
  // ...
});

License

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.

image_squidhome@2x.png

Related Repositories

waterline-docs

waterline-docs

Public Documentation for Waterline ...

dogwater

dogwater

A hapi plugin integrating Waterline ORM. ...

bedwetter

bedwetter

Auto-generated, RESTful, CRUDdy route handlers for Waterline models in hapi ...

waterline-graphql

waterline-graphql

GraphQL adapter for the Waterline ORM. ...

sails-dynamodb

sails-dynamodb

Amazon DynamoDB adapter for Waterline / Sails.js ...


Top Contributors

particlebanana mikermcneil dmarcelino sgress454 IanVS tjwebb devinivy vanetix Globegitter khalilTN Zolmeister mkeremguc ghernandez345 ragulka luislobo nbiton wanderer KeitaMoromizato m3talsmith chotiwat mikehostetler connor4312 leedm777 murilopolese mphasize tobalsgithub marnusw nkibler7 arielyang dtoubelis

Releases

-   v0.12.2 zip tar
-   v0.12.1 zip tar
-   v0.12.0 zip tar
-   v0.11.3 zip tar
-   v0.11.2 zip tar
-   v0.11.1 zip tar
-   v0.11.0 zip tar
-   v0.10.31 zip tar
-   v0.10.30 zip tar
-   v0.10.29 zip tar
-   v0.10.28 zip tar
-   v0.10.27 zip tar
-   v0.10.26 zip tar
-   v0.10.25 zip tar
-   v0.10.25-alpha0 zip tar
-   v0.10.24 zip tar
-   v0.10.23 zip tar
-   v0.10.22 zip tar
-   v0.10.21 zip tar
-   v0.10.20 zip tar
-   v0.10.19 zip tar
-   v0.10.19-alpha zip tar
-   v0.10.18 zip tar
-   v0.10.17 zip tar
-   v0.10.5 zip tar
-   v0.10.4 zip tar
-   v0.10.3 zip tar
-   v0.10.2 zip tar
-   v0.10.1 zip tar
-   v0.10.0b zip tar