From 505e8480237dee769edff0fd8325d8df485b6a7d Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 13:14:39 +0100 Subject: [PATCH 01/14] Update 00-index.mdx --- website/docs/documentation/00-index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/00-index.mdx b/website/docs/documentation/00-index.mdx index b249a066a0..940d106d06 100644 --- a/website/docs/documentation/00-index.mdx +++ b/website/docs/documentation/00-index.mdx @@ -25,7 +25,7 @@ Not only **MySQL2** offers better performance over [Node MySQL][node-mysql], we - [More Features](/docs/documentation/extras) - [MySQL Server](/docs/documentation/mysql-server) - Pooling -- SSL +- [SSL](/docs/documentation/ssl) - MySQL Compression - Binary Log Protocol Client From 7a6404c356289c4c5587b51125e91528ad037ec5 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 13:26:00 +0100 Subject: [PATCH 02/14] Create ssl.mdx --- website/docs/documentation/ssl.mdx | 31 ++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 website/docs/documentation/ssl.mdx diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx new file mode 100644 index 0000000000..47d87b57b0 --- /dev/null +++ b/website/docs/documentation/ssl.mdx @@ -0,0 +1,31 @@ +# SSL + +As part of the connection options one can specify an object with ssl parameters or a string containing name of ssl profile. + +## SSL Options + +When connecting to other servers, you will need to provide an object of options, in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). Please note the arguments expect a string of the certificate, not a file name to the certificate. Here is a simple example: + +```js +const connection = mysql.createConnection({ + host : 'localhost', + ssl : { + ca : fs.readFileSync(__dirname + '/mysql-ca.crt') + } +}); +``` + +You can also connect to a MySQL server without properly providing an appropriate CA to trust. **This is highly not recommended.** + +```js +const connection = mysql.createConnection({ + host : 'localhost', + ssl : { + // DO NOT DO THIS + // set up your ca correctly to trust the connection + rejectUnauthorized: false + } +}); +``` + +## SSL Profile From 8a2fa96546c1c3584a3709e51dd97a20e33fa22d Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 13:29:46 +0100 Subject: [PATCH 03/14] Update ssl.mdx --- website/docs/documentation/ssl.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 47d87b57b0..f35225344f 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -2,11 +2,17 @@ As part of the connection options one can specify an object with ssl parameters or a string containing name of ssl profile. +```ts +ssl?: string | SslOptions; +``` + +See full list of [SslOptions](../../typings/mysql/lib/Connection.d.ts) + ## SSL Options When connecting to other servers, you will need to provide an object of options, in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). Please note the arguments expect a string of the certificate, not a file name to the certificate. Here is a simple example: -```js +```ts const connection = mysql.createConnection({ host : 'localhost', ssl : { @@ -17,7 +23,7 @@ const connection = mysql.createConnection({ You can also connect to a MySQL server without properly providing an appropriate CA to trust. **This is highly not recommended.** -```js +```ts const connection = mysql.createConnection({ host : 'localhost', ssl : { From 84dcbdfc4c525c2068e73a7ab4fbec14ae66a5d8 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 13:46:17 +0100 Subject: [PATCH 04/14] Update ssl.mdx --- website/docs/documentation/ssl.mdx | 53 ++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index f35225344f..9563cef6d2 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -1,32 +1,52 @@ # SSL -As part of the connection options one can specify an object with ssl parameters or a string containing name of ssl profile. +As part of the connection options one can specify an object with ssl parameters or a string containing name of SSL profile. ```ts ssl?: string | SslOptions; ``` -See full list of [SslOptions](../../typings/mysql/lib/Connection.d.ts) +See full list of [SslOptions](../../typings/mysql/lib/Connection.d.ts), which are in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). ## SSL Options -When connecting to other servers, you will need to provide an object of options, in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). Please note the arguments expect a string of the certificate, not a file name to the certificate. Here is a simple example: +To enable SSL without manually providing certificates and assuming they are already trusted by the host machine, you can specify empty object: ```ts const connection = mysql.createConnection({ - host : 'localhost', - ssl : { - ca : fs.readFileSync(__dirname + '/mysql-ca.crt') + host: 'localhost', + ssl: {} +}); +``` + +You can also specify custom certificate(s) as an individual string or array of strings. Please note the arguments expect a string of the certificate, not a file name to the certificate: + +```ts +const connection = mysql.createConnection({ + host: 'localhost', + ssl: { + ca: fs.readFileSync(__dirname + '/mysql-ca.crt') } }); ``` -You can also connect to a MySQL server without properly providing an appropriate CA to trust. **This is highly not recommended.** +When cerificate is read from environment variable, you might need to replace escaped `\n` characters with proper new line characters: ```ts const connection = mysql.createConnection({ - host : 'localhost', - ssl : { + host: 'localhost', + ssl: { + ca: process.env.DB_SSL_CA?.replace(/\\n/gm, '\n') + } +}); +``` + +You can also connect to a MySQL server without properly providing an appropriate CA to trust. **This is highly discouraged** as being insecure. + +```ts +const connection = mysql.createConnection({ + host: 'localhost', + ssl: { // DO NOT DO THIS // set up your ca correctly to trust the connection rejectUnauthorized: false @@ -34,4 +54,17 @@ const connection = mysql.createConnection({ }); ``` -## SSL Profile +## SSL Profile (deprecated) + +Alternativelly you can also specify a string containing name of SSL profile: + +```ts +const connection = mysql.createConnection({ + host: 'localhost', + ssl: 'Amazon RDS' +}); +``` + +Following profiles are included in the package: + +* `Amazon RDS` - contains certificates from https://rds.amazonaws.com/doc/rds-ssl-ca-cert.pem and https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem From 0add7d6ebdfbaf2279f6d25fa9b389808423b813 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 13:47:17 +0100 Subject: [PATCH 05/14] Update ssl.mdx --- website/docs/documentation/ssl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 9563cef6d2..b953a6fd06 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -6,7 +6,7 @@ As part of the connection options one can specify an object with ssl parameters ssl?: string | SslOptions; ``` -See full list of [SslOptions](../../typings/mysql/lib/Connection.d.ts), which are in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). +See full list of [SslOptions](../../../typings/mysql/lib/Connection.d.ts), which are in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). ## SSL Options From 03f2c7d1992e684f238c86bf740d11e04aa9c8ae Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:23:35 +0100 Subject: [PATCH 06/14] add default cert example --- .../connections/create-connection.mdx | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/website/docs/examples/connections/create-connection.mdx b/website/docs/examples/connections/create-connection.mdx index b8b0c51367..9f6a3a6f71 100644 --- a/website/docs/examples/connections/create-connection.mdx +++ b/website/docs/examples/connections/create-connection.mdx @@ -160,6 +160,49 @@ connection.addListener('error', (err) => { ```js import mysql from 'mysql2/promise'; +try { + // highlight-start + const connection = await mysql.createConnection({ + // ... + ssl: {}, + }); + // highlight-end +} catch (err) { + console.log(err); +} +``` + + + + +```js +const mysql = require('mysql2'); + +const connection = mysql.createConnection({ + // ... + ssl: {}, +}); + +connection.addListener('error', (err) => { + console.log(err); +}); +``` + + + + +
+ +## createConnection(config) — SSL Custom Certificate + +> **createConnection(config: [ConnectionOptions](#connectionoptions))** + + + + +```js +import mysql from 'mysql2/promise'; + try { // highlight-start const connection = await mysql.createConnection({ From 3dc5a4862e42a1655d30b2513c66af579503f675 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:32:54 +0100 Subject: [PATCH 07/14] Update website/docs/documentation/ssl.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com> --- website/docs/documentation/ssl.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index b953a6fd06..2bb7e11b67 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -22,6 +22,8 @@ const connection = mysql.createConnection({ You can also specify custom certificate(s) as an individual string or array of strings. Please note the arguments expect a string of the certificate, not a file name to the certificate: ```ts +const fs = require('node:fs'); + const connection = mysql.createConnection({ host: 'localhost', ssl: { From 0f135769ae7a33c5a37a7223a6142ed05f728874 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:33:11 +0100 Subject: [PATCH 08/14] Update website/docs/documentation/ssl.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com> --- website/docs/documentation/ssl.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 2bb7e11b67..19fc8db19f 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -49,8 +49,7 @@ You can also connect to a MySQL server without properly providing an appropriate const connection = mysql.createConnection({ host: 'localhost', ssl: { - // DO NOT DO THIS - // set up your ca correctly to trust the connection + // Beware, set `rejectUnauthorized` as `false` is strongly discouraged for security reasons: rejectUnauthorized: false } }); From b927a0c1ddb619b6cbe30dded4e1dc357cc20382 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:33:32 +0100 Subject: [PATCH 09/14] Update website/docs/documentation/ssl.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com> --- website/docs/documentation/ssl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 19fc8db19f..79cba4b6a7 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -1,6 +1,6 @@ # SSL -As part of the connection options one can specify an object with ssl parameters or a string containing name of SSL profile. +As part of the connection options, you can specify the `ssl` object property or a string containing the SSL profile content. ```ts ssl?: string | SslOptions; From 06dd09a4d0e9fb68624f8cd7ec424aa85ceb02b5 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:33:55 +0100 Subject: [PATCH 10/14] Update website/docs/documentation/ssl.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com> --- website/docs/documentation/ssl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 79cba4b6a7..1bcb0b4aad 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -10,7 +10,7 @@ See full list of [SslOptions](../../../typings/mysql/lib/Connection.d.ts), which ## SSL Options -To enable SSL without manually providing certificates and assuming they are already trusted by the host machine, you can specify empty object: +To enable SSL without manually providing certificates and assuming they are already trusted by the host machine, you can specify an empty object, for example: ```ts const connection = mysql.createConnection({ From bc1e869537be7bbb1ec676f77c4bee9ff6d9be88 Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:34:03 +0100 Subject: [PATCH 11/14] Update website/docs/documentation/ssl.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com> --- website/docs/documentation/ssl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 1bcb0b4aad..aee23c2568 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -32,7 +32,7 @@ const connection = mysql.createConnection({ }); ``` -When cerificate is read from environment variable, you might need to replace escaped `\n` characters with proper new line characters: +When a certificate is read from an environment variable, it's recommended to replace escaped `\n` characters with proper new line characters, for example: ```ts const connection = mysql.createConnection({ From 2fb93e318653bcb98b2cc339814a49f17ff6b50d Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:34:19 +0100 Subject: [PATCH 12/14] some changes --- website/docs/documentation/ssl.mdx | 59 +++++++++++++++++++----------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index b953a6fd06..b5a8c18230 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -1,6 +1,6 @@ # SSL -As part of the connection options one can specify an object with ssl parameters or a string containing name of SSL profile. +As part of the connection options one can specify an object with ssl parameters or a string containing name of SSL profile (__deprecated__). ```ts ssl?: string | SslOptions; @@ -13,58 +13,75 @@ See full list of [SslOptions](../../../typings/mysql/lib/Connection.d.ts), which To enable SSL without manually providing certificates and assuming they are already trusted by the host machine, you can specify empty object: ```ts -const connection = mysql.createConnection({ +const connection = await mysql.createConnection({ host: 'localhost', ssl: {} -}); +}) ``` You can also specify custom certificate(s) as an individual string or array of strings. Please note the arguments expect a string of the certificate, not a file name to the certificate: ```ts -const connection = mysql.createConnection({ +const connection = await mysql.createConnection({ host: 'localhost', ssl: { ca: fs.readFileSync(__dirname + '/mysql-ca.crt') } -}); +}) ``` -When cerificate is read from environment variable, you might need to replace escaped `\n` characters with proper new line characters: +When certificate is read from environment variable, you might need to replace escaped `\n` characters with proper new line characters: ```ts -const connection = mysql.createConnection({ +const connection = await mysql.createConnection({ host: 'localhost', ssl: { ca: process.env.DB_SSL_CA?.replace(/\\n/gm, '\n') } -}); +}) ``` -You can also connect to a MySQL server without properly providing an appropriate CA to trust. **This is highly discouraged** as being insecure. +## SSL Certificate Bundle + +Alternatively, you can use a bundle with CA certificates. For example for Amazon RDS you could use: ```ts -const connection = mysql.createConnection({ - host: 'localhost', - ssl: { - // DO NOT DO THIS - // set up your ca correctly to trust the connection - rejectUnauthorized: false - } -}); +import awsCaBundle from 'aws-ssl-profiles'; + +const connection = await mysql.createConnection({ + host: 'db.id.ap-southeast-2.rds.amazonaws.com', + ssl: awsCaBundle, +}) ``` +For detailed instructions, please follow [aws-ssl-profiles](https://github.com/mysqljs/aws-ssl-profiles) documentation. + ## SSL Profile (deprecated) -Alternativelly you can also specify a string containing name of SSL profile: +There is also a **deprecated option** allowing to specify a string containing name of SSL profile: ```ts -const connection = mysql.createConnection({ +const connection = await mysql.createConnection({ host: 'localhost', ssl: 'Amazon RDS' -}); +}) ``` Following profiles are included in the package: -* `Amazon RDS` - contains certificates from https://rds.amazonaws.com/doc/rds-ssl-ca-cert.pem and https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem +* `Amazon RDS` - in this case https://s3.amazonaws.com/rds-downloads/mysql-ssl-ca-cert.pem CA cert is used + +## Ignoring Unauthorized SSL Errors + +You can also connect to a MySQL server without providing an appropriate CA to trust. **This is highly discouraged** as being insecure. + +```ts +const connection = await mysql.createConnection({ + host: 'localhost', + ssl: { + // DO NOT DO THIS + // set up your ca correctly to trust the connection + rejectUnauthorized: false + } +}) +``` From 0650077e60485a40e6d75768197a946469f06aeb Mon Sep 17 00:00:00 2001 From: Piotr Kuczynski Date: Thu, 6 Feb 2025 15:37:15 +0100 Subject: [PATCH 13/14] lint --- website/docs/documentation/ssl.mdx | 34 +++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index 990b2c7861..d4ced11a84 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -1,6 +1,6 @@ # SSL -As part of the connection options, you can specify the `ssl` object property or a string containing the SSL profile content (__deprecated__). +As part of the connection options, you can specify the `ssl` object property or a string containing the SSL profile content (**deprecated**). ```ts ssl?: string | SslOptions; @@ -15,21 +15,21 @@ To enable SSL without manually providing certificates and assuming they are alre ```ts const connection = await mysql.createConnection({ host: 'localhost', - ssl: {} -}) + ssl: {}, +}); ``` You can also specify custom certificate(s) as an individual string or array of strings. Please note the arguments expect a string of the certificate, not a file name to the certificate: ```ts -import fs from 'node:fs' +import fs from 'node:fs'; const connection = await mysql.createConnection({ host: 'localhost', ssl: { - ca: fs.readFileSync(__dirname + '/mysql-ca.crt') - } -}) + ca: fs.readFileSync(__dirname + '/mysql-ca.crt'), + }, +}); ``` When a certificate is read from an environment variable, it's recommended to replace escaped `\n` characters with proper new line characters, for example: @@ -38,9 +38,9 @@ When a certificate is read from an environment variable, it's recommended to rep const connection = await mysql.createConnection({ host: 'localhost', ssl: { - ca: process.env.DB_SSL_CA?.replace(/\\n/gm, '\n') - } -}) + ca: process.env.DB_SSL_CA?.replace(/\\n/gm, '\n'), + }, +}); ``` ## SSL Certificate Bundle @@ -53,7 +53,7 @@ import awsCaBundle from 'aws-ssl-profiles'; const connection = await mysql.createConnection({ host: 'db.id.ap-southeast-2.rds.amazonaws.com', ssl: awsCaBundle, -}) +}); ``` For detailed instructions, please follow [aws-ssl-profiles](https://github.com/mysqljs/aws-ssl-profiles) documentation. @@ -65,13 +65,13 @@ There is also a **deprecated option** allowing to specify a string containing na ```ts const connection = await mysql.createConnection({ host: 'localhost', - ssl: 'Amazon RDS' -}) + ssl: 'Amazon RDS', +}); ``` Following profiles are included in the package: -* `Amazon RDS` - in this case https://s3.amazonaws.com/rds-downloads/mysql-ssl-ca-cert.pem CA cert is used +- `Amazon RDS` - in this case https://s3.amazonaws.com/rds-downloads/mysql-ssl-ca-cert.pem CA cert is used ## Ignoring Unauthorized SSL Errors @@ -82,7 +82,7 @@ const connection = await mysql.createConnection({ host: 'localhost', ssl: { // Beware, set `rejectUnauthorized` as `false` is strongly discouraged for security reasons: - rejectUnauthorized: false - } -}) + rejectUnauthorized: false, + }, +}); ``` From fb982045743ca53fbc6c74cd91223634b1fab41d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Weslley=20Ara=C3=BAjo?= <46850407+wellwelwel@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:36:23 -0300 Subject: [PATCH 14/14] Update website/docs/documentation/ssl.mdx --- website/docs/documentation/ssl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx index d4ced11a84..59f6b07fa9 100644 --- a/website/docs/documentation/ssl.mdx +++ b/website/docs/documentation/ssl.mdx @@ -6,7 +6,7 @@ As part of the connection options, you can specify the `ssl` object property or ssl?: string | SslOptions; ``` -See full list of [SslOptions](../../../typings/mysql/lib/Connection.d.ts), which are in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). +See full list of [SslOptions](https://github.com/sidorares/node-mysql2/blob/master/typings/mysql/lib/Connection.d.ts#L24-L80), which are in the same format as [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). ## SSL Options