npm package: @homeservenow/aurora-sequelize-pg
Description: Sequelize wrapper for AWS Aurora cluster
Latest version: 0.1.5

# @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

1. Install the dependency `yarn add @homeservenow/aurora-sequelize-pg`

2. Start importing modules into your code.

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

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

sequelize.addModels([Jobs, Users]);
```

3. 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.

```javascript
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, 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.

```javascript
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 };
```

5. Database config and other settings can be defined on initialization.

```javascript
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:

```yaml
# 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.

```javascript
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.

```javascript
// .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`.

```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](https://jestjs.io/docs/en/configuration#globalsetup-string) file.

```javascript
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).