From 08dbc53f3b78049848f8e1710c856fa02d6bd2b1 Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 10:56:05 +0100 Subject: [PATCH 1/7] Remove space in anonymous functions There are more instances of `function()` than `function ()`. This commit makes them consistently the former. --- Readme.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/Readme.md b/Readme.md index cf85d8e1e..9de7c30d4 100644 --- a/Readme.md +++ b/Readme.md @@ -394,7 +394,7 @@ If you need to set session variables on the connection before it gets used, you listen to the `connection` event. ```js -pool.on('connection', function (connection) { +pool.on('connection', function(connection) { connection.query('SET SESSION auto_increment_increment=1') }); ``` @@ -405,7 +405,7 @@ The pool will emit an `enqueue` event when a callback has been queued to wait fo an available connection. ```js -pool.on('enqueue', function () { +pool.on('enqueue', function() { console.log('Waiting for available connection slot'); }); ``` @@ -419,7 +419,7 @@ trying to gracefully shutdown a server. To end all the connections in the pool, use the `end` method on the pool: ```js -pool.end(function (err) { +pool.end(function(err) { // all connections in the pool have ended }); ``` @@ -450,28 +450,28 @@ poolCluster.remove('SLAVE2'); // By nodeId poolCluster.remove('SLAVE*'); // By target group : SLAVE1-2 // Target Group : ALL(anonymous, MASTER, SLAVE1-2), Selector : round-robin(default) -poolCluster.getConnection(function (err, connection) {}); +poolCluster.getConnection(function(err, connection) {}); // Target Group : MASTER, Selector : round-robin -poolCluster.getConnection('MASTER', function (err, connection) {}); +poolCluster.getConnection('MASTER', function(err, connection) {}); // Target Group : SLAVE1-2, Selector : order // If can't connect to SLAVE1, return SLAVE2. (remove SLAVE1 in the cluster) -poolCluster.on('remove', function (nodeId) { - console.log('REMOVED NODE : ' + nodeId); // nodeId = SLAVE1 +poolCluster.on('remove', function(nodeId) { + console.log('REMOVED NODE : ' + nodeId); // nodeId = SLAVE1 }); -poolCluster.getConnection('SLAVE*', 'ORDER', function (err, connection) {}); +poolCluster.getConnection('SLAVE*', 'ORDER', function(err, connection) {}); // of namespace : of(pattern, selector) -poolCluster.of('*').getConnection(function (err, connection) {}); +poolCluster.of('*').getConnection(function(err, connection) {}); var pool = poolCluster.of('SLAVE*', 'RANDOM'); -pool.getConnection(function (err, connection) {}); -pool.getConnection(function (err, connection) {}); +pool.getConnection(function(err, connection) {}); +pool.getConnection(function(err, connection) {}); // close all connections -poolCluster.end(function (err) { +poolCluster.end(function(err) { // all connections in the pool cluster have ended }); ``` @@ -545,7 +545,7 @@ The simplest form on query comes as `.query(sqlString, callback)`, where a strin of a MySQL query is the first argument and the second is a callback: ```js -connection.query('SELECT * FROM `books` WHERE `author` = "David"', function (error, results, fields) { +connection.query('SELECT * FROM `books` WHERE `author` = "David"', function(error, results, fields) { // error will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) @@ -556,7 +556,7 @@ The second form `.query(sqlString, parameters, callback)` comes when using placeholders (see [escaping query values](#escaping-query-values)): ```js -connection.query('SELECT * FROM `books` WHERE `author` = ?', ['David'], function (error, results, fields) { +connection.query('SELECT * FROM `books` WHERE `author` = ?', ['David'], function(error, results, fields) { // error will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) @@ -573,7 +573,7 @@ connection.query({ sql: 'SELECT * FROM `books` WHERE `author` = ?', timeout: 40000, // 40s values: ['David'] -}, function (error, results, fields) { +}, function(error, results, fields) { // error will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) @@ -708,9 +708,9 @@ If you prefer to have another type of query escape format, there's a connection Here's an example of how to implement another format: ```js -connection.config.queryFormat = function (query, values) { +connection.config.queryFormat = function(query, values) { if (!values) return query; - return query.replace(/\:(\w+)/g, function (txt, key) { + return query.replace(/\:(\w+)/g, function(txt, key) { if (values.hasOwnProperty(key)) { return this.escape(values[key]); } @@ -746,7 +746,7 @@ you will get values rounded to hundreds or thousands due to the precision limit. You can get the number of affected rows from an insert, update or delete statement. ```js -connection.query('DELETE FROM posts WHERE title = "wrong"', function (err, result) { +connection.query('DELETE FROM posts WHERE title = "wrong"', function(err, result) { if (err) throw err; console.log('deleted ' + result.affectedRows + ' rows'); @@ -761,7 +761,7 @@ You can get the number of changed rows from an update statement. whose values were not changed. ```js -connection.query('UPDATE posts SET ...', function (err, result) { +connection.query('UPDATE posts SET ...', function(err, result) { if (err) throw err; console.log('changed ' + result.changedRows + ' rows'); @@ -996,7 +996,7 @@ method will send a ping packet to the server and when the server responds, the c will fire. If an error occurred, the callback will fire with an error argument. ```js -connection.ping(function (err) { +connection.ping(function(err) { if (err) throw err; console.log('Server responded to ping'); }) @@ -1012,7 +1012,7 @@ on will be destroyed and no further operations can be performed. ```js // Kill query after 60s -connection.query({sql: 'SELECT COUNT(*) AS count FROM big_table', timeout: 60000}, function (err, rows) { +connection.query({sql: 'SELECT COUNT(*) AS count FROM big_table', timeout: 60000}, function(err, rows) { if (err && err.code === 'PROTOCOL_SEQUENCE_TIMEOUT') { throw new Error('too long to count table rows!'); } @@ -1178,7 +1178,7 @@ fallback to the default. Here's an example of converting `TINYINT(1)` to boolean ```js connection.query({ sql: '...', - typeCast: function (field, next) { + typeCast: function(field, next) { if (field.type == 'TINY' && field.length == 1) { return (field.string() == '1'); // 1 = true, 0 = false } From 0ca9b90f2d7aa492c3ed9aac0113ba5d0792d529 Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 10:56:58 +0100 Subject: [PATCH 2/7] Remove trailing whitespace --- Readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Readme.md b/Readme.md index 9de7c30d4..1b53258b8 100644 --- a/Readme.md +++ b/Readme.md @@ -389,7 +389,7 @@ addition to those options pools accept a few extras: ### connection -The pool will emit a `connection` event when a new connection is made within the pool. +The pool will emit a `connection` event when a new connection is made within the pool. If you need to set session variables on the connection before it gets used, you can listen to the `connection` event. @@ -478,7 +478,7 @@ poolCluster.end(function(err) { ## PoolCluster Option * `canRetry`: If `true`, `PoolCluster` will attempt to reconnect when connection fails. (Default: `true`) -* `removeNodeErrorCount`: If connection fails, node's `errorCount` increases. +* `removeNodeErrorCount`: If connection fails, node's `errorCount` increases. When `errorCount` is greater than `removeNodeErrorCount`, remove a node in the `PoolCluster`. (Default: `5`) * `restoreNodeTimeout`: If connection fails, specifies the number of milliseconds before another connection attempt will be made. If set to `0`, then node will bd @@ -958,7 +958,7 @@ Simple transaction support is available at the connection level: connection.beginTransaction(function(err) { if (err) { throw err; } connection.query('INSERT INTO posts SET title=?', title, function(err, result) { - if (err) { + if (err) { connection.rollback(function() { throw err; }); From 81f0c5c66d75db3b492354ff1ef0600223581581 Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 11:13:22 +0100 Subject: [PATCH 3/7] Use spaces for indentation and space out code for readability --- Readme.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/Readme.md b/Readme.md index 1b53258b8..8b88ed9a5 100644 --- a/Readme.md +++ b/Readme.md @@ -956,30 +956,38 @@ Simple transaction support is available at the connection level: ```js connection.beginTransaction(function(err) { + if (err) { throw err; } + connection.query('INSERT INTO posts SET title=?', title, function(err, result) { + if (err) { connection.rollback(function() { throw err; }); } - var log = 'Post ' + result.insertId + ' added'; + var log = 'Post ' + result.insertId + ' added'; - connection.query('INSERT INTO log SET data=?', log, function(err, result) { - if (err) { + connection.query('INSERT INTO log SET data=?', log, function(err, result) { + + if (err) { connection.rollback(function() { throw err; }); - } - connection.commit(function(err) { - if (err) { + }; + + connection.commit(function(err) { + + if (err) { connection.rollback(function() { throw err; }); } - console.log('success!'); - }); + + console.log('success!'); + + }); }); }); }); From 7853b71fe2ce5eb5635a79853f04ae95e1dac76b Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 11:23:09 +0100 Subject: [PATCH 4/7] Reword 'Performing queries' Less to read is generally easier to understand. --- Readme.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Readme.md b/Readme.md index 8b88ed9a5..d8d730bd7 100644 --- a/Readme.md +++ b/Readme.md @@ -537,12 +537,11 @@ space for a new connection to be created on the next getConnection call. ## Performing queries -In the MySQL library library, the most basic way to perform a query is to call -the `.query()` method on an object (like on a `Connection`, `Pool`, `PoolNamespace` -or other similar objects). +The most basic way to perform a query is to call the `.query()` method on an object +(like on a `Connection`, `Pool`, `PoolNamespace` or other similar objects). -The simplest form on query comes as `.query(sqlString, callback)`, where a string -of a MySQL query is the first argument and the second is a callback: +The simplest form of .`query()` is `.query(sqlString, callback)`, where a SQL string +is the first argument and the second is a callback: ```js connection.query('SELECT * FROM `books` WHERE `author` = "David"', function(error, results, fields) { From 1eb61637742a568b0c91bdbeb67e4755bb7ae4fe Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 11:26:57 +0100 Subject: [PATCH 5/7] Rename 'parameters' argument to 'values' The options object field is named 'values', referring to it as 'parameters' when passed as an argument might lead to confusion. --- Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Readme.md b/Readme.md index d8d730bd7..21580587e 100644 --- a/Readme.md +++ b/Readme.md @@ -551,8 +551,8 @@ connection.query('SELECT * FROM `books` WHERE `author` = "David"', function(erro }); ``` -The second form `.query(sqlString, parameters, callback)` comes when using -placeholders (see [escaping query values](#escaping-query-values)): +The second form `.query(sqlString, values, callback)` comes when using +placeholder values (see [escaping query values](#escaping-query-values)): ```js connection.query('SELECT * FROM `books` WHERE `author` = ?', ['David'], function(error, results, fields) { From 8b2ceaf40666a82ae7f012c4b0ea4c349b58b822 Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 11:29:19 +0100 Subject: [PATCH 6/7] Use err over error The majority of code examples use `err` instead of `error`. This commit makes it consistent across the readme. --- Readme.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Readme.md b/Readme.md index 21580587e..a5e89b32b 100644 --- a/Readme.md +++ b/Readme.md @@ -544,8 +544,8 @@ The simplest form of .`query()` is `.query(sqlString, callback)`, where a SQL st is the first argument and the second is a callback: ```js -connection.query('SELECT * FROM `books` WHERE `author` = "David"', function(error, results, fields) { - // error will be an Error if one occurred during the query +connection.query('SELECT * FROM `books` WHERE `author` = "David"', function(err, results, fields) { + // err will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) }); @@ -555,8 +555,8 @@ The second form `.query(sqlString, values, callback)` comes when using placeholder values (see [escaping query values](#escaping-query-values)): ```js -connection.query('SELECT * FROM `books` WHERE `author` = ?', ['David'], function(error, results, fields) { - // error will be an Error if one occurred during the query +connection.query('SELECT * FROM `books` WHERE `author` = ?', ['David'], function(err, results, fields) { + // err will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) }); @@ -572,8 +572,8 @@ connection.query({ sql: 'SELECT * FROM `books` WHERE `author` = ?', timeout: 40000, // 40s values: ['David'] -}, function(error, results, fields) { - // error will be an Error if one occurred during the query +}, function(err, results, fields) { + // err will be an Error if one occurred during the query // results will contain the results of the query // fields will contain information about the returned results fields (if any) }); From 37539db0856f685426c37bc0e874860be0f0a357 Mon Sep 17 00:00:00 2001 From: Adrian Lynch Date: Tue, 7 Apr 2015 11:38:32 +0100 Subject: [PATCH 7/7] Add fourth form of performing a query This is likely a less used form but still works. I'm unsure of the code formatting but it does make the values array stand out from the options object. --- Readme.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Readme.md b/Readme.md index a5e89b32b..e51058b63 100644 --- a/Readme.md +++ b/Readme.md @@ -579,6 +579,23 @@ connection.query({ }); ``` +Note that a combination of the second and third forms can be used where the +placeholder values are passes as an argument and not in the options object. + +```js +connection.query({ + sql: 'SELECT * FROM `books` WHERE `author` = ?', + timeout: 40000, // 40s + }, + ['David'], + function(err, results, fields) { + // err will be an Error if one occurred during the query + // results will contain the results of the query + // fields will contain information about the returned results fields (if any) + } +); +``` + ## Escaping query values In order to avoid SQL Injection attacks, you should always escape any user