{"id":16683,"library":"sequelize-pg-utilities","title":"Sequelize Postgres Utilities","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/davesag/sequelize-pg-utilities","tags":["javascript","postgres","postgresql","database","configuration","config"],"install":[{"cmd":"npm install sequelize-pg-utilities","lang":"bash","label":"npm"},{"cmd":"yarn add sequelize-pg-utilities","lang":"bash","label":"yarn"},{"cmd":"pnpm add sequelize-pg-utilities","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for PostgreSQL database interaction. Became a peer dependency in v2.0.0, meaning it must be installed manually by the user.","package":"pg","optional":false}],"imports":[{"note":"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.","wrong":"import { configure } from 'sequelize-pg-utilities';","symbol":"configure function","correct":"const { configure } = require('sequelize-pg-utilities');"},{"note":"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.","wrong":"import pgUtilities from 'sequelize-pg-utilities';","symbol":"Full module object","correct":"const pgUtilities = require('sequelize-pg-utilities');\n// then use pgUtilities.configure(...)"},{"note":"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.","symbol":"TypeScript types","correct":"import type { ConfigureResult, DbConfig } from 'sequelize-pg-utilities';"}],"quickstart":{"code":"const { configure } = require('sequelize-pg-utilities');\nconst { Sequelize } = require('sequelize'); // Assuming Sequelize is installed\n\n// Mock a config/config.json structure\nconst appConfig = {\n  development: {\n    username: process.env.DB_USER ?? 'my-dev-user',\n    password: process.env.DB_PASS ?? 'my-dev-password',\n    database: process.env.DB_NAME ?? 'my-project-development'\n  },\n  test: { /* ... */ },\n  production: { /* ... */ }\n};\n\n// To simulate different environments for quickstart\nprocess.env.NODE_ENV = 'development'; \n\nasync function initializeDatabase() {\n  try {\n    const { name, user, password, options, dbNew } = await configure(appConfig);\n\n    console.log(`Database '${name}' initialized. New database created: ${dbNew}`);\n    console.log(`Attempting to connect with user: ${user}`);\n\n    const sequelize = new Sequelize(name, user, password, options);\n\n    await sequelize.authenticate();\n    console.log('Database connection has been established successfully.');\n    \n    // Example: Run a simple query\n    const [results] = await sequelize.query('SELECT 1+1 AS solution');\n    console.log('Query result:', results[0].solution);\n\n    await sequelize.close();\n    console.log('Database connection closed.');\n  } catch (error) {\n    console.error('Unable to connect to the database or an error occurred:', error);\n    process.exit(1);\n  }\n}\n\ninitializeDatabase();","lang":"javascript","description":"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."},"warnings":[{"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`).","message":"The `operatorsAliases` option was completely removed. If your project still relies on this Sequelize feature, you must either downgrade or refactor your queries.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Ensure `pg` is installed as a direct dependency in your project: `npm install pg` or `yarn add pg`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update any code accessing the 'is new database' flag to use `dbNew` instead of `isNew` from the `configure` function's return object.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.2.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install 'pg' as a direct dependency: `npm install pg` or `yarn add pg`.","cause":"The 'pg' package, which is the PostgreSQL client, became a peer dependency in v2.0.0 and must be installed manually.","error":"Cannot find module 'pg'"},{"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()`.","cause":"Incorrect or missing configuration for `sequelize-pg-utilities`, leading to an incomplete options object being passed to Sequelize.","error":"TypeError: Cannot read properties of undefined (reading 'dialectOptions')"},{"fix":"Replace all instances of `isNew` with `dbNew` in your code, as the property name was standardized in v2.0.0.","cause":"Attempting to access the `isNew` property from the `configure` function's return object in versions 2.0.0 and later.","error":"ReferenceError: isNew is not defined"}],"ecosystem":"npm"}