Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Waterline
✓ import { Waterline } from 'waterline';
✗ const Waterline = require('waterline');
ESM import for modern Node.js environments. For older CommonJS (Node <13) or existing projects, use `require`.
Waterline.Collection
✓ import { Waterline } from 'waterline';
// ... then use Waterline.Collection.extend
✗ import { Collection } from 'waterline';
Collection is accessed as a static property of the `Waterline` class, not a direct named export.
Model instances (e.g., User)
✓ const User = collections.user;
✗ import { User } from 'waterline';
Models are registered with and returned by the initialized Waterline instance via `collections`, not directly imported from the package.
This quickstart demonstrates how to use Waterline standalone with a `sails-disk` adapter. It covers initializing Waterline, defining a simple model, performing basic CRUD operations using `async/await` syntax, and tearing down the ORM gracefully. This setup is typical for standalone Waterline applications or for testing environments.
import { Waterline } from 'waterline';
import DiskAdapter from 'sails-disk'; // Example adapter, install with `npm i sails-disk`
// 1. Initialize Waterline
const waterline = new Waterline();
// 2. Define a Collection (Model)
const UserCollection = Waterline.Collection.extend({
identity: 'user',
datastore: 'default',
primaryKey: 'id',
attributes: {
id: { type: 'number', autoIncrement: true },
name: { type: 'string', required: true },
email: { type: 'string', unique: true },
age: { type: 'number', defaultsTo: 18 },
},
});
// 3. Register the Collection
waterline.registerModel(UserCollection);
// 4. Configure Waterline
const config = {
datastores: {
default: {
adapter: 'sails-disk',
},
},
models: {
migrate: 'alter', // 'safe', 'alter', 'drop'
}
};
async function runWaterlineExample() {
try {
// 5. Initialize the ORM
const { collections, connections } = await waterline.initialize(config);
// Access the User model
const User = collections.user;
// Create a new user
const newUser = await User.create({ name: 'Alice', email: 'alice@example.com' }).fetch();
console.log('Created user:', newUser);
// Find all users
const allUsers = await User.find();
console.log('All users:', allUsers);
// Update a user
const updatedUser = await User.updateOne({ id: newUser.id })
.set({ age: 30 })
.fetch();
console.log('Updated user:', updatedUser);
// Clean up (release connections)
await waterline.teardown();
} catch (err) {
console.error('Waterline error:', err);
}
}
runWaterlineExample();
Debug
Known issues
breakingStarting with Waterline v0.13, the API transitioned from callback-based methods to `async/await` (promises). Existing code relying on `.exec(callback)` will break.fixRefactor all query operations to use `await` or `.then().catch()` for promise-based handling. The `.fetch()` method is often needed to retrieve results from `create` and `update` operations.
affects: >=0.13.0
breakingWaterline v0.11.0 removed the second argument from `.save()` commands that previously returned the newly updated data. This change was for performance optimization.fixAfter a `.save()` operation, if you need the updated record, perform a subsequent `.findOne()` or `.find()` query to retrieve the current state of the data.
affects: >=0.11.0
breakingWaterline v0.12.2 fixed critical issues with compatibility in `alter` auto-migrations which were causing corrupted data, especially in SQL adapters. Older versions might have led to data integrity problems.fixUpgrade to Waterline v0.12.2 or higher immediately. Carefully review and backup your data before running migrations with the updated version, especially in production environments.
affects: <0.12.2
gotchaSails.js framework versions have specific Waterline compatibility. Sails v0.12 uses Waterline 0.11.x, whereas Sails v1.0 and later use Waterline v0.13+ (which includes the `await` syntax).fixEnsure your Waterline version matches the requirements of your Sails.js project. Refer to the Sails.js documentation for specific compatibility matrices to avoid unexpected behavior and errors.
affects: *
gotchaIssues were reported and fixed in `v0.12.1` and `v0.11.2` related to searching by `id` in schemaless mode, which could lead to incorrect results or errors.fixIf operating in schemaless mode and encountering problems with `id`-based queries, ensure you are on Waterline `v0.12.1` or `v0.11.2` (or newer patch versions) to benefit from the fixes.
affects: <0.12.1 || <0.11.2
breakingIn Waterline v0.13, criteria objects passed into model methods (e.g., `update`, `createEach`) will be mutated in-place for performance. This was not always the case in v0.12. Also, aggregation clauses (`sum`, `average`, `min`, `max`, `groupBy`) are no longer supported in criteria.fixAvoid reusing or modifying criteria objects after passing them to Waterline methods if their original state is needed. For aggregations, use the new dedicated model methods instead of criteria clauses. Ensure criteria are structured correctly: `{ where: { field: 'value' }, limit: 4 }` instead of mixed top-level properties. affects: >=0.13.0
Errors
Common errors & fixes
TypeError: callback is not a function
Attempting to use the old callback pattern (e.g., `.exec(cb)`) on a query after Waterline's transition to `async/await` (from v0.13).
fixRemove `.exec(cb)` and use `await` before the query, or chain `.then().catch()` to handle the promise. Remember to add `.fetch()` for `create`, `update`, and `destroy` operations to retrieve the record(s).
Error: Adapter 'my-adapter' not registered.
The specified adapter was not correctly installed or registered with the Waterline instance during initialization. Waterline does not ship with adapters.
fixInstall the required adapter package (e.g., `npm install sails-mysql`) and ensure it's imported and explicitly registered in the `config.datastores` object before `waterline.initialize()`.
ReferenceError: MyModel is not defined
Trying to access a Waterline model (e.g., `MyModel.find()`) directly without proper initialization or scoping. Models are exposed via the initialized Waterline instance.
fixEnsure Waterline is fully initialized (`await waterline.initialize(config)`), and then access your models through the returned `collections` object, typically like `const MyModel = collections.mymodel;`.
Error: A record with that unique key already exists.
Attempting to create or update a record with a value that violates a uniqueness constraint defined in the model's attributes (e.g., a duplicate email for a `unique: true` field).
fixImplement error handling for uniqueness violations. Before creating, check if the record exists, or catch the specific error type after the operation and handle it gracefully (e.g., notify the user).
Audit
Dependencies
sails-diskrequiredCommon in-memory/disk-based adapter used for quickstarts and local development; required for the quickstart example. Waterline ships without any adapters, so they must be installed separately.