Skip to content
Promises for Node's MySQL Library
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test Finished adding end method Mar 8, 2015
.gitignore Finished adding end method Mar 8, 2015
LICENSE Initial commit Jul 21, 2014
README.md Finished adding end method Mar 8, 2015
index.js Finished adding end method Mar 8, 2015
package.json

README.md

MyOath - MySQL Promises for Node

This simple library wraps node's MySQL functions in promises and adds a little convenience. The test suite tests that it works with the following promise libraries:

If you need something that isn't here, feel free to send a pull request.

I built this because I wanted a little more than the basics but not a full blown ORM.

Using it

var DB = require('myoath'),
    db = new DB.MyOath({
        host: 'localhost',
        user: 'root',
        password: '',
        database: 'db'
    });
db.exec("SELECT * FROM t")
    .then(function (results) {
        //Results.rows contains all the query results.
        //Results.fields contains the column information.
        console.log("Got %d rows", results.rows.length);
    });

MyOath(options) (constructor)

The options are passed to mysql.createPool directly. Other methods will fail until this is called.

An extra option promises is available to inject the promise library you want to use. The object provided should offer a defer() or deferred() method which returns a deferred with at least resolve() and reject() methods. If you want to stream query results with getStream() then the deferred must implement the notify() method.

exec(sql, parameters)

Run a query and return a promise. Resolves to an object with keys for rows and fields. You can optionally pass parameters to the query.

For example:

db.exec('SELECT * FROM t WHERE c = ?', [c])
    .then(function (result) {
        // ...
    });

This will return all results at once and should only be used when reasonably small result sets are expected.

getOneRow(sql, parameters)

This runs a query with exec but the promise it returns resolves to an array containing the single array of values for the first row of the result. It should only be used when only one row is expected, for example when selecting a row by primary key.

db.getOneRow('SELECT * FROM t WHERE id = ?', [id])
    .then(function (row) {
        // ...
    });

getOneValue(sql, parameters)

This runs a query with exec but the promise it returns resolves to a single value. It is useful when running a count(*) query for example.

db.getOneValue('SELECT count(*) FROM t')
    .then(function (row) {
        // ...
    });

set(table, identity, data)

This takes a table name, row identity information, and updated column data and generates and runs an update statement. It returns a promise which resolves when the update completes, or rejects with an error.

This is useful for easily updating rows.

db.set('t', { id: 1 }, { c: 'foo' })
    .then(function () {
        // ...
    });

When building REST style services, this should help with PUT requests.

get(table, identity)

Gets a single row from table with the column data in identity.

db.get('t', { id: 1 })
    .then(function (row) {
        // ...
    });

When building REST style services, this should help with GET requests for single entities.

add(table, data)

Just like set for adding new rows. It's promise resolves to an exec promise which resolves to an object which includes an insertId value.

db.add('t', {
    c: 'foo'
});

When building REST style services, this should help with POST requests.

delete(table, identity)

This takes a table and row identity and deletes any matching rows. Its promise resolves to an object which includes affectedRows with a deleted row count.

db.delete('t', {
    id: 1
});

When building REST style services, this should help with DELETE requests.

getStream(sql, parameters)

Returns a promise which reports rows as progress, and then finally resolves to the field definition data.

db.getStream("SELECT * FROM t WHERE c=?", { c: 'foo' })
    .progress(function (row) {
        // do something with row
    })
    .then(function (fields) {
        // do something with the field data, or just stop expecting
        // more rows in progress().
    })
    .catch(function (error) {
        // Report error
    })
    .done();

Note that it is not possible to cancel a query in progress.

addLogger(f)

Will call f() with a single parameter which is a message to be logged. You can add as many loggers as you like. For quick debugging you can add console.log. If you want to store a log file you might want to consider something like winston.

All messages logged by MyOath will begin with "MyOath: ".

end()

This closes the MySQL connection pool and returns a promise which resolves when all existing queries have completed.

You can’t perform that action at this time.