Skip to main content

SSL

As part of the connection options, you can specify the ssl object property or a string containing the SSL profile content (deprecated).

ssl?: string | SslOptions;

See full list of SslOptions, which are in the same format as tls.createSecureContext.

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:

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:

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:

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:

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 documentation.

SSL Profile (deprecated)​

There is also a deprecated option allowing to specify a string containing name of SSL profile:

const connection = await mysql.createConnection({
  host: 'localhost',
  ssl: 'Amazon RDS',
});

Following profiles are included in the package:

TLS Session Resumption​

Every new TLS connection normally runs a full handshake, in which the server sends its certificate chain and the client verifies it. MySQL2 keeps the session ticket issued at the end of a successful handshake in memory and presents it on later connections to the same server, which lets the server skip the certificate exchange and, on TLS 1.2, one round trip. This happens automatically and is never persisted to disk.

A session is only reused when the new connection shares the same ssl object, host and port as the one that established it, together with the same rejectUnauthorized and verifyIdentity settings, so a session established under a lax configuration is never resumed by a strict one. Connections created by a pool or a pool cluster already share their ssl object. When you create connections one by one, reuse a single ssl object to get the same benefit:

const ssl = { ca: fs.readFileSync(__dirname + '/mysql-ca.crt') };

const first = await mysql.createConnection({ host: 'localhost', ssl });
const second = await mysql.createConnection({ host: 'localhost', ssl });

A server that rejects or no longer knows the ticket silently falls back to a full handshake, and a failed handshake drops the cached session.

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.

const connection = await mysql.createConnection({
  host: 'localhost',
  ssl: {
    // Beware, set `rejectUnauthorized` as `false` is strongly discouraged for security reasons:
    rejectUnauthorized: false,
  },
});