aurora-sequelize-pg v0.0.2

aurora-sequelize-pg

Sequelize (Typescript) wrapper for AWS Aurora Postgres and local environments.

Connections to an Aurora cluster will authenticate via IAM token.

Usage

1. Install the dependency npm install @homeservenow/aurora-sequelize-pg
2. Start importing modules into your code.

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

const sequelize = initSequelize();

sequelize.addModels([Jobs, Engineers]);

3. Don't include Sequelize 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 {
  ...

4. By default, Sequelize initialization will provide a singleton pattern, hence multiple initializations won't have any effect, using the same pool. This is useful to add the models in the same model declaration and avoid cyclic loops. This is the recommended convention for the package.

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

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

const sequelize = initSequelize({ singleton: true });
sequelize.addModels([MyModel]);

export { MyModel };

5. 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,
  auroraIAMauth: true, // default to false
  aurora: true,
});

Local usage

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

version: "3"

services:
  database:
    image: postgis/postgis
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: my_user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: my_db

Migrations and seeds

A migrator functionality is included in the package, that will create schemas and data located in the root /migrations and /seeders folders, respectively. You can override these folders with MIGRATIONS_FOLDER and SEEDERS_FOLDER env variables. For instance,

src/db/standAloneMigrator.ts

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

standAloneMigrator();

And then run

$ MIGRATIONS_FOLDER=src/db/migrations yarn run ts-node src/db/standAloneMigrator.ts

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

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 by adding a timestamp suffix to the database name, and run all tests inside it. Database can be initialized via testSetUp util, which will run any existing migrations and seeders into the temporary db.

// config.database = 'myLocalDb'
// NODE_ENV=test yarn test
import { testSetUp } from "@homeservenow/aurora-sequelize-pg";
import { MyModel } from "../MyModel"; // using Sequelize singleton

const opts = { database: "myLocalDb" };
const extensions = ["uuid-ossp"];
await testSetUp({ opts, extensions });
// database 'myLocalDb_test1606144592304' created with migrations

await MyModel.create(...

Temporary database behaviour can be disabled with the tempDatabase flag.

await testSetUp({ opts, tempDatabase: false });

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

TODO yarn link

Release cycle

Any PR that is merged to main will trigger a CI flow to bump the npm package version and privately publishing that new version on npm.