microservice-chassis-knex About

A plugin for microservice-chassis that provides knex database connections

During startup, microservice-chassis-knex will scan your environment variables and connect to databases specified there accordingly.

Getting Started

Database connections are specified as environment variables. The name of each variable takes this form: KNEX[_{databaseName}]_{setting}. databaseName may contain underscores. If it is not present, the name default is used. setting may be one of JSON, PGUSER, PGPASSWORD, PGDATABASE, PGPORT, or PGHOST. If JSON is specified, it is used to construct a Knex.Config object. If not, a blank Knex.Config is created. Any of the PG* settings will modify this object with settings appropriate to a Postgresql database connection.

Sidebar: It is possible that additional database types will be directly supported as environment variable setting entries in the future. The current plan is that those will be of the form DBTYPE{SETTING}. For example, there might be SQLITE3FILENAME. In the event we go down that road, we will add checks to make sure that you don't mix PG* settings with other database-specific settings for the same databaseName.

$ npm i --save @earnest-labs/microservice-chassis
$ npm i --save @earnest-labs/microservice-chassis-knex

$ KNEX_JSON='{"client": "sqlite3", "connection": {"filename": ":memory:"}, "useNullAsDefault": true}' \
    npx chassis-start
# ^^^ connects to a new in-memory sqlite3 database, accessible as knexPlugin.defaultConnectionName

Ctrl+C

$ KNEX_DB1_PGUSER=theuser \
  KNEX_DB1_PGPASSWORD=thepassword \
  KNEX_DB1_PGDATABASE=thedatabase \
  KNEX_DB1_PGHOST=thehost.dns.record.com \
    npx chassis-start
# ^^^ connects to the specified postgresql database, accessible as "DB1"

Ctrl+C

From other microservice-chassis plugins, you may want to grab a connection and make calls:

import Plugin from '@earnest-labs/microservice-chassis/Plugin.js';
import PluginContext from '@earnest-labs/microservice-chassis/PluginContext.js';
import { defaultConnectionName } from '@earnest-labs/microservice-chassis-knex/knex.chassis-plugin.js';
import type * as knex from 'knex';

export const handler = (conn: knex.Knex) => async (request, response) => {
  const resp = await conn("users").count("id").first();
  response.json({
    status: 'ok',
    data: resp,
  });
}

export const plugin: Plugin = {
  name: 'knex-consumer-plugin',
  version: '1.0.0',
  requiredPlugins: ['knex'],
  register: async(context: PluginContext, { knex }: { knex: Map<string, knex.Knex> }) : Promise<void> => {
    const conn = knex.get(defaultConnectionName);
    if (conn) {
      context.application.get("/health/db", handler(conn));
    } else {
      // Optionally, handle the error or log it
      throw new Error("Knex connection is undefined");
    }
  }
}