pool-by-client

An NPM package to map postgres pools to ids.

Usage no npm install needed!

<script type="module">
  import poolByClient from 'https://cdn.skypack.dev/pool-by-client';
</script>

README

pool-by-client

Glossary

  • Install
  • Usage
  • API
  • Example
  • Publishing to NPM

Install

  • Install pool-by-client package:
npm i pool-by-client

Usage

  • Import into your project
const poolByClient = require('pool-by-client')

  • Call the poolByClient function with parameters:

    1. provider(STRING): name of provider; ie: 'amazon'

    2. container(STRING): name of container; ie: s3 bucket name

    3. file(STRING): name of file in container; ie: s3 key name

    4. opts(OBJECT): options object

    • opts.unique(BOOLEAN): will filter out duplicate database pools. Defaults to false.

  • Returns a promise that resolves as an object with three methods:

    1. dbByClient

    2. dbWriteByClient

    3. endPools

    4. configs

    5. poolMap

  • dbByClient and dbWriteByClient are functions that take in a clientId and returns a respective pool.

  • endPools is a function that ends all pools.

  • configs and poolMap objects are provided if in-depth modifications are needed to be made.

API

  • Supports the following clouds for config storage using the pkgcloud package:

    1. filesystem (local file)
    2. amazon (AWS S3 Storage)
    3. google (Google Cloud Storage)
    4. azure (Azue Cloud Storage)

  • The package uses the parent application's process.env object for env variables.

    • filesystem env variables: DB_CONFIGS_PATH
    • Amazon env variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
    • Google env variables: GOOGLE_KEY_FILE_NAME, GOOGLE_PROJECT_ID
    • Azure env variables: AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_ACCESS_KEY

  • Database Passwords are mapped from process.env properties to prevent passwords from being in public files.

    • For example you would set a variable DATABASE_PASS in your .env file. In the config storage file, the db's password property be set to the name of your .env variable to reference so the package can map the password.

The Config File

  • An array of objects that contains information about each database to create a pool from.

  • clientDbid : A number you want the pool to map to.

  • name : A string representing the client.

  • default : A boolean determining the default database. The dbByClient and dbWriteByClient methods will point to the default database if no argument is provided.

  • db : An object containing the pg pool configurations.

    • writeHost : OPTIONAL. A string representing the host name if CQRS is enabled for read-only. If writeHost property exists, the host will be the read-only host.

    • ssl : OPTIONAL. A boolean to enable SSL. Defaults to false.

    • idleTimeoutMillis : OPTIONAL. A number representing how long in milliseconds for a pool connection to stay alive after idle. Defaults to 10000.

    • max : OPTIONAL. A number representing the max size of the pool. Defaults to 10.

Examples

  • Example of the configs.json file:
[
  {
    "clientDbid": 123,
    "name": "exampleClient",
    "db": {
      "user": "user",
      "password": "DATABASE_PASS",
      "host": "example-host-ro.com",
      "writeHost": "example-host.com",
      "port": 5432,
      "database": "exampleDb",
      "ssl": false,
      "idleTimeoutMillis": 30000,
      "max": 20
    }
  }
]
  • Example of the .env file:
DATABASE_PASS=password123
# PKG_CLOUD_PROVIDER=filesystem
# PKG_CLOUD_PROVIDER=google
# PKG_CLOUD_PROVIDER=azure
PKG_CLOUD_PROVIDER=amazon
PKG_CLOUD_CONTAINER=myBucket
PKG_CLOUD_FILE=dev/configs.json
  • Example of usage in app:
const {
  PKG_CLOUD_PROVIDER, PKG_CLOUD_CONTAINER, PKG_CLOUD_FILE,
} = process.env

const example = async () => {
  const {
    dbByClient,
    dbWriteByClient,
    endPools,
  } = await poolByClient(PKG_CLOUD_PROVIDER, PKG_CLOUD_CONTAINER, PKG_CLOUD_FILE)
  const result = await dbByClient(123).query('SELECT * FROM my_table')
  await endPools()
}

Publishing to NPM

  1. IMPORTANT! Run npm build to update the lib directory with the compiled files and in turn the GitHub repo. If this isn't done, there will be no changes to the package when imported!
  2. Travis will automatically publish to NPM when a feature branch is merged to master. Make sure to update the version number in package.json before doing so.