Accept MySQL charset (like UTF8 or UTF8MB4) in charset option

closes #808

Author: dougwilson

Changes.md

@@ -6,6 +6,7 @@ you spot any mistakes.
 
 ## HEAD
 
+* Accept MySQL charset (like `UTF8` or `UTF8MB4`) in `charset` option #808
 * Clone connection config for new pool connections
 * Default `connectTimeout` to 2 minutes
 * Throw on unknown SSL profile name #817

Readme.md

@@ -141,7 +141,9 @@ When establishing a connection, you can set the following options:
 * `user`: The MySQL user to authenticate as.
 * `password`: The password of that MySQL user.
 * `database`: Name of the database to use for this connection (Optional).
-* `charset`: The charset for the connection. (Default: `'UTF8_GENERAL_CI'`)
+* `charset`: The charset for the connection. This is called "collation" in the SQL-level
+  of MySQL (like `utf8_general_ci`). If a SQL-level charset is specified (like `utf8mb4`)
+  then the default collation for that charset is used. (Default: `'UTF8_GENERAL_CI'`)
 * `timezone`: The timezone used to store local dates. (Default: `'local'`)
 * `connectTimeout`: The milliseconds before a timeout occurs during the initial connection
   to the MySQL server. (Default: 2 minutes)

lib/protocol/constants/charsets.js

@@ -218,3 +218,45 @@ exports.UTF8MB4_CROATIAN_MYSQL561_CI = 245;
 exports.UTF8MB4_UNICODE_520_CI       = 246;
 exports.UTF8MB4_VIETNAMESE_CI        = 247;
 exports.UTF8_GENERAL50_CI            = 253;
+
+// short aliases
+exports.ARMSCII8 = exports.ARMSCII8_GENERAL_CI;
+exports.ASCII    = exports.ASCII_GENERAL_CI;
+exports.BIG5     = exports.BIG5_CHINESE_CI;
+exports.BINARY   = exports.BINARY;
+exports.CP1250   = exports.CP1250_GENERAL_CI;
+exports.CP1251   = exports.CP1251_GENERAL_CI;
+exports.CP1256   = exports.CP1256_GENERAL_CI;
+exports.CP1257   = exports.CP1257_GENERAL_CI;
+exports.CP866    = exports.CP866_GENERAL_CI;
+exports.CP850    = exports.CP850_GENERAL_CI;
+exports.CP852    = exports.CP852_GENERAL_CI;
+exports.CP932    = exports.CP932_JAPANESE_CI;
+exports.DEC8     = exports.DEC8_SWEDISH_CI;
+exports.EUCJPMS  = exports.EUCJPMS_JAPANESE_CI;
+exports.EUCKR    = exports.EUCKR_KOREAN_CI;
+exports.GB2312   = exports.GB2312_CHINESE_CI;
+exports.GBK      = exports.GBK_CHINESE_CI;
+exports.GEOSTD8  = exports.GEOSTD8_GENERAL_CI;
+exports.GREEK    = exports.GREEK_GENERAL_CI;
+exports.HEBREW   = exports.HEBREW_GENERAL_CI;
+exports.HP8      = exports.HP8_ENGLISH_CI;
+exports.KEYBCS2  = exports.KEYBCS2_GENERAL_CI;
+exports.KOI8R    = exports.KOI8R_GENERAL_CI;
+exports.KOI8U    = exports.KOI8U_GENERAL_CI;
+exports.LATIN1   = exports.LATIN1_SWEDISH_CI;
+exports.LATIN2   = exports.LATIN2_GENERAL_CI;
+exports.LATIN5   = exports.LATIN5_TURKISH_CI;
+exports.LATIN7   = exports.LATIN7_GENERAL_CI;
+exports.MACCE    = exports.MACCE_GENERAL_CI;
+exports.MACROMAN = exports.MACROMAN_GENERAL_CI;
+exports.SJIS     = exports.SJIS_JAPANESE_CI;
+exports.SWE7     = exports.SWE7_SWEDISH_CI;
+exports.TIS620   = exports.TIS620_THAI_CI;
+exports.UCS2     = exports.UCS2_GENERAL_CI;
+exports.UJIS     = exports.UJIS_JAPANESE_CI;
+exports.UTF16    = exports.UTF16_GENERAL_CI;
+exports.UTF16LE  = exports.UTF16LE_GENERAL_CI;
+exports.UTF8     = exports.UTF8_GENERAL_CI;
+exports.UTF8MB4  = exports.UTF8MB4_GENERAL_CI;
+exports.UTF32    = exports.UTF32_GENERAL_CI;

test/unit/test-ConnectionConfig.js

@@ -26,15 +26,33 @@ test('ConnectionConfig#Constructor', {
     assert.equal(config.debug, true);
     assert.equal(config.charsetNumber, Charsets.BIG5_CHINESE_CI);
   },
+});
+
+test('ConnectionConfig#Constructor.charset', {
+  'accepts charset name': function() {
+    var config = new ConnectionConfig({
+      charset: 'LATIN1_SWEDISH_CI',
+    });
 
-  'allows case-insensitive charset name': function() {
+    assert.equal(config.charsetNumber, Charsets.LATIN1_SWEDISH_CI);
+  },
+
+  'accepts case-insensitive charset name': function() {
     var config = new ConnectionConfig({
       charset: 'big5_chinese_ci',
     });
 
     assert.equal(config.charsetNumber, Charsets.BIG5_CHINESE_CI);
   },
 
+  'accepts short charset name': function() {
+    var config = new ConnectionConfig({
+      charset: 'UTF8MB4',
+    });
+
+    assert.equal(config.charsetNumber, Charsets.UTF8MB4_GENERAL_CI);
+  },
+
   'throws on unknown charset': function() {
     var error;
 
@@ -50,6 +68,16 @@ test('ConnectionConfig#Constructor', {
     assert.equal(error.name, 'TypeError');
     assert.equal(error.message, 'Unknown charset \'INVALID_CHARSET\'');
   },
+
+  'all charsets should have short name': function() {
+    var charsets = Object.keys(Charsets);
+
+    for (var i = 0; i < charsets.length; i++) {
+      var charset = charsets[i];
+      assert.ok(Charsets[charset]);
+      assert.ok(Charsets[charset.split('_')[0]]);
+    }
+  },
 });
 
 test('ConnectionConfig#Constructor.connectTimeout', {