Sequelize Postgres Utilities

2.0.2 · active · verified Wed Apr 22

sequelize-pg-utilities is an opinionated set of database utilities designed to simplify the configuration and connection process for PostgreSQL databases when used with Sequelize or the Sequelize CLI. It standardizes database configuration by integrating values from config files, environment variables, and sensible defaults, and also provides a mechanism for creating the database itself. The current stable version is 2.0.2, with recent updates focused on dependency upgrades and maintenance. The library differentiates itself by addressing the configuration discrepancies between Sequelize and the Sequelize CLI and offering built-in database creation capabilities, abstracting away common setup complexities for PostgreSQL users. Releases typically occur as needed for dependency updates, bug fixes, or significant API changes.

Common errors

```
Cannot find module 'pg'
```
cause The 'pg' package, which is the PostgreSQL client, became a peer dependency in v2.0.0 and must be installed manually.

fix Install 'pg' as a direct dependency: `npm install pg` or `yarn add pg`.
```
TypeError: Cannot read properties of undefined (reading 'dialectOptions')
```
cause Incorrect or missing configuration for `sequelize-pg-utilities`, leading to an incomplete options object being passed to Sequelize.

fix Double-check your `config.json` and environment variables. Ensure `configure(config)` receives a valid object and that the resulting `options` object is properly structured before passing to `new Sequelize()`.
```
ReferenceError: isNew is not defined
```
cause Attempting to access the `isNew` property from the `configure` function's return object in versions 2.0.0 and later.

fix Replace all instances of `isNew` with `dbNew` in your code, as the property name was standardized in v2.0.0.

Warnings

breaking The `operatorsAliases` option was completely removed. If your project still relies on this Sequelize feature, you must either downgrade or refactor your queries.
Fix: Remove `operatorsAliases` from your Sequelize configuration. For deprecated operators, use the new symbol-based operators introduced in Sequelize v5+ (e.g., `Op.eq` instead of `$eq`).
breaking The internal `pgtools` dependency was removed, and `pg` was transitioned to a peer dependency. This means `pg` must now be explicitly installed in your project.
Fix: Ensure `pg` is installed as a direct dependency in your project: `npm install pg` or `yarn add pg`.
breaking The return object from `configure` standardized its flag for indicating a newly created database. The mixed usage of `dbNew` and `isNew` was consolidated to exclusively use `dbNew`.
Fix: Update any code accessing the 'is new database' flag to use `dbNew` instead of `isNew` from the `configure` function's return object.
gotcha The package explicitly set its type to `commonjs` in version 1.2.2. While Node.js has CJS-ESM interoperability, projects primarily using ESM may encounter unexpected behavior or require specific configurations.
Fix: Always use `require()` for importing this package's utilities in CommonJS environments. For ESM projects, ensure your build system or Node.js environment is configured to correctly handle CommonJS modules, or consider using dynamic `import()` if static `import` fails.

Install

npm install sequelize-pg-utilities npm
yarn add sequelize-pg-utilities yarn
pnpm add sequelize-pg-utilities pnpm

Imports

configure function
wrong:
```
import { configure } from 'sequelize-pg-utilities';
```
correct:
```
const { configure } = require('sequelize-pg-utilities');
```
This package is CommonJS. Use `require` for named imports. Direct ESM `import` statements will only work with Node.js CJS interop features enabled, which may not be desired in all projects.
Full module object
wrong:
```
import pgUtilities from 'sequelize-pg-utilities';
```
correct:
```
const pgUtilities = require('sequelize-pg-utilities');
// then use pgUtilities.configure(...)
```
When requiring the entire module, access named exports like `configure` as properties of the returned object. A default import (`import pgUtilities from '...'`) is not provided or supported.
TypeScript types
```
import type { ConfigureResult, DbConfig } from 'sequelize-pg-utilities';
```
For TypeScript users, specific types like `ConfigureResult` (the return type of `configure`) and `DbConfig` (for input configuration) can be imported directly for improved type checking.

Quickstart

This quickstart demonstrates how to use `sequelize-pg-utilities` to configure and connect to a PostgreSQL database with Sequelize, including handling environment variables and illustrating database creation.

const { configure } = require('sequelize-pg-utilities');
const { Sequelize } = require('sequelize'); // Assuming Sequelize is installed

// Mock a config/config.json structure
const appConfig = {
  development: {
    username: process.env.DB_USER ?? 'my-dev-user',
    password: process.env.DB_PASS ?? 'my-dev-password',
    database: process.env.DB_NAME ?? 'my-project-development'
  },
  test: { /* ... */ },
  production: { /* ... */ }
};

// To simulate different environments for quickstart
process.env.NODE_ENV = 'development'; 

async function initializeDatabase() {
  try {
    const { name, user, password, options, dbNew } = await configure(appConfig);

    console.log(`Database '${name}' initialized. New database created: ${dbNew}`);
    console.log(`Attempting to connect with user: ${user}`);

    const sequelize = new Sequelize(name, user, password, options);

    await sequelize.authenticate();
    console.log('Database connection has been established successfully.');
    
    // Example: Run a simple query
    const [results] = await sequelize.query('SELECT 1+1 AS solution');
    console.log('Query result:', results[0].solution);

    await sequelize.close();
    console.log('Database connection closed.');
  } catch (error) {
    console.error('Unable to connect to the database or an error occurred:', error);
    process.exit(1);
  }
}

initializeDatabase();

view raw JSON →