feathers-sequelize

If you are writing advanced Sequelize queries, follow this two-step workflow:

1. Test in isolation

Create a temporary script to test the query directly against the Sequelize client without the Feathers overhead. This allows you to iterate quickly on the query object.

// test.js
import app from './src/app';
app.setup(); // Initialize relations

const seqClient = app.get('sequelizeClient');
const SomeModel = seqClient.models['some-model'];

SomeModel.findAll({
  /* Your custom query object */
}).then(console.log).catch(console.log);

2. Integrate via a 'before' hook

Once the query works, move the query object into a Feathers before hook by assigning it to context.params.sequelize.

Important: context.params.sequelize is shallow merged onto the underlying query object generated by Feathers. It is not a deep merge. You can override where, limit, offset, and order by setting them here.

function buildCustomQuery(context) {
  context.params.sequelize = {
    /* The object tested in your isolation script */
  };
}

someService.hooks({
  before: {
    find: [buildCustomQuery]
  }
});

If you are upgrading from Feathers v4 to v5, note the following breaking changes in feathers-sequelize:

1. Named Exports

The default export has been removed. You must now import SequelizeService directly.

import { SequelizeService } from 'feathers-sequelize';

app.use('/messages', new SequelizeService({ ... }));

2. Rename operators to operatorMap

The options.operators property is now options.operatorMap.

import { SequelizeService } from 'feathers-sequelize';
import { Op } from 'sequelize';

app.use('/messages', new SequelizeService({
  Model,
  operatorMap: {
    $between: Op.between
  }
}));

3. Use filters for validation

Feathers v5 uses a filters option to verify filters. Add any $dollar.notation$ operators here.

import { SequelizeService } from 'feathers-sequelize';

app.use('/messages', new SequelizeService({
  Model,
  filters: {
    '$and': true,
    '$person.name$': true
  }
}));

To manage database schema changes, use the sequelize-cli. This setup assumes a migrations folder exists in your project root.

1. Install the CLI

npm install sequelize-cli --save -g

2. Configure .sequelizerc

Create a .sequelizerc file in your project root to map the directory structure:

const path = require('path');

module.exports = {
  'config': path.resolve('migrations/config.js'),
  'migrations-path': path.resolve('migrations/scripts'),
  'seeders-path': path.resolve('migrations/seeders'),
  'models-path': path.resolve('migrations/models.js')
};

3. Create Migration Configuration

In migrations/config.js, link your Feathers app to the Sequelize configuration:

const app = require('../src/app');
const env = process.env.NODE_ENV || 'development';
const dialect = 'postgres'; // Or your dialect name

module.exports = {
  [env]: {
    dialect,
    url: app.get(dialect),
    migrationStorageTableName: '_migrations'
  }
};

4. Define Models Configuration

In migrations/models.js, export your existing Sequelize models from the Feathers app:

const Sequelize = require('sequelize');
const app = require('../src/app');
const sequelize = app.get('sequelizeClient');
const models = sequelize.models;

module.exports = Object.assign({
  Sequelize,
  sequelize
}, models);

Migrations require your application's environment variables (like DATABASE_URL) to be present in the terminal session.

Create a migration

Generate a new migration file with a descriptive name:

sequelize migration:create --name="meaningful-name"

Files are stored in migrations/scripts with a timestamp prefix (e.g., 20160421135254-meaningful-name.js) to ensure correct execution order.

Writing up/down scripts

Each migration must implement up (to apply) and down (to undo) functions.

Note: When using changeColumn, you must always specify the type, even if the type is not changing.

Example of changing a column from NOT NULL to nullable:

'use strict';

module.exports = {
  up: function (queryInterface, Sequelize) {
    return queryInterface.changeColumn('tableName', 'columnName', {
      type: Sequelize.STRING,
      allowNull: true
    });
  },

  down: function (queryInterface, Sequelize) {
    return queryInterface.changeColumn('tableName', 'columnName', {
      type: Sequelize.STRING,
      allowNull: false
    });
  }
};

Apply and Undo migrations

• Apply all pending migrations: sequelize db:migrate
• Undo the last migration: sequelize db:migrate:undo

ProTip: You can automate migrations by adding them to your app startup script in package.json:

"scripts": {
    "start": "sequelize db:migrate && node src/"
}

By default, feathers-sequelize returns raw data. To return full Sequelize Model instances (which allow you to use instance methods), you have two options:

1. Before Hook: Set { raw: false } in context.params.sequelize.
2. After Hook: Use the hydrate hook provided by feathers-sequelize.

Warning: When using Sequelize Instances, many feathers-hooks-common hooks will fail. You should use the dehydrate hook to convert data back to plain objects before passing it to standard Feathers hooks.

// Option 1: Before hook
const rawFalse = () => (context) => {
  if (!context.params.sequelize) context.params.sequelize = {};
  Object.assign(context.params.sequelize, { raw: false });
  return context;
}

// Option 2: After hook with hydrate
import { hydrate } from 'feathers-sequelize';

export default {
  after: {
    find: [hydrate()]
  }
};

// Recommended pattern for compatibility with other hooks:
import { dehydrate, hydrate } from 'feathers-sequelize';
import { populate } from 'feathers-hooks-common';

export default {
  after: {
    find: [hydrate(), doSomethingCustom(), dehydrate(), populate()]
  }
};