@caratlane/sqc

SQC (Sequelize Query Commenter)

version 1.1.0 ( added support for v5 & v6 Sequalize)

Overview

SQC (Sequelize Query Commenter) is a package that enables you to add comments to your SQL queries when using the Sequelize ORM (Object-Relational Mapping) with Node.js. It allows you to annotate your queries with meaningful comments, making it easier to understand and maintain your database interactions.

This package provides a simple and convenient way to add comments to your SQL queries without modifying the underlying Sequelize code. By leveraging Sequelize hooks and middlewares, it intercepts and modifies the generated SQL queries to include user-defined comments.

Installation

You can install the Sequelize SQL Query Commenter package using npm:

npm install @caratlane/sqc

Usage

To start using the sqc package, follow these steps:

Import the package into your project:

const commentPlugin = require("@caratlane/sqc");

Attach the sqc middleware to your Sequelize instance:

const Sequelize = require('sequelize');
const commentPlugin = require('@caratlane/sqc');

let sequelize = new Sequelize(/* your database configuration */);

// Attach the query commenter middleware
sequelize = commentPlugin(sequelize);

Add comments to your queries:

const User = sequelize.define('User', {
  name: Sequelize.STRING,
  email: Sequelize.STRING
});

// Add a comment to the query
const users = await User.findAll({
  where: { name: 'John Doe' },
  comment: 'Retrieve users with name John Doe'
});

Run your Sequelize queries as usual, and the comments will be automatically added to the generated SQL queries.

commentPlugin(sequelize)

Attaches the sqc middleware to the provided Sequelize instance.

sequelize: The Sequelize instance to which the middleware will be attached. Query Options The Sequelize SQL Query Commenter extends the Sequelize query options with an additional comment property. You can include this property in your queries to add a comment to the generated SQL query.

comment (string): The comment to be added to the SQL query. It should be a descriptive string that provides additional context or information about the query. Examples Here are a few examples to illustrate how to use the Sequelize SQL Query Commenter:

const users = await User.findAll({
  where: { age: { [Sequelize.Op.gte]: 18 } },
  comment: 'Retrieve adult users'
});

const updatedUser = await User.update(
  { name: 'Jane Doe' },
  {
    where: { id: 1 },
    comment: 'Update user name'
  }
);

const deletedRows = await User.destroy({
  where: { age: { [Sequelize.Op.lt]: 18 } },
  comment: 'Delete underage users'
});

In the above examples, the comments provided in the comment property will be automatically added to the generated SQL queries.

Acknowledgments

This package was inspired by the need to add comments to Sequelize SQL queries and aims to provide a simple and flexible solution. Special thanks to the Sequelize and Node.js communities for their valuable contributions.