Add connection examples

.npmignore

@@ -6,3 +6,4 @@ test
 .vscode
 .nyc_output
 coverage
+examples

README.md

@@ -29,7 +29,7 @@ A Bluebird `Promise` that resolves to a [pool](#pool) object
 
 In addition to the [connection options in mysqljs/mysql](https://github.com/mysqljs/mysql#connection-options), promise-mysql accepts the following:
 
-`returnArgumentsArray` _boolean_: If set to true then methods will return an array with the return value and the callback arguments from the underlying method.
+`returnArgumentsArray` _boolean_: If set to true then methods will return an array with the callback arguments from the underlying method (excluding the any errors) and the return value from the call.
 
 `mysqlWrapper` _function_: A function that is passed the `mysql` object so that it can be wrapped with something like the [aws-xray-sdk module](https://www.npmjs.com/package/aws-xray-sdk). This function must either return the wrapped `mysql` object, return a promise of the wrapped `mysql` object or call the callback that is passed into the function.
 

examples/README.md

@@ -0,0 +1,10 @@
+Examples
+==================
+
+These examples run against the [test_db](https://github.com/datacharmer/test_db) dataset. It expects the database to be named `employees` and expects the root password to be `password`.
+
+To run a docker container with this data and bound to the correct port, you can run the following:
+
+```
+docker run -p 3306:3306 --name mysql_container -e MYSQL_ROOT_PASSWORD=password -d genschsa/mysql-employees
+```

examples/connection/mysqlWrapper.js

@@ -0,0 +1,60 @@
+const mysql = require('../../index.js');
+const bluebird = require('bluebird');
+
+async function runReturn() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance) => {
+            return wrapMysql(mysqlInstance, 'runReturn');
+        }
+    });
+
+    connection.end();
+}
+
+async function runPromise() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance) => {
+            return bluebird.resolve(wrapMysql(mysqlInstance, 'runPromise'));
+        }
+    });
+
+    connection.end();
+}
+
+async function runCallback() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance, callback) => {
+            callback(null, wrapMysql(mysqlInstance, 'runCallback'));
+        }
+    });
+
+    connection.end();
+}
+
+runReturn();
+runPromise();
+runCallback();
+
+
+function wrapMysql(mysql, fnName) {
+    const createConnection = mysql.createConnection;
+
+    mysql.createConnection = function () {
+        console.log(`createConnection called in ${fnName}!`);
+
+        mysql.createConnection = createConnection;
+
+        return createConnection(...arguments);
+    }
+
+    return mysql;
+}

examples/connection/query.js

@@ -0,0 +1,40 @@
+const mysql = require('../../index.js');
+
+function run() {
+    let connection;
+
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    }).then((conn) => {
+        connection = conn;
+
+        return connection.query('select * from employees limit 0, 10');
+    }).then((employees) => {
+        employees.forEach(employee => {
+            console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+        });
+
+        connection.end();
+    });
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    });
+
+    const employees = await connection.query('select * from employees limit 0, 10');
+
+    employees.forEach(employee => {
+        console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+    });
+
+    connection.end();
+}
+
+run();
+runAwait();

examples/connection/querystream.js

@@ -0,0 +1,40 @@
+const mysql = require('../../index.js');
+
+function run() {
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    }).then((connection) => {
+        const employees = connection.queryStream('select * from employees limit 0, 10');
+
+        employees.on('result', (employee) => {
+            console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+        });
+
+        employees.on('end', () => {
+            connection.end();
+        })
+    });
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    });
+
+    const employees = connection.queryStream('select * from employees limit 0, 10');
+
+    employees.on('result', (employee) => {
+        console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+    });
+
+    employees.on('end', () => {
+        connection.end();
+    })
+}
+
+run();
+runAwait();

examples/connection/returnArgumentsArray.js

@@ -0,0 +1,60 @@
+const mysql = require('../../index.js');
+
+function run() {
+    let connection;
+
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        returnArgumentsArray: true
+    }).then((conn) => {
+        connection = conn;
+
+        return connection.query('select * from employees limit 0, 10');
+    }).then(([data, fields, query]) => {
+        console.log(`The SQL for the query was: ${query.sql}\n`);
+
+        console.log(`The table 'employees' contains the following fields:`)
+        fields.forEach(field => {
+            console.log(`    ${field.name}`);
+        })
+
+        console.log('\nThe data retrieved was:')
+
+        data.forEach(employee => {
+            console.log(`    Employee number ${employee.emp_no}: ${employee.first_name} ${employee.last_name}`);
+        });
+
+        connection.end();
+    });
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        returnArgumentsArray: true
+    });
+
+    const [data, fields, query] = await connection.query('select * from employees limit 0, 10');
+
+    console.log(`The SQL for the query was: ${query.sql}\n`);
+
+    console.log(`The table 'employees' contains the following fields:`)
+    fields.forEach(field => {
+        console.log(`    ${field.name}`);
+    })
+
+    console.log('\nThe data retrieved was:')
+
+    data.forEach(employee => {
+        console.log(`    Employee number ${employee.emp_no}: ${employee.first_name} ${employee.last_name}`);
+    });
+
+    connection.end();
+}
+
+run();
+runAwait();