mysql-connection-manager

Manages keep-alive signals, reconnections for a MySQL connection or connection pool.

Installation

Add to your application via npm:

npm install mysql-connection-manager --save

This will install mysql-connection-manager and add it to your application's package.json file.

How to Use

To have mysql-connection-manager create the connection for you:

1var MySQLConnectionManager = require('mysql-connection-manager');
2
3var options = {
4	host: 'localhost',
5	port: 3306,
6	user: 'db_user',
7	password: 'password',
8	database: 'db_name'
9};
10
11var manager = new MySQLConnectionManager(options);
12
13manager.on('connect', function(connection) {
14
15	// Connected!
16
17});
18
19// Pass the connection object to some other module, like this:
20var something = new SomeThing(someOtherOptions, manager.connection);

The connection object is the same as provided by node-mysql.

You can also pass an already existing node-mysql connection object to mysql-connection-manager, like this:

1var mysql = require('mysql');
2var MySQLConnectionManager = require('mysql-connection-manager');
3
4var options = {
5	host: 'localhost',
6	port: 3306,
7	user: 'db_user',
8	password: 'password',
9	database: 'db_name'
10};
11
12var connection = mysql.createConnection(options);
13var manager = new MySQLConnectionManager(options, connection);

To cleanly end the current connection:

1manager.endConnection();

Options

A list of all available options:

1var options = {
2	host: 'localhost',// Host name for database connection.
3	port: 3306,// Port number for database connection.
4	user: 'connect_mng_test',// Database user.
5	password: 'password',// Password for the above database user.
6	database: 'connect_mng_test',// Database name.
7	autoReconnect: true,// Whether or not to re-establish a database connection after a disconnect.
8	reconnectDelay: [
9		500,// Time between each attempt in the first group of reconnection attempts; milliseconds.
10		1000,// Time between each attempt in the second group of reconnection attempts; milliseconds.
11		5000,// Time between each attempt in the third group of reconnection attempts; milliseconds.
12		30000,// Time between each attempt in the fourth group of reconnection attempts; milliseconds.
13		300000// Time between each attempt in the fifth group of reconnection attempts; milliseconds.
14	],
15	useConnectionPooling: false,// Whether or not to use connection pooling.
16	reconnectDelayGroupSize: 5,// Number of reconnection attempts per reconnect delay value.
17	maxReconnectAttempts: 25,// Maximum number of reconnection attempts. Set to 0 for unlimited.
18	keepAlive: true,// Whether or not to send keep-alive pings on the database connection(s).
19	keepAliveInterval: 30000// How frequently keep-alive pings will be sent; milliseconds.
20};

Connection Pooling

When useConnectionPooling is set to true, the manager.connection object is a connection pool object returned by mysql.createPool; see node-mysql for details.

SSL

Provide your SSL configuration options as you would when using the node-mysql module directly. Here's an example:

1var MySQLConnectionManager = require('mysql-connection-manager');
2
3var options = {
4    ssl: {
5        cert : fs.readFileSync( '/path/to/server-cert.pem'),
6        key : fs.readFileSync( '/path/to/server-key.pem')
7    }
8};
9
10var manager = new MySQLConnectionManager(options);

For more details on SSL options, see node-mysql.

Reconnect Delays

The reconnect-related options may require a bit of additional explanation. With the default options shown above, the reconnect attempts will have the following delay pattern:

• Attempts #1 through #5 will have a delay of 500 milliseconds each.
• Attempts #6 through #10 will have a delay of 1 second each.
• Attempts #11 through #15 will have a delay of 5 seconds each.
• Attempts #16 through #20 will have a delay of 30 seconds each.
• Attempts #21 through #25 will have a delay of 5 minutes each.

If the reconnectDelayGroupSize was 3:

• Attempts #1 through #3 will have a delay of 500 milliseconds each.
• Attempts #4 through #6 will have a delay of 1 second each.
• Attempts #7 through #9 will have a delay of 5 seconds each.
• Attempts #10 through #12 will have a delay of 30 seconds each.
• Attempts #13 through #25 will have a delay of 5 minutes each.

Any reconnect attempts beyond the last value in the reconnectDelay array will simply use the last value from the reconnectDelay array.

Alternatively you may supply a single integer value to the reconnectDelay option to have one delay time between all reconnect attempts, like this:

1var options = {
2	reconnectDelay: 500
3};

Events

There are a few events that can be listened for on the manager object:

1manager.on('connect', function(connection) {
2
3	// A database connection has been established..
4
5});
6
7manager.on('reconnect', function(connection) {
8
9	// The database connection has been re-established..
10
11});
12
13manager.on('disconnect', function() {
14
15	// The database connection has been lost..
16
17});

The manager object is extended with the nodejs EventEmitter, so you can use all of the methods that it provides as well: on, off, once, emit, etc.

Debugging

mysql-connection-manager uses the debug module to output debug messages to the console. To output all debug messages, run your node app with the DEBUG environment variable:

DEBUG=mysql-connection-manager node your-app.js

This will output log messages as well as error messages from mysql-connection-manager.

Contributing

There are a number of ways you can contribute:

• Improve or correct the documentation - All the documentation is in this readme.md file. If you see a mistake, or think something should be clarified or expanded upon, please submit a pull request
• Report a bug - Please review existing issues before submitting a new one; to avoid duplicates. If you can't find an issue that relates to the bug you've found, please create a new one.
• Request a feature - Again, please review the existing issues before posting a feature request. If you can't find an existing one that covers your feature idea, please create a new one.
• Fix a bug - Have a look at the existing issues for the project. If there's a bug in there that you'd like to tackle, please feel free to do so. I would ask that when fixing a bug, that you first create a failing test that proves the bug. Then to fix the bug, make the test pass. This should hopefully ensure that the bug never creeps into the project again. After you've done all that, you can submit a pull request with your changes.

Before you contribute code, please read through at least some of the source code for the project. I would appreciate it if any pull requests for source code changes follow the coding style of the rest of the project.

Now if you're still interested, you'll need to get your local environment configured.

Configure Local Environment

Step 1: Get the Code

First, you'll need to pull down the code from GitHub:

git clone git@github.com:chill117/mysql-connection-manager.git

Step 2: Install Dependencies

Second, you'll need to install the project dependencies as well as the dev dependencies. To do this, simply run the following from the directory you created in step 1:

npm install

Step 3: Set Up the Test Database

Now, you'll need to set up a local test database:

1{
2	host: 'localhost',
3	port: 3306,
4	user: 'connect_mng_test',
5	password: 'password',
6	database: 'connect_mng_test'
7};

These database credentials are located at test/config/database.js

Running Tests

With your local environment configured, running tests is as simple as:

npm test