@middy/db-manager
    TypeScript icon, indicating that this package has built-in type declarations

    1.5.2 • Public • Published

    Middy database manager

    Middy logo

    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.

    FOSSA Status

    Install

    npm i @middy/db-manager

    DownloadsWeekly Downloads

    339

    Version

    1.5.2

    License

    MIT

    Unpacked Size

    20.6 kB

    Total Files

    7

    Last publish

    Collaborators

    • lmammino
    • middyjs
    • willfarrell