Sequelize Revision

TIPS | Troubleshooting | Code of Conduct | Contributing | Security Policy | Changelog

Track revisions of your Sequelize models, revert them to any revision or restore them after being destroyed. Written in TypeScript and can be used with sequelize-typescript.

Sequelize Revision is a fork from Sequelize Paper Trail supporting similar options and providing consistent behavior with following improvements:

• Re-written in TypeScript and support type checks
• Working well with or without sequelize-typescript
• Tracking users for making changes with AsyncLocalStorage
• Support JSON data type for storing revisions
• Exclude revision attributes for each model
• Passing revision metadata to operations
• Logging revisions for upsert operations
• Better coverage in unit tests
• Support composite key

Installation

$ npm install --save sequelize-revision

Usage

Sequelize Revision assumes that you already set up your Sequelize connection, for example, like this:

import { Sequelize } from "sequelize";

const sequelize = new Sequelize("sqlite::memory:");

then adding Sequelize Revision is as easy as:

import { SequelizeRevision } from "sequelize-revision";

const sequelizeRevision = new SequelizeRevision(sequelize, options);
const [Revision, RevisionChanges] = sequelizeRevision.defineModels();

which loads the Sequelize Revision library, and the defineModels() method sets up a Revision and RevisionChange models.

Note: If you pass userModel option to the constructor in order to enable user tracking, userModel should be setup before defineModels() is called.

Then for each model that you want to keep a paper trail you simply add:

sequelizeRevision.trackRevision(Model);

Example

import Sequelize from "sequelize";
import { SequelizeRevision } from "sequelize-revision";

const sequelize = new Sequelize("sqlite::memory:");
const sequelizeRevision = new SequelizeRevision(sequelize, options);
const [Revision, RevisionChanges] = sequelizeRevision.defineModels();

const User = sequelize.define("User", { name: Sequelize.STRING });
sequelizeRevision.trackRevision(User);

Options

Sequelize Revision supports various options that can be passed into the initialization. The following are the default options:

Options documentation

Sequelize Models

Revision

RevisionChnage

Migration Guide to 8.x.x

In version 8.x.x, sequelize-revision has moved away from using cls-hooked (which relies on the deprecated async_hook API) to using the more stable AsyncLocalStorage API. This change ensures better performance and stability for tracking asynchronous context in Node.js applications.

For more details, refer to the updated TIPS section in the README.

User Tracking

Before:

import { createNamespace } from "cls-hooked";

const session = createNamespace("my session");
session.set("userId", user.id);

await Model.update({
  /* ... */
});

After:

import { AsyncLocalStorage } from "async_hooks";

const asyncLocalStorage = new AsyncLocalStorage();

await asyncLocalStorage.run(user.id, async () => {
  await Model.update({
    /* ... */
  });
});

Saving Metadata

Before:

import { createNamespace } from "cls-hooked";

const session = createNamespace("my session");
session.set("metaData", { userRole: "admin" });

await Model.update({
  /* ... */
});

New Code (8.x.x):

import { AsyncLocalStorage } from "async_hooks";

const metaDataAsyncLocalStorage = new AsyncLocalStorage();

await metaDataAsyncLocalStorage.run({ userRole: "admin" }, async () => {
  await Model.update({
    /* ... */
  });
});