First pass at changes to create/destroy manager and get/release connection.

Author: mikermcneil

machines/create-manager.js

@@ -15,7 +15,7 @@ module.exports = {
   '\n'+
   'Note that a manager instance does not necessarily need to correspond with a pool though--'+
   'it might simply be a container for storing config, or it might refer to multiple pools '+
-  '(e.g. a ClusterPool from felixge\'s `mysql` package).',
+  '(e.g. a PoolCluster from felixge\'s `mysql` package).',
 
 
   inputs: {
@@ -109,8 +109,169 @@ module.exports = {
 
 
   fn: function (inputs, exits){
-    // TODO
-    return exits.error();
+    var util = require('util');
+    var Url = require('url');
+    var felix = require('mysql');
+
+
+    // Note:
+    // Support for different types of managers is database-specific, and is not
+    // built into the Waterline driver spec-- however this type of configurability
+    // can be instrumented using `meta`.
+    //
+    // In particular, support for ad-hoc connections (i.e. no pool) and clusters/multiple
+    // pools (see "PoolCluster": https://github.com/felixge/node-mysql/blob/v2.10.2/Readme.md#poolcluster)
+    // could be implemented here, using properties on `meta` to determine whether or not
+    // to have this manager produce connections ad-hoc, from a pool, or from a cluster of pools.
+    //
+    // Feel free to fork this driver and customize as you see fit.  Also note that
+    // contributions to the core driver in this area are welcome and greatly appreciated!
+
+
+
+    // Build a local variable (`_mysqlClientConfig`) to house a dictionary
+    // of additional MySQL options that will be passed into `.createPool()`
+    // (Note that these could also be used with `.connect()` or `.createPoolCluster()`)
+    //
+    // This is pulled from the `connectionString` and `meta` inputs, and used for
+    // configuring stuff like `host` and `password`.
+    //
+    // For a complete list of available options, see:
+    //  • https://github.com/felixge/node-mysql#connection-options
+    //
+    // However, note that supported options are explicitly whitelisted below.
+    var _mysqlClientConfig = {};
+
+
+
+
+    // Validate and parse `meta` (if specified).
+    if ( !util.isUndefined(inputs.meta) ) {
+      if ( !util.isObject(inputs.meta) ) {
+        return exits.error('If provided, `meta` must be a dictionary.');
+      }
+
+      // Use properties of `meta` directly as MySQL client config.
+      // (note that we're very careful to only stick a property on the client config
+      //  if it was not undefined, just in case that matters)
+      [
+        // MySQL Client Options:
+        // ============================================
+
+        // Basic:
+        'host', 'port', 'database', 'user', 'password',
+        'charset', 'timezone', 'ssl',
+
+        // Advanced:
+        'connectTimeout', 'stringifyObjects', 'insecureAuth', 'typeCast',
+        'queryFormat', 'supportBigNumbers', 'bigNumberStrings', 'dateStrings',
+        'debug', 'trace', 'multipleStatements', 'flags',
+
+        // Pool-specific:
+        'acquireTimeout', 'waitForConnections', 'connectionLimit', 'queueLimit',
+
+      ].forEach(function (mysqlClientConfKeyName){
+        if ( !util.isUndefined(inputs.meta[mysqlClientConfKeyName]) ) {
+          _mysqlClientConfig[mysqlClientConfKeyName] = inputs.meta[mysqlClientConfKeyName];
+        }
+      });
+
+
+      // In the future, other special properties of `meta` could be used
+      // as options for the manager-- e.g. whether or not to use pooling,
+      // or the connection strings of replicas, etc.
+
+      // // Now use other special properties of `meta` as our higher-level
+      // // logical machinepack options.
+      // [
+      //   // Machinepack Configuration:
+      //   // ============================================
+      //   '',
+      // ].forEach(function (pkgConfKeyName) {
+      //   // ...
+      // });
+    }
+
+
+    // Validate & parse connection string, pulling out MySQL client config
+    // (call `malformed` if invalid).
+    //
+    // Remember: connection string takes priority over `meta` in the event of a conflict.
+    try {
+      var parsedConnectionStr = Url.parse(inputs.connectionString);
+
+      // Validate that a protocol was found before other pieces
+      // (otherwise other parsed info will be very weird and wrong)
+      if ( !parsedConnectionStr.protocol ) {
+        throw new Error('Protocol (i.e. `mysql://`) is required in connection string.');
+      }
+
+      // Parse port & host
+      var DEFAULT_HOST = 'localhost';
+      var DEFAULT_PORT = 3306;
+      if (parsedConnectionStr.port) { _mysqlClientConfig.port = +parsedConnectionStr.port; }
+      else { _mysqlClientConfig.port = DEFAULT_PORT; }
+      if (parsedConnectionStr.hostname) { _mysqlClientConfig.host = parsedConnectionStr.hostname; }
+      else { _mysqlClientConfig.host = DEFAULT_HOST; }
+
+      // Parse user & password
+      if ( parsedConnectionStr.auth && util.isString(parsedConnectionStr.auth) ) {
+        var authPieces = parsedConnectionStr.auth.split(/:/);
+        if (authPieces[0]) {
+          _mysqlClientConfig.user = authPieces[0];
+        }
+        if (authPieces[1]) {
+          _mysqlClientConfig.password = authPieces[1];
+        }
+      }
+
+      // Parse database name
+      if (util.isString(parsedConnectionStr.pathname) ) {
+        var _databaseName = parsedConnectionStr.pathname;
+        // Trim leading and trailing slashes
+        _databaseName = _databaseName.replace(/^\/+/, '');
+        _databaseName = _databaseName.replace(/\/+$/, '');
+        // If anything is left, use it as the database name.
+        if ( _databaseName ) {
+          _mysqlClientConfig.database = _databaseName;
+        }
+      }
+    }
+    catch (_e) {
+      _e.message = util.format('Provided value (`%s`) is not a valid MySQL connection string.',inputs.connectionString) + ' Error details: '+ _e.message;
+      return exits.malformed({
+        error: _e
+      });
+    }
+
+    // Create a connection pool.
+    //
+    // More about using pools with node-mysql:
+    //  • https://github.com/felixge/node-mysql#pooling-connections
+    var pool = felix.createPool(_mysqlClientConfig);
+
+    // Bind an "error" handler in order to handle errors from connections in the pool,
+    // or from the pool itself. Otherwise, without any further protection, if any MySQL
+    // connections in the pool die, then the process would crash with an error.
+    //
+    // For more background, see:
+    //  • https://github.com/felixge/node-mysql/blob/v2.10.2/Readme.md#error-handling
+    pool.on('error', function (err){
+      // When/if something goes wrong in this pool, call the `onUnexpectedFailure` notifier
+      // (if one was provided)
+      if (!util.isUndefined(onUnexpectedFailure)) {
+        onUnexpectedFailure(err || new Error('One or more pooled connections to MySQL database were lost. Did the database server go offline?'));
+      }
+    });
+
+    // Finally, build and return the manager.
+    var mgr = {
+      pool: pool
+    };
+    return exits.success({
+      manager: mgr
+    });
+
   }
 
 

machines/destroy-manager.js

@@ -4,10 +4,7 @@ module.exports = {
   friendlyName: 'Destroy manager',
 
 
-  description: 'Destroy the specified connection manager and destroying all of its active connections.',
-
-
-  extendedDescription: 'This may involve destroying a single connection, destroying a pool and its connections, destroying multiple pools and their connections, or something even more exotic.  The implementation is left up to the driver.',
+  description: 'Destroy the specified connection manager and destroy all of its active connections.',
 
 
   inputs: {
@@ -37,9 +34,9 @@ module.exports = {
       }
     },
 
-    badManager: {
-      friendlyName: 'Bad manager',
-      description: 'The provided connection manager is no longer active; or possibly never was.',
+    failed: {
+      friendlyName: 'Failed',
+      description: 'Could not destroy the provided connection manager.',
       extendedDescription:
         'Usually, this means the manager has already been destroyed.  But depending on the driver '+
         'it could also mean that database cannot be accessed.  In production, this can mean that the database '+
@@ -56,8 +53,29 @@ module.exports = {
 
 
   fn: function (inputs, exits){
-    // TODO
-    return exits.error();
+    var util = require('util');
+
+    // Note that if this driver is adapted to support managers which spawn
+    // ad-hoc connections or manage multiple pools/replicas using PoolCluster,
+    // then relevant settings would need to be included in the manager instance
+    // so that the manager could be appropriately destroyed here (in the case of
+    // ad-hoc connections, leased connections would need to be tracked on the
+    // manager, and then rounded up and disconnected here.)
+    //
+    // For now, since we only support a single pool, we simply destroy it.
+    //
+    // For more info, see:
+    //  • https://github.com/felixge/node-mysql/blob/v2.10.2/Readme.md#closing-all-the-connections-in-a-pool
+    inputs.manager.pool.end(function (err) {
+      if (err) {
+        return exits.failed({
+          error:  new Error('Failed to destroy the MySQL connection pool and/or gracefully end all connections in the pool.  Details:\n=== === ===\n'+err.stack)
+        });
+      }
+      // All connections in the pool have ended.
+      console.log('FILLED UP THE POOL WITH GRAVEL.');
+      return exits.success();
+    });
   }