{"id":19435301,"url":"https://github.com/nb1987/pg-ez","last_synced_at":"2026-05-12T20:09:42.690Z","repository":{"id":57322616,"uuid":"130946086","full_name":"nb1987/pg-ez","owner":"nb1987","description":"Library for simplifying and enhancing the node-postgres (pg) API.","archived":false,"fork":false,"pushed_at":"2018-05-26T18:25:10.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-08T20:45:04.205Z","etag":null,"topics":["node-module","node-postgres","nodejs-modules","pg","postgres","postgresql","postgresql-database","rdbms"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nb1987.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-25T03:32:02.000Z","updated_at":"2018-05-18T01:11:31.000Z","dependencies_parsed_at":"2022-08-25T20:00:10.431Z","dependency_job_id":null,"html_url":"https://github.com/nb1987/pg-ez","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nb1987%2Fpg-ez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nb1987%2Fpg-ez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nb1987%2Fpg-ez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nb1987%2Fpg-ez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nb1987","download_url":"https://codeload.github.com/nb1987/pg-ez/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240619430,"owners_count":19830204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node-module","node-postgres","nodejs-modules","pg","postgres","postgresql","postgresql-database","rdbms"],"created_at":"2024-11-10T15:05:22.830Z","updated_at":"2026-05-12T20:09:37.652Z","avatar_url":"https://github.com/nb1987.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# pg-ez - node-postgres made easy\n[node-postgres](https://github.com/brianc/node-postgres) is not particularly difficult to use and has [a well-documented API](https://node-postgres.com), but as that documentation states, \"node-postgres strives to be low level an un-opinionated.\" pg-ez, on the other hand, strives to be high-level and (more) opinionated, allowing you to get up and querying within seconds rather than minutes. It uses best practices as recommend by node-postgres, so you don't have to concern yourself with things like releasing clients back to a pool. \n\n## Installation\n\n`npm install pg-ez`\n\n## Testing\n\n`npm test`\n\nThe tests test `pg-ez`'s integration with `node-postgres` but run quickly. The tests require you to have defined environment variables for `PGUSER`, `PGPASSWORD`, `PGHOST`, `PGPORT`, and `PGDATABASE`.\n\n## Documentation\n\n* [Establishing a database connection](#connection)\n  * [Example 1: passing in a connection string](#connection-ex1)\n  * [Example 2: passing in a connection object](#connection-ex2)\n  * [Example 3: passing in nothing](#connection-ex3)\n* [Querying](#querying)\n  * [Example 1: using `async` / `await`](#querying-ex1)\n  * [Example 2: using promises](#querying-ex2)\n  * [Example 3: using callbacks](#querying-ex3)\n* [Streaming](#streams)\n  * [Example 1: streaming JSON transform of results to `http` response](#streams-ex1)\n  * [Example 2: streaming comma-delimited transform of results to CSV file](#streams-ex2)\n* [Transactions](#transactions)\n  * [Example 1: Using `async` / `await`](#transactions-ex1)\n  * [Example 2: Using promises](#transactions-ex2)\n\n\u003ca name=\"connection\" /\u003e\n\n### Establishing a database connection\nRequiring `pg-ez` and establishing a database connection is done in a single line. Like `pg`, you can pass to it a connection string or a connection object; if you pass neither, `pg-ez` will, like `pg`, try to establish a connection using environment variables.\n\n\u003ca name=\"connection-ex1\" /\u003e\n\n#### Example 1: passing in a connection string\n```javascript\nconst db = require('pg-ez')('postgresql://admin:sekrit@localhost:5432/mydb');\n```\n\n\u003ca name=\"connection-ex2\" /\u003e\n\n#### Example 2: passing in a connection object\n```javascript\nconst db = require('pg-ez')({user: 'admin', password: 'sekrit', host: 'localhost', port: 5432, database: 'mydb'});\n```\n\n\u003ca name=\"connection-ex3\" /\u003e\n\n#### Example 3: passing in nothing \n```javascript\n// NOTE: requires that there are defined environment variables for  PGUSER, PGPASSWORD, PGHOST, PGPORT, and PGDATABASE\nconst db = require('pg-ez')();\n```\n\n\u003ca name=\"querying\" /\u003e\n\n### Queries\nQuerying in `pg-ez` is nearly the same as querying in `pg`: simply call the `exec` method and pass to it a query string and parameters, or pass to it a query configuration object. Like `pg`, `pg-ez` supports 3 flavors of asynchronous querying: `async` / `await`, promises, and callbacks. \n\n\u003ca name=\"querying-ex1\" /\u003e\n\n#### Example 1: using `async` / `await`\n```javascript\n(async () =\u003e {\n  try {\n    const result = await db.exec('SELECT $1::VARCHAR AS first_name, $2::VARCHAR AS last_name, $3::INT AS age', ['Peter', 'Gibbons', 32]);\n    console.log(result.rows);\n  } catch (err) {\n    console.error('ERR: ' + err);\n  }\n})();\n```\n\u003ca name=\"querying-ex2\" /\u003e\n\n#### Example 2: using promises\n```javascript\ndb.exec('SELECT $1::VARCHAR AS first_name, $2::VARCHAR AS last_name, $3::INT AS age', ['Peter', 'Gibbons', 32])\n  .then(result =\u003e {\n    console.log(result.rows);\n  })\n  .catch(err =\u003e {\n    console.error('ERR: ' + err);\n  });\n```\n\n\u003ca name=\"querying-ex3\" /\u003e\n\n#### Example 3: using callbacks\n```javascript\ndb.exec('SELECT $1::VARCHAR AS first_name, $2::VARCHAR AS last_name, $3::INT AS age', ['Peter', 'Gibbons', 32], (err, result) =\u003e {\n  if (err) console.error('ERR: ' + err);\n  else console.log(result.rows);\n});\n```\n\n\u003ca name=\"streams\" /\u003e\n\n### Streams\nBig data can bring big problems. If you have a query yielding millions of rows, you probably don't want to put the query results into memory and thereby spike your memory usage. Streams to the rescue! The `stream` method returns a native promise, not a stream; however, this particular promise supports a `pipe` method, allowing you to pass data through and chain together pipes just as though you were dealing with a stream. An error thrown at any point in the pipeline will propagate and can be caught\u0026mdash;as any promise error can be\u0026mdash;with a `catch` method (if using promises) or a `try` / `catch` block (if using `async` / `await`). \n\n\u003ca name=\"streams-ex1\" /\u003e\n\n#### Example 1: stream JSON transform of results to `http` response\n```javascript\nconst JSONStream = require('JSONStream');\nconst http = require('http');\nhttp.createServer((req, res) =\u003e {\n  res.setHeader('Content-Type', 'application/json');\n  db.stream('SELECT generate_series(0, $1, 1) x, generate_series(0, $1, 2) y', [1000])\n    .pipe(JSONStream.stringify())\n    .pipe(res);\n}).listen(1337);\n```\n\n\u003ca name=\"streams-ex2\" /\u003e\n\n#### Example 2: stream comma-delimited transform of results to CSV file\n```javascript\nconst csvStream = require('csv-write-stream')({headers: ['x', 'y']});\nconst fs = require('fs');\nconst fileStream = fs.createWriteStream('./query-output.csv');\n\ndb.stream({text: 'SELECT generate_series(0, $1, 1) x, generate_series(0, $1, 2) y', values: [1000], rowMode: 'array'})\n  .pipe(csvStream)\n  .pipe(fileStream)\n  .then(() =\u003e {\n    console.log('Streaming complete!');\n  })\n  .catch(err =\u003e {\n    console.error('ERR: ' + err);\n  });\n```\n\n\u003ca name=\"transactions\" /\u003e\n\n### Transactions\n\nTransactions are implemented intuitively: simply wrap all your desired statements within a `transaction` \"block.\" The `transaction` method returns a native promise, so you can do follow-up processing with `then() `, or you can use `await` if your `transaction` invocation is inside an `async` function. An error in any query within the transaction block will automatically trigger a rollback, but because `transaction` returns a promise, you can `catch` the error to perform additional error handling.\n\n\u003ca name=\"transactions-ex1\" /\u003e\n\n#### Example 1: Using `async` / `await`\n```javascript\n(async () =\u003e {\n  try {\n    await db.transaction(async (client) =\u003e {\n      // NOTE: It's important that you execute queries against the client passed in as the lone argument to this callback function\n      await client.exec('CREATE TEMP TABLE pg_ez_test_transaction (id SERIAL, first_name VARCHAR(255), last_name VARCHAR(255))');\n      await client.exec('INSERT INTO pg_ez_test_transaction (first_name, last_name)  VALUES ($1, $2)', ['Michael', 'Bolton']);\n    });\n    console.log('Done!');\n  } catch (err) {\n    console.error('ERR: ' + err);\n  }\n})();\n```\n\n\u003ca name=\"transactions-ex2\" /\u003e\n\n#### Example 2: Using promises\n```javascript\ndb.transaction(async (client) =\u003e {\n  // NOTE: It's important that you execute queries against the client passed in as the lone argument to this callback function\n  await client.exec('CREATE TEMP TABLE pg_ez_test_transaction (id SERIAL, first_name VARCHAR(255), last_name VARCHAR(255))');\n  await client.exec('INSERT INTO pg_ez_test_transaction (first_name, last_name)  VALUES ($1, $2)', ['Michael', 'Bolton']);\n})\n.then(function() {\n  console.log('Done!');\n})\n.catch(function(err) {\n  console.error('ERR: ' + err);\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnb1987%2Fpg-ez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnb1987%2Fpg-ez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnb1987%2Fpg-ez/lists"}