@middy/db-manager

Middy database manager

Simple database manager for the middy framework

dbManager provides seamless connection with database of your choice. By default it uses knex.js but you can use any tool that you want.

After initialization your database connection is accessible under:

middy((event, context) => {
  const { db } = context;
});

Mind that if you use knex you will also need driver of your choice (check docs), for PostgreSQL that would be:

yarn add pg
// or
npm install pg

Install

To install this middleware you can use NPM:

npm install --save @middy/db-manager

Options

• config: configuration object passed as is to client (knex.js by default), for more details check knex documentation
• client (optional): client that you want to use when connecting to database of your choice. By default knex.js is used but as long as your client is run as client(config) or you create wrapper to conform, you can use other tools. Due to node6 support in middy, knex is capped at version 0.17.3. If you wish to use newer features, provide your own knex client here.
• secretsPath (optional): if for any reason you want to pass credentials using context, pass path to secrets laying in context object - good example is combining this middleware with ssm
• secretsParam (optional): override the connection parameter when setting the password directly from ssm using secretsPath or with rdsSigner. This is ignored when passing an object in. Default: password.
• removeSecrets (optional): By default is true. Works only in combination with secretsPath. Removes sensitive data from context once client is initialized.
• forceNewConnection (optional): Creates new connection on every run and destroys it after. Database client needs to have destroy function in order to properly clean up connections.
• rdsSigner (optional): Will use to create an IAM RDS Auth Token for the database connection using RDS.Signer. See AWS docs for required params, region is automatically pulled from the hostname unless overridden.

Sample usage

Minimal configuration

const handler = middy(async (event, context) => {
  const { db } = context;
  const records = await db.select('*').from('my_table');
  console.log(records);
});
handler.use(dbManager({
  config: {
    client: 'pg',
    connection: {
      host: '127.0.0.1',
      user: 'your_database_user',
      password: 'your_database_password',
      database: 'myapp_test'
    }
  },
}));

Credentials as secrets object

const handler = middy(async (event, context) => {
  const { db } = context;
  const records = await db.select('*').from('my_table');
  console.log(records);
});
handler.use(secretsManager({
    secrets: {
        [secretsField]: 'my_db_credentials' // { user: 'your_database_user', password: 'your_database_password' }
    },
    throwOnFailedCall: true
}));
handler.use(dbManager({
  config: {
    client: 'pg',
    connection: {
      host : '127.0.0.1',
      database : 'myapp_test'
    }
  },
  secretsPath: secretsField
}));

Custom knex (or any other) client and secrets

const knex = require('knex')

const handler = middy(async (event, context) => {
  const { db } = context;
  const records = await db.select('*').from('my_table');
  console.log(records);
});
handler.use(secretsManager({
    secrets: {
        [secretsField]: 'my_db_credentials' // { user: 'your_database_user', password: 'your_database_password' }
    },
    throwOnFailedCall: true
}));
handler.use(dbManager({
  client: knex,
  config: {
    client: 'pg',
    connection: {
      host : '127.0.0.1',
      database : 'myapp_test'
    }
  },
  secretsPath: secretsField
}));

Connect to RDS using IAM Auth Tokens and TLS

const tls = require('tls')
const ca = require('fs').readFileSync(`${__dirname}/rds-ca-2019-root.pem`)  // Download from https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html

const handler = middy(async (event, context) => {
  const { db } = context;
  const records = await db.select('*').from('my_table');
  console.log(records);
});
handler.use(dbManager({
  rdsSigner:{
    region: 'us-east-1',
    hostname: '*****.******.{region}.rds.amazonaws.com',
    username: 'your_database_user_with_iam_role',
    database: 'myapp_test',
    port: '5432'
  },
  secretsPath: 'password',
  config: {
    client: 'pg',
    connection: {
      host: '*****.******.{region}.rds.amazonaws.com',
      user: 'your_database_user_with_iam_role',
      database: 'myapp_test',
      port: '5432',
      ssl: {
        rejectUnauthorized: true,
        ca,
        checkServerIdentity: (host, cert) => {
          const error = tls.checkServerIdentity(host, cert)
          if (error && !cert.subject.CN.endsWith('.rds.amazonaws.com')) {
            return error
          }
        }
      }
    }
  }
}));

Note:

If you're lambda is timing out, likely your database connections are keeping the event loop open. Check out do-not-wait-for-empty-event-loop middleware to resolve this.

See AWS Docs Rotating Your SSL/TLS Certificate to ensure you're using the right certificate.

Middy documentation and examples

For more documentation and examples, refers to the main Middy monorepo on GitHub or Middy official website.

Contributing

Everyone is very welcome to contribute to this repository. Feel free to raise issues or to submit Pull Requests.

License

Licensed under MIT License. Copyright (c) 2017-2018 Luciano Mammino and the Middy team.