@bletchley-tech/mysqlify

MySQLify

MySQLify is a Promise-based Node.js wrapper for the mysql npm package.

MySQLify aims to make working with a MySQL database easier by providing a promise-based API built on top of the already reliable mysql package.

Note: MySQLify is not a replacement for the mysql package. It is a wrapper for the mysql package.

Installation

$ npm install @bletchley-tech/mysqlify

Usage

MySQLify is built on top of mysql, which means that everything you can do with the mysql package you can do with MySQLify.

While with mysql you'd write code like this:

connection.query("SELECT * FROM Users;", (err, users, fields) => {
    if (err) throw err;
    return users;
});

MySQLify simplifies this to:

const users = await connection.query("SELECT * FROM Users;");

// or

connection.query("SELECT * FROM Users;")
.then(users => {
    // do something with users
})
.catch(err => {
    // handle error
});

In so doing, MySQLify provides a simpler, cleaner method of working with MySQL databases by removing callbacks and avoiding falling into 'callback hell'.

Note: MySQLify does NOT yet support pool connections. For the time being, use the mysql package for pool connections.

MySQLConnection

MySQLify provides a MySQLConnection class that wraps the mysql connection.

To create a connection to a MySQL instance, regardles of whether it is locally- or remotely-hosted, you can use the following code:

const connection = new MySQLConnection({
    host: "localhost",
    user: "root",
    password: "password",
    database: "my_database"
});

// or

const connection = new MySQLConnection('mysql://root:password@localhost/my_database');

Class Attributes

host

The hostname of the MySQL instance (e.g. localhost).

currentUser

The current user of the connection.

This attribute is updated when the changeConnection method is called with the user property.

currentDatabase

The current database being accessed by the connection.

This attribute is updated when the changeConnection method is called with the database property.

connectionId

The ID of the connection.

This is the same as the threadId attribute from the mysql package. See more here.

config

The current configuration of the connection. This will return an object containing the host, user, database, and connectionId of the connection.

Class Methods

connect()

By default, initializing a MySQLConnection instance will connect to the database. Regardless, the class provides a connect() method that can be used to connect to the database.

connection.connect();

To handle errors in this method, as well as the ping and close methods, simple add a catch block and handle the error like you would in any other Promise-based method.

connection.connect()
.catch(err => {
    // handle error
});

query(sql, values)

The query() method is used to execute a query against the database.

connection.query("SELECT * FROM Users;")
.then(users => {
    // do something with users
})
.catch(err => {
    // handle error
});

// or

const users = await connection.query("SELECT * FROM Users;");

The values parameter is optional. If used, it should be an array of values to be bound to the query, while the query string itself (sql) should have a question mark ('?') in the places where you want the values in the values array to be replaced.

connection.query("SELECT * FROM Users WHERE id = ?;", [1])
.then(users => {
    // do something with users
})
.catch(err => {
    // handle error
});

// or

const users = await connection.query("SELECT * FROM Users WHERE id = ?;", [1]);

ping()

The ping() method is used to ping the database. The method will return a Promise that resolves if the database is reachable, or rejects if the database is not reachable.

connection.ping()
.then(() => {
    // database is reachable
})
.catch(err => {
    // database is not reachable
});

If the promise resolves, there will be no return value. If the promise rejects, the rejection will be an Error object.

changeConnection(changeOptions)

The changeConnection() method is used to change the connection settings of the MySQLConnection instance. This method takes a single parameter, which is an object containing the new connection settings.

It will return a Promise that resolves if the connection settings are successfully changed, or rejects if the connection settings are not successfully changed.

connection.changeConnection({
	user: 'newUser',
	password: 'newUserPassword',
	charset: 'newCharset',
	database: 'newDatabase'
})
.then(() => {
	// connection settings have been changed
})
.catch(err => {
	// connection settings could not be changed
});

Same as with the ping() method, if the promise resolves, there will be no return value. If the promise rejects, the rejection will be an Error object.

close()

The close() method is used to close the connection to the database. The method will return a Promise that resolves if the connection is closed, or rejects if the connection is not closed.

connection.close()
.then(() => {
    // connection is closed
})
.catch(err => {
    // connection is not closed
});

Same as with the ping() method, if the promise resolves, there will be no return value. If the promise rejects, the rejection will be an Error object.

License

MySQLify is licensed under the MIT license (see the LICENSE for more information).