{"id":18043,"library":"node-postgres-named","title":"Named Parameters for Node-Postgres","description":"node-postgres-named is a utility library designed to introduce named parameter support to the `node-postgres` client by monkeypatching its `query` method. As of its latest release, version 2.4.1 (published in 2018), this package allows developers to write more readable SQL queries using `$name` syntax, which it then translates into the positional `$1`, `$2` parameters required by PostgreSQL. This addresses a deliberate design choice in `node-postgres` to maintain a minimal API consistent with PostgreSQL's native capabilities, which do not inherently support named parameters. Given the absence of updates since 2018, this project is considered abandoned. Consequently, its compatibility with contemporary Node.js versions, recent `node-postgres` releases, and modern JavaScript module systems like ESM is highly uncertain and likely problematic.","status":"abandoned","version":"2.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/bwestergard/node-postgres-named","tags":["javascript"],"install":[{"cmd":"npm install node-postgres-named","lang":"bash","label":"npm"},{"cmd":"yarn add node-postgres-named","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-postgres-named","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package monkeypatches the `pg` (node-postgres) client instance to add named parameter functionality.","package":"pg","optional":false},{"reason":"This package can also monkeypatch `pg-pure` clients, an alternative implementation of node-postgres.","package":"pg-pure","optional":true}],"imports":[{"note":"This library is CommonJS-only and relies on `require` for module loading. Direct ESM `import` is not supported without a wrapper.","symbol":"named","correct":"const named = require('node-postgres-named');"},{"note":"The `patch` function is exported as a property of the main module object, not a named export from the CommonJS module.","wrong":"const { patch } = require('node-postgres-named');","symbol":"patch","correct":"named.patch(client);"}],"quickstart":{"code":"const pg = require('pg');\nconst named = require('node-postgres-named');\n\nconst conString = process.env.DATABASE_URL || 'postgres://user:password@host:5432/database';\n\nasync function runQuery() {\n  const client = new pg.Client(conString);\n  named.patch(client); // Patch the client instance in-place\n\n  try {\n    await client.connect();\n\n    const query = {\n      text: 'SELECT name FROM person WHERE name = $name AND tenure <= $tenure AND age <= $age',\n      values: { 'name': 'Ursus', 'tenure': 2.5, 'age': 24 }\n    };\n\n    const res = await client.query(query);\n    console.log('Query result:', res.rows);\n  } catch (err) {\n    console.error('Error executing query', err.stack);\n  } finally {\n    await client.end();\n  }\n}\n\nrunQuery();","lang":"javascript","description":"This quickstart demonstrates how to import, patch a `pg` client, and then execute a query using named parameters."},"warnings":[{"fix":"Consider migrating to a more modern ORM or query builder that offers named parameter-like functionality natively without monkeypatching, or manually mapping named parameters to positional ones.","message":"This package performs monkeypatching on the `node-postgres` client. Monkeypatching can lead to unexpected behavior, conflicts with other libraries, or compatibility issues with future versions of `node-postgres` or Node.js.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Evaluate alternatives for named parameters or query building that are actively maintained and compatible with current ecosystem standards. If forced to use, thorough testing with your specific `node-postgres` and Node.js versions is crucial.","message":"The project is abandoned, with the last update in 2018. It is highly unlikely to be compatible with recent versions of `node-postgres` (e.g., v8 or later) or modern Node.js runtimes (e.g., Node.js 16+), especially regarding async/await syntax or ESM support.","severity":"gotcha","affected_versions":">=2.4.1"},{"fix":"If using ESM, you will need to `import named from 'node-postgres-named'` (with appropriate `package.json` configuration or a build tool) or explicitly use `createRequire` from `module` to load it in an ESM context.","message":"This library is exclusively CommonJS (`require`). It does not provide native ESM support. Using it in an ESM module will require a CommonJS wrapper or a build step that handles CJS interoperability.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure named parameters strictly adhere to the `$` followed by a letter, then alphanumerics, underscores, or dashes.","message":"The pattern matching for named parameters (`\\$[a-zA-Z]([a-zA-Z0-9_\\-]*)\\b`) is specific. Using unsupported characters or incorrect syntax for named parameters will cause the query to fail or be interpreted incorrectly.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure `client` is a valid, unpatched `pg.Client` instance before calling `named.patch(client)`.","cause":"The `named.patch` function was called on an object that is not a `pg.Client` instance or whose `query` method has been removed or redefined by another library.","error":"TypeError: client.query is not a function"},{"fix":"Double-check that every named parameter (e.g., `$name`) in your SQL query string has a corresponding key in the `values` object, and vice-versa. Also, verify that `named.patch(client)` was successfully called.","cause":"This error can occur if the named parameters in the `text` property of the query object do not exactly match the keys in the `values` object, or if the patching did not correctly transform the query.","error":"Error: bind message supplies N parameters, but prepared statement \"name\" requires M"},{"fix":"If your project is ESM, consider using a dynamic import (`await import('node-postgres-named')`) or revert to CJS if possible. However, the best long-term solution is to migrate to a maintained library for named parameters or ORM functionality.","cause":"Attempting to `require('node-postgres-named')` in an ESM context, or attempting to `import` it when the library itself is CJS-only.","error":"SyntaxError: require() of ES Module ... not supported. Instead, change the require of index.js to a dynamic import() or remove the 'type': 'module' in your package.json."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}