{"id":13615614,"url":"https://github.com/MatteoGioioso/serverless-pg","last_synced_at":"2025-04-13T21:31:13.303Z","repository":{"id":38172758,"uuid":"238889587","full_name":"MatteoGioioso/serverless-pg","owner":"MatteoGioioso","description":"A package for managing PostgreSQL connections at SERVERLESS scale","archived":false,"fork":false,"pushed_at":"2024-08-07T06:44:34.000Z","size":444,"stargazers_count":322,"open_issues_count":9,"forks_count":16,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T23:38:22.284Z","etag":null,"topics":["aws","aws-lambda","javascript","nodejs","postgres","postgresql","serverless","serverless-postgres"],"latest_commit_sha":null,"homepage":"","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/MatteoGioioso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-07T09:46:11.000Z","updated_at":"2025-03-13T06:09:43.000Z","dependencies_parsed_at":"2024-01-17T00:55:01.621Z","dependency_job_id":"347429e2-9a42-4a5d-bf70-f497877682c8","html_url":"https://github.com/MatteoGioioso/serverless-pg","commit_stats":{"total_commits":108,"total_committers":8,"mean_commits":13.5,"dds":0.3055555555555556,"last_synced_commit":"3bbd4e888e7960ed99f3f0f33b42d9a68ac31bbb"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGioioso%2Fserverless-pg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGioioso%2Fserverless-pg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGioioso%2Fserverless-pg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGioioso%2Fserverless-pg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatteoGioioso","download_url":"https://codeload.github.com/MatteoGioioso/serverless-pg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248786196,"owners_count":21161413,"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":["aws","aws-lambda","javascript","nodejs","postgres","postgresql","serverless","serverless-postgres"],"created_at":"2024-08-01T20:01:15.762Z","updated_at":"2025-04-13T21:31:08.288Z","avatar_url":"https://github.com/MatteoGioioso.png","language":"JavaScript","readme":"[![Serverless-postgres](logo.png)](https://github.com/MatteoGioioso/serverless-pg/)\n\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/MatteoGioioso/serverless-pg)\n[![npm version](https://badge.fury.io/js/serverless-postgres.svg)](https://badge.fury.io/js/serverless-postgres)\n![GitHub](https://img.shields.io/github/license/MatteoGioioso/serverless-pg)\\\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/matteogioioso)\n\n---\n\n### Slow query? Check [Pgex, PostgreSQL query explainer](https://www.pgex.matteogioioso.com/)\n[![Slow Query? Use postgres explain](./docs/postgres-explain.png)](https://www.pgex.matteogioioso.com/)\n\n---\n\n## What is serverless-pg?\n\nServerless-postgres is a wrapper for **[node-pg](https://github.com/brianc/node-postgres)** Node.js module.\nIt is heavily inspired by Jeremy Daly's **[serverless-mysql](https://github.com/jeremydaly/serverless-mysql)** package.\n\n### Why I need this module?\n\nIn a serverless application a function can scale almost \"infinitely\" by creating separate container instances\nfor each concurrent user.\nEach container can correspond to a database connection which, for performance purposes, is left opened for further\nre-utilization. If we have a sudden spike of concurrent traffic, the available connections can be quickly maxed out\nby other competing functions.\nIf we reach the max connections limit, Postgres will automatically reject any frontend trying to connect to its backend.\nThis can cause heavy disruption in your application.\n\n### What does it do?\n\nServerless-postgres adds a connection management component specifically for FaaS based applications.\nBy calling the method `.clean()` at the end of your functions, the module will constantly monitor the status of all\nthe processes running in the PostgreSQL backend and then, based on the configuration provided,\nwill garbage collect the \"zombie\" connections.\nIf the client fails to connect with `\"sorry, too many clients already\"` error, the module will retry\nusing trusted backoff algorithms.\n\n\u003e **NOTE:** This module *should* work with any PostgreSQL server.\n\u003e It has been tested with AWS's RDS Postgres, Aurora Postgres, and Aurora Serverless.\n\nFeel free to request additional features and contribute =)\n\n## Install\n\n```bash\nnpm i serverless-postgres\n```\n\n## Usage\n\nDeclare the ServerlessClient outside the lambda handler\n\n```javascript\nconst ServerlessClient = require('serverless-postgres')\n\nconst client = new ServerlessClient({\n  user: process.env.DB_USER,\n  host: process.env.DB_HOST,\n  database: process.env.DB_NAME,\n  password: process.env.DB_PASSWORD,\n  port: process.env.DB_PORT,\n  debug: true,\n  delayMs: 3000,\n});\n\nconst handler = async (event, context) =\u003e {\n  await client.connect();\n  const result = await client.query(`SELECT 1+1 AS result`);\n  await client.clean();\n  return {\n    body: JSON.stringify({ message: result.rows[0] }),\n    statusCode: 200\n  }\n}\n\n```\n\nYou can set the configuration dynamically if your secret is stored in a vault\n\n```javascript\nconst ServerlessClient = require('serverless-postgres')\n\nconst client = new ServerlessClient({\n  host: process.env.DB_HOST,\n  database: process.env.DB_NAME,\n  port: process.env.DB_PORT,\n});\n\nconst handler = async (event, context) =\u003e {\n  const { user, password } = await getCredentials('my-secret')\n  client.setConfig({\n    user, password\n  })\n  await client.connect();\n  // ...rest of the code\n}\n\n```\n\n## Connections filtering (\u003e= v2)\n\nThis feature leverage postgres `application_name` to differentiate\nclients created by this library and others, this will avoid terminating connections belonging to long-running\nprocesses, batch jobs, ect...\nBy default, we set the same `application_name` parameter for all the serverless clients, if you wish you can change it\nby just specifying it in the client config:\n\n```javascript\nconst client = new ServerlessClient({\n  application_name: 'my_client',\n});\n```\n\n## Plugins (\u003e= v2)\n\nServerless-postgres is extensible and could be used for any wire compatible postgres engines such as Redshift, Google\nCloud Spanner, CockroachDB, YugabyteDB, etc...\nIf needed you can write your own plugin implementing the following interface:\n\n```typescript\ninterface Plugin {\n  getIdleProcessesListByMinimumTimeout(self: ServerlessClient): Promise\u003cNodePgClientResponse\u003cProcessList\u003e\u003e;\n\n  getIdleProcessesListOrderByDate(self: ServerlessClient): Promise\u003cNodePgClientResponse\u003cProcessList\u003e\u003e;\n\n  processCount(self: ServerlessClient): Promise\u003cNodePgClientResponse\u003cCount\u003e\u003e;\n\n  killProcesses(self: ServerlessClient, pids: string[]): Promise\u003cNodePgClientResponse\u003cany\u003e\u003e;\n\n  showMaxConnections(self: ServerlessClient): Promise\u003cNodePgClientResponse\u003cMaxConnections\u003e\u003e;\n}\n\n```\n\nEvery function supply as argument the serverless client itself so you can access any configuration parameter such\nas `database`, `user`, `applicationName`, `ect...`;\nif your changes are minimal you can inherit the main Postgres plugin class:\n\n```javascript\nclass MyPlugin extends Postgres {\n  constructor() {\n    super();\n  }\n  // ...\n}\n```\n\nYou can then use your plugin like this:\n\n```javascript\n const client = new ServerlessClient({\n  plugin: new MyServerlessPGPlugin(someObject)\n});\n```\n\n## Configuration Options\n\n| Property                 | Type                | Description                                                                                                                                                | Default             | Version |\n|--------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|---------|\n| config                   | `Object`            | A `node-pg` configuration object as defined [here](https://node-postgres.com/api/client)                                                                   | `{}`                |         |\n| maxConnsFreqMs           | `Integer`           | The number of milliseconds to cache lookups of max_connections.                                                                                            | `60000`             |         |\n| manualMaxConnections     | `Boolean`           | if this parameters is set to true it will query to get the maxConnections values, to maximize performance you should set the `maxConnections` yourself     | `false`             |         |\n| maxConnections           | `Integer`           | Max connections of your PostgreSQL, it should be set equal to `max_connections` in your cluster. I highly suggest to set this yourself                     | `100`               |         |\n| strategy                 | `String`            | Name of your chosen strategy for cleaning up \"zombie\" connections, allowed values `minimum_idle_time` or `ranked`                                          | `minimum_idle_time` |         |\n| minConnectionIdleTimeSec | `Number`            | The minimum number of seconds that a connection must be idle before the module will recycle it.                                                            | `0.5`               |         |\n| maxIdleConnectionsToKill | `Integer` or `null` | The amount of max connection that will get killed. Default is `ALL`                                                                                        | `null`              |         |\n| connUtilization          | `Number`            | The percentage of total connections to use when connecting to your PostgreSQL server. A value of `0.80` would use 80% of your total available connections. | `0.8`               |         |\n| debug                    | `Boolean`           | Enable/disable debugging logs.                                                                                                                             | `false`             |         |\n| capMs                    | `Integer`           | Maximum number of milliseconds between connection retries.                                                                                                 | `1000`              |         |\n| baseMs                   | `Integer`           | Number of milliseconds added to random backoff values.                                                                                                     | `2`                 |         |\n| delayMs                  | `Integer`           | Additional delay to add to the exponential backoff.                                                                                                        | `1000`              |         |\n| maxRetries               | `Integer`           | Maximum number of times to retry a connection before throwing an error.                                                                                    | `3`                 |         |\n| processCountCacheEnabled | `Boolean`           | Enable caching for get process count.                                                                                                                      | `False`             |         |\n| processCountFreqMs       | `Integer`           | The number of milliseconds to cache lookups of process count.                                                                                              | `6000`              |         |\n| allowCredentialsDiffing  | `Boolean`           | If you are using dynamic credentials, such as IAM, you can set this parameter to `true` and the client will be refreshed                                   | `false`             |         |\n| library                  | `Function`          | Custom postgres library                                                                                                                                    | `require('pg')`     |         |\n| application_name         | `String`            | This is postgres specific configuration; serverless-pg uses it to avoid closing other applications connections.                                            | `serverless_client` | `\u003e= v2` |\n| plugin                   | `Object`            | This is where you need to initialize your plugin class                                                                                                     | `Postgres`          | `\u003e= v2` |\n\n## Note\n\n- `Serverless-postgres` depends on `pg` package and usually you **do not need to install it on your own**.\n  As some users have observed, if you have installed it on your own, and it is a different version,\n  this package might misbehave.\n","funding_links":["https://www.buymeacoffee.com/matteogioioso"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMatteoGioioso%2Fserverless-pg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMatteoGioioso%2Fserverless-pg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMatteoGioioso%2Fserverless-pg/lists"}