A sails hook that enables the use of wetland ORM.
Latest commit e34e154 Feb 10, 2017 @RWOverdijk RWOverdijk 1.2.0



A sails hook that enables the use of wetland ORM. It might be useful to take a look at the quick start of wetland.

More documentation and examples will follow.


  • All default sails blueprints.
  • Nested populates.
  • Migrations.
  • Runs side-by-side with waterline.
  • Unit of work (transactions).
  • Dirty checking (optimized).
  • Lower memory footprint.
  • Performance.
  • And the rest of the wetland features.


  1. sails new myapplication
  2. cd $_
  3. npm i sails-hook-wetland --save
  4. Choose an adapter (list below) npm i --save sqlite3
  5. mkdir api/entity


Out of the box, wetland works with sqlite3, so there's no need to configure anything. An extensive list with config options and explanation can be found in the wetland documentation.

Example config

The simplest configuration (which will be what's used 9/10 times) is as follows:


const path = require('path');

module.exports.wetland = {
  entityPath: path.resolve(process.cwd(), 'api', 'entity'),
  stores    : {
    defaultStore: {
      client    : 'mysql',
      connection: {
        host    : '',
        user    : 'your_database_user',
        password: 'your_database_password',
        database: 'myapp_test'

Wetland supports master/slave setups and pooling. Documentation for these features will be added in the nearby future.

Wetland CLI

To be able to use the wetland CLI, a wetland.js or wetland.json file must be present in the root directory of your project. The wetland cli allows you to run & create migrations, manage your schema and work with snapshots.

The easiest way to do this is by creating a file called wetland.js in the root of your directory with the following contents:

module.exports = require('./config/wetland').wetland;

Installing the CLI

In order to use the CLI, you'll have to install it first. You can do this by running npm i -g wetland. You can verify installation worked by running wetland --version.


Adapter Command
mysql npm i mysql --save
mysql2 npm i mysql2 --save
pg npm i pg --save
sqlite3 npm i sqlite3 --save
mariasql npm i mariasql --save
strong-oracle npm i strong-oracle --save
oracle npm i oracle --save
mssql npm i mssql --save

Differences with waterline

The differences are minimal out of the box when working with blueprints. Once you start writing custom code, the differences become more clear.

No validation

Validation is a precious feature, that does not belong in an ORM. Because wetland entities are simple classes, you can apply your own validation easily.

A good library for this is joi, which is a joy to work with.

In the future there will be an opinionated validation plugin for wetland. If there's enough demand, this will be bumped up on the priority list.

Unit of work

To be able to guarantee data safety, wetland uses transactions for all queries. These queries are calculated once you flush the changes.

Flushing will trigger the unit of work to calculate changes you made (new, changed, removed and linked entities).

No entity methods

Wetland doesn't have model methods. It separates logic and state using Entities and Repositories.

Instead, you'll be using repositories to fetch data from the database. Each entity can have its own repository, so it's possible to create your own repository and have it contain custom queries (using the query builder, or native).


Wetland supports migrations, including creating, running and auto-running (dev migrations) them.


IDs on entities

Out of the box, entities are exactly as you define them. No magical PK, no autoUpdatedAt or autoCreatedAt. All of these are up to you to implement. Because entities are just classes, you can create a base class and extend it.

Entity definition

The way you specify the mappings for your entities is different.


In api, create a directory called entity. This is where wetland will look for your entities (comparable to models for waterline).


Req methods


Get the repository for provided Entity. If none was supplied, the Entity for the current blueprint will be used instead.

See also: EntityRepository.