Finish stubbing compatibility.

Author: mikermcneil

constants/badConnection.exit.js

@@ -7,9 +7,8 @@ module.exports = {
   description: 'The provided connection is not valid or no longer active.  Are you sure it was obtained by calling this driver\'s `getConnection()` method?',
   extendedDescription: 'Usually, this means the connection to the database was lost due to a logic error or timing issue in userland code.  In production, this can mean that the database became overwhelemed or was shut off while some business logic was in progress.',
   outputVariableName: 'report',
-  outputDescription: 'The `error` property is a JavaScript Error instance containing the raw error from the database.  The `meta` property is reserved for custom driver-specific extensions.',
+  outputDescription: 'The `meta` property is reserved for custom driver-specific extensions.',
   example: {
-    error: '===',
     meta: '==='
   }
 };

machines/create-manager.js

@@ -0,0 +1,117 @@
+module.exports = {
+
+
+  friendlyName: 'Create manager',
+
+
+  description: 'Build and initialize a connection manager instance for this database.',
+
+
+  extendedDescription:
+  'The `manager` instance returned by this method contains any configuration that is necessary '+
+  'for communicating with the database and establishing connections (e.g. host, user, password) '+
+  'as well as any other relevant metadata.  The manager will often also contain a reference '+
+  'to some kind of native container (e.g. a connection pool).\n'+
+  '\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).',
+
+
+  inputs: {
+
+    connectionString: {
+      description: 'A connection string to use to connect to a MySQL database.',
+      extendedDescription: 'Be sure to include credentials.  You can also optionally provide the name of an existing database on your MySQL server.',
+      moreInfoUrl: 'https://gist.github.com/mikermcneil/46d10fd816c980cd3d9f',
+      whereToGet: {
+        url: 'https://gist.github.com/mikermcneil/46d10fd816c980cd3d9f'
+      },
+      example: 'mysql://mikermcneil:p4ssw02D@localhost:3306/some_db',
+      required: true
+    },
+
+    onUnexpectedFailure: {
+      description: 'A function to call any time an unexpected error event is received from this manager or any of its connections.',
+      extendedDescription:
+        'This can be used for anything you like, whether that\'s sending an email to devops, '+
+        'or something as simple as logging a warning to the console.\n'+
+        '\n'+
+        'For example:\n'+
+        '```\n'+
+        'onUnexpectedFailure: function (err) {\n'+
+        '  console.warn(\'Unexpected failure in database manager:\',err);\n'+
+        '}\n'+
+        '```',
+      example: '->'
+    },
+
+    meta:
+      require('../constants/meta.input')
+
+  },
+
+
+  exits: {
+
+    success: {
+      description: 'The manager was successfully created.',
+      extendedDescription:
+        'The new manager should be passed in to `getConnection()`.'+
+        'Note that _no matter what_, this manager must be capable of '+
+        'spawning an infinite number of connections (i.e. via `getConnection()`).  '+
+        'The implementation of how exactly it does this varies on a driver-by-driver '+
+        'basis; and it may also vary based on the configuration passed into the `meta` input.',
+      outputVariableName: 'report',
+      outputDescription: 'The `manager` property is a manager instance that will be passed into `getConnection()`. The `meta` property is reserved for custom driver-specific extensions.',
+      example: {
+        manager: '===',
+        meta: '==='
+      }
+    },
+
+    malformed: {
+      description: 'The provided connection string is not valid for MySQL.',
+      outputVariableName: 'report',
+      outputDescription: 'The `error` property is a JavaScript Error instance explaining that (and preferably "why") the provided connection string is invalid.  The `meta` property is reserved for custom driver-specific extensions.',
+      example: {
+        error: '===',
+        meta: '==='
+      }
+    },
+
+    failed: {
+      description: 'Could not create a connection manager for this database using the specified connection string.',
+      extendedDescription:
+        'If this exit is called, it might mean any of the following:\n'+
+        ' + the credentials encoded in the connection string are incorrect\n'+
+        ' + there is no database server running at the provided host (i.e. even if it is just that the database process needs to be started)\n'+
+        ' + there is no software "database" with the specified name running on the server\n'+
+        ' + the provided connection string does not have necessary access rights for the specified software "database"\n'+
+        ' + this Node.js process could not connect to the database, perhaps because of firewall/proxy settings\n'+
+        ' + any other miscellaneous connection error\n'+
+        '\n'+
+        'Note that even if the database is unreachable, bad credentials are being used, etc, '+
+        'this exit will not necessarily be called-- that depends on the implementation of the driver '+
+        'and any special configuration passed to the `meta` input. e.g. if a pool is being used that spins up '+
+        'multiple connections immediately when the manager is created, then this exit will be called if any of '+
+        'those initial attempts fail.  On the other hand, if the manager is designed to produce adhoc connections, '+
+        'any errors related to bad credentials, connectivity, etc. will not be caught until `getConnection()` is called.',
+      outputVariableName: 'report',
+      outputDescription: 'The `error` property is a JavaScript Error instance with more information and a stack trace.  The `meta` property is reserved for custom driver-specific extensions.',
+      example: {
+        error: '===',
+        meta: '==='
+      }
+    }
+
+  },
+
+
+  fn: function (inputs, exits){
+    // TODO
+    return exits.error();
+  }
+
+
+};

machines/destroy-manager.js

@@ -0,0 +1,64 @@
+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.',
+
+
+  inputs: {
+
+    manager: {
+      friendlyName: 'Manager',
+      description: 'The connection manager instance to destroy.',
+      extendedDescription: 'Only managers built using the `createManager()` method of this driver are supported.  Also, the database connection manager instance provided must not have been destroyed--i.e. once `destroyManager()` is called on a manager, it cannot be destroyed again (also note that all existing connections become inactive).',
+      example: '===',
+      required: true
+    },
+
+    meta:
+      require('../constants/meta.input')
+
+  },
+
+
+  exits: {
+
+    success: {
+      description: 'The specified manager and all of its active connections were successfully destroyed.',
+      outputVariableName: 'report',
+      outputDescription: 'The `meta` property is reserved for custom driver-specific extensions.',
+      example: {
+        meta: '==='
+      }
+    },
+
+    badManager: {
+      friendlyName: 'Bad manager',
+      description: 'The provided connection manager is no longer active; or possibly never was.',
+      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 '+
+        'server(s) became overwhelemed or were shut off while some business logic was in progress.',
+      outputVariableName: 'report',
+      outputDescription: 'The `error` property is a JavaScript Error instance with more information and a stack trace.  The `meta` property is reserved for custom driver-specific extensions.',
+      example: {
+        error: '===',
+        meta: '==='
+      }
+    }
+
+  },
+
+
+  fn: function (inputs, exits){
+    // TODO
+    return exits.error();
+  }
+
+
+};

machines/get-connection.js

@@ -9,14 +9,16 @@ module.exports = {
 
   inputs: {
 
-    connectionString: {
-      description: 'A connection string to use to connect to a MySQL database.',
-      extendedDescription: 'Be sure to include credentials.  You can also optionally provide the name of an existing database on your MySQL server.',
-      moreInfoUrl: 'https://gist.github.com/mikermcneil/46d10fd816c980cd3d9f',
-      whereToGet: {
-        url: 'https://gist.github.com/mikermcneil/46d10fd816c980cd3d9f'
-      },
-      example: 'mysql://mikermcneil:p4ssw02D@localhost:3306/some_db',
+    manager: {
+      friendlyName: 'Manager',
+      description: 'The connection manager instance to acquire the connection from.',
+      extendedDescription:
+        'Only managers built using the `createManager()` method of this driver are supported. '+
+        'Also, the database connection manager instance provided must not have been destroyed--'+
+        'i.e. once `destroyManager()` is called on a manager, no more connections can be acquired '+
+        'from it (also note that all existing connections become inactive-- see `destroyManager()` '+
+        'for more on that).',
+      example: '===',
       required: true
     },
 
@@ -44,19 +46,8 @@ module.exports = {
       }
     },
 
-    malformed: {
-      description: 'The provided connection string is malformed.',
-      extendedDescription: 'The provided connection string is not valid for MySQL.',
-      outputVariableName: 'report',
-      outputDescription: 'The `error` property is a JavaScript Error instance explaining that (and preferably "why") the provided connection string is invalid.  The `meta` property is reserved for custom driver-specific extensions.',
-      example: {
-        error: '===',
-        meta: '==='
-      }
-    },
-
-    failedToConnect: {
-      description: 'Could not acquire a connection to the database using the specified connection string.',
+    failed: {
+      description: 'Could not acquire a connection to the database using the specified manager.',
       extendedDescription: 'This might mean any of the following:\n'+
       ' + the credentials encoded in the connection string are incorrect\n'+
       ' + there is no database server running at the provided host (i.e. even if it is just that the database process needs to be started)\n'+

machines/parse-native-query-error.js

@@ -18,13 +18,6 @@ module.exports = {
 
   inputs: {
 
-    queryType: {
-      description: 'The type of query operation this raw error came from.',
-      extendedDescription: 'Either "select", "insert", "delete", or "update".  This determines how the provided raw error will be parsed/coerced.',
-      required: true,
-      example: 'select',// (select|insert|delete|update)
-    },
-
     nativeQueryError: {
       description: 'The error sent back from the database as a result of a failed native query.',
       extendedDescription: 'This is referring to the raw error; i.e. the `error` property of the dictionary returned through the `queryFailed` exit of `sendNativeQuery()` in this driver.',

machines/parse-native-query-result.js

@@ -17,16 +17,19 @@ module.exports = {
 
     queryType: {
       description: 'The type of query operation this raw result came from.',
-      extendedDescription: 'Either "select", "insert", "delete", or "update".  This determines how the provided raw result will be parsed/coerced.',
+      moreInfoUrl: 'https://github.com/node-machine/waterline-driver-interface#query-results',
+      extendedDescription:
+        'Either "select", "insert", "destroy", "update", "count", "sum", or "avg".  '+
+        'This determines how the provided raw result will be parsed/coerced.',
       required: true,
-      example: 'select',// (select|insert|delete|update)
+      example: 'select',// (select|insert|destroy|update|count|sum|avg)
     },
 
     nativeQueryResult: {
       description: 'The result data sent back from the the database as a result of a native query.',
       extendedDescription: 'Specifically, be sure to use the `result` property of the output report from a successful native query (i.e. don\'t include `meta`!)  The data provided will be coerced to a JSON-serializable value if it isn\'t one already (see [rttc.dehydrate()](https://github.com/node-machine/rttc#dehydratevalue-allownullfalse-dontstringifyfunctionsfalse)). That means any Date instances therein will be converted to timezone-agnostic ISO timestamp strings (i.e. JSON timestamps).',
       required: true,
-      example: '*'
+      example: '==='
     },
 
     meta:

machines/release-connection.js

@@ -49,6 +49,9 @@ module.exports = {
     // Release connection.
     try {
       inputs.connection.release();
+
+      // If we made it here, releasing the connection gracefully must have worked.
+      return exits.success();
     }
     catch (_releaseErr) {
       // If the connection cannot be released back to the pool gracefully,
@@ -62,13 +65,9 @@ module.exports = {
       }
 
       // Otherwise, forcing a disconnect worked:
-      console.warn('Could not release MySQL connection gracefully, but connection was forcibly destroyed.  Details:\n=== === ===\n'+_releaseErr.stack);
       return exits.success();
+      // console.warn('Could not release MySQL connection gracefully, but connection was forcibly destroyed.  Details:\n=== === ===\n'+_releaseErr.stack);
     }
-
-    // If we made it here, releasing the connection gracefully must have worked.
-    return exits.success();
-
   }
 
 

machines/send-native-query.js

@@ -37,7 +37,7 @@ module.exports = {
       outputDescription: 'The `result` property is the result data the database sent back.  The `meta` property is reserved for custom driver-specific extensions.',
       moreInfoUrl: 'https://github.com/felixge/node-mysql#getting-the-id-of-an-inserted-row',
       example: {
-        result: '*',
+        result: '===',
         meta: '==='
       }
     },

package.json

@@ -35,7 +35,9 @@
       "begin-transaction",
       "commit-transaction",
       "rollback-transaction",
-      "compile-statement"
+      "compile-statement",
+      "create-manager",
+      "destroy-manager"
     ],
     "interfaces": [
       "driveable",
@@ -47,4 +49,4 @@
     "type": "git",
     "url": "[email protected]:particlebanana/machinepack-mysql.git"
   }
-}
+}