@homeservenow/aurora-sequelize-pg NPM

@homeservenow/aurora-sequelize-pg

How do I know if I need this?

you're using AWS aurora, postgres flavour, as your database
you need to use IAM as authentication (regular auth is also supported)
you like sequelize and typescript and you want to use both
you like low-friction, fairly opinionated libraries that will handle some of the complexities of connecting to a DB instance for you

Why

HomeServe Now infrastructure relies on a microservice architecture with a Postgres persistence layer. This package centralizes a bunch of useful database features used in different services.

Features

Sequelize wrapper, designed for but not limited to Postgres.
Singleton Sequelize pattern, to avoid cyclic loops on your model definitions.
SSL/TLS encrypted connections for AWS Aurora.
IAM database authentication
A migrator tool, to run your migrations and seeders files.
Test utils for jest: create a temporary database for each test job.

Usage

Install the dependency yarn add @homeservenow/aurora-sequelize-pg
Start importing modules into your code.

import { initSequelize } from "@homeservenow/aurora-sequelize-pg";

const sequelize = initSequelize({
  opts,
  aurora: true,
  auroraIAMauth: false,
});

sequelize.addModels([Jobs, Users]);

Sequelize dependency is not required in your repository. You can import the original NodeJS package using OriginSequelize, and any Sequelize-Typescript object directly from the package.

import {
  OriginSequelize,
  Table,
  Model,
} from "@homeservenow/aurora-sequelize-pg";

const DATE = OriginSequelize.DataTypes.DATE;

@Table({})
class MyModel extends Model {
  ...

By default, Sequelize initialization will provide a singleton pattern, which is editable as parameter. After the first one, subsequent initializations will use the same sequelize instance and pool of connections. This can save you a dependency nightmare on your model definitions.

import { initSequelize, Table, Model } from "@homeservenow/aurora-sequelize-pg";
import { AnotherModel } from "./AnotherModel";

@Table({})
class MyModel extends Model { ... }

const sequelize = initSequelize({ singleton: true }); // already initialized in AnotherModel, same instance.

sequelize.addModels([MyModel]);

export { MyModel };

Database config and other settings can be defined on initialization.

import {
  initSequelize,
  SequelizeOptions,
} from "@homeservenow/aurora-sequelize-pg";

const opts = {
  logging: true,
  database: "myDatabase",
  username: "postgres",
  password: "p0sTgR3s",
  pool: { max: 10, min: 0, idle: 5000, acquire: 20000 },
};
const auroraIAMauth = true;

const sequelize = initSequelize({
  opts,
  singleton: false,
  auroraIAMauth: true,
  aurora: true,
});

Local usage

Local database can be created using a docker-compose config like the following:

# docker-compose.yml
version: "3"

services:
  database:
    image: postgres
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: my_user
      POSTGRES_PASSWORD: my_password
      POSTGRES_DB: my_db

Migrations and seeds

A migrator functionality is included in the package. It will update if needed any schemas and data from existing directories in the repository.

import { standAloneMigrator } from "@homeservenow/aurora-sequelize-pg";

standAloneMigrator({
  opts,
  migrationsPath,
  seedersPath,
  aurora: true,
  auroraIAMauth: false,
});

Alternatively, you can use sequelize-cli to generate and run migrations, as long as the folders are correctly set up on a .sequelizerc file.

// .sequelizerc
const path = require("path");

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

And then, in your package.json.

  "scripts": {
    "db:generate-migration": "npx sequelize-cli migration:generate --name",
    "db:generate-seed": "npx sequelize-cli seed:generate --name",
    "db:migrate": "npx sequelize-cli db:migrate",
    "db:seed": "npx sequelize-cli db:seed:all",
    "db:up": "docker-compose up -d",

Testing

Test mode is run by setting the NODE_ENV variable to test (automatically defined by Jest). Sequelize initialization will create a new, temporary database, and run all tests inside it. Database can be initialized via testSetUp util, which is recommended to run on the Jest globalSetup file.

import { testSetUp } from "@homeservenow/aurora-sequelize-pg";

module.exports = async () => {
  await testSetUp({
    opts,
    tempDatabase: true,
    extensions,
    migrationsPath,
    seedersPath,
  });
};

Older test databases will be deleted on initialization.

On singleton mode, there will be one temporary database for tests. If singleton mode is disabled, each Sequelize initialization will create and use a different test database.

Development

You can use yarn link command to test the library as a dependency:

On this repository, run yarn link.
On a repository of interest, run yarn link "@homeservenow/aurora-sequelize-pg" to create a symlink to your build.
Test your changes. Remember to yarn build the library before testing them.
Once you are done, yarn unlink (both symlink and in the library).