docs: document SSL options (#3384)

* Update 00-index.mdx * Create ssl.mdx * Update ssl.mdx * Update ssl.mdx * Update ssl.mdx * add default cert example * Update website/docs/documentation/ssl.mdx Co-authored-by: Weslley Araújo <[email protected]> * Update website/docs/documentation/ssl.mdx Co-authored-by: Weslley Araújo <[email protected]> * Update website/docs/documentation/ssl.mdx Co-authored-by: Weslley Araújo <[email protected]> * Update website/docs/documentation/ssl.mdx Co-authored-by: Weslley Araújo <[email protected]> * Update website/docs/documentation/ssl.mdx Co-authored-by: Weslley Araújo <[email protected]> * some changes * lint * Update website/docs/documentation/ssl.mdx --------- Co-authored-by: Weslley Araújo <[email protected]>
sidorares · Feb 6, 2025 · a446fac · a446fac · sidorares · Feb 9, 2025
1 parent 37e4e74
commit a446fac
Show file tree

Hide file tree

Showing 3 changed files with 132 additions and 1 deletion.
diff --git 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
 

diff --git a/website/docs/documentation/ssl.mdx b/website/docs/documentation/ssl.mdx
@@ -0,0 +1,88 @@
+# SSL
+
+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;
+```
+
+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
+
+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 = 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
+import fs from 'node:fs';
+
+const connection = await mysql.createConnection({
+  host: 'localhost',
+  ssl: {
+    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:
+
+```ts
+const connection = await mysql.createConnection({
+  host: 'localhost',
+  ssl: {
+    ca: process.env.DB_SSL_CA?.replace(/\\n/gm, '\n'),
+  },
+});
+```
+
+## SSL Certificate Bundle
+
+Alternatively, you can use a bundle with CA certificates. For example for Amazon RDS you could use:
+
+```ts
+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)
+
+There is also a **deprecated option** allowing to specify a string containing name of SSL profile:
+
+```ts
+const connection = await mysql.createConnection({
+  host: 'localhost',
+  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
+
+## 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: {
+    // Beware, set `rejectUnauthorized` as `false` is strongly discouraged for security reasons:
+    rejectUnauthorized: false,
+  },
+});
+```
diff --git 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);
+}
+```
+
+  </TabItem>
+  <TabItem value='callback.js'>
+
+```js
+const mysql = require('mysql2');
+
+const connection = mysql.createConnection({
+  // ...
+  ssl: {},
+});
+
+connection.addListener('error', (err) => {
+  console.log(err);
+});
+```
+
+  </TabItem>
+</Tabs>
+
+<hr />
+
+## createConnection(config) — SSL Custom Certificate
+
+> **createConnection(config: [ConnectionOptions](#connectionoptions))**
+
+<Tabs>
+  <TabItem value='promise.js' default>
+
+```js
+import mysql from 'mysql2/promise';
+
 try {
   // highlight-start
   const connection = await mysql.createConnection({