Wraps 'mysql' to provide mulitple query queues, allowing support for multiple statements and transactions.
Add your own node-mysql query queues to support transactions and multiple statements.
For use with Node.js and node-mysql: https://github.com/felixge/node-mysql
node-mysql does not provide an API for MySQL transactions (yet).
There are a few problems with this:
Fortunately, there are a few solutions:
All that being said, this project is still being actively maintained. It has also been tested with node-mysql 2.0.
npm install mysql-queues
var mysql = require'mysql';var client = mysqlcreateClientuser: 'root'password: 'root';//Enable mysql-queuesvar queues = require'mysql-queues';const DEBUG = true;queuesclient DEBUG;//Start running queries as normal...clientquery;//Now you want a separate queue?var q = clientcreateQueue;qquery;qquery;qexecute;clientquery; //Will not execute until all queued queries (and their callbacks) completed.//Now you want a transaction?var trans = clientstartTransaction;transquery"INSERT..." x y ziferrtransrollback;elsetransquery"UPDATE..." a b c infoinsertIdiferrtransrollback;elsetranscommit;;;transexecute;//No other queries will get executed until the transaction completesclientquery"SELECT ..." //This won't execute until the transaction is COMPLETELY done (including callbacks)//Or... as of version 0.3.0, you can do this...var trans = clientstartTransaction;iferr && transrollback transrollback; throw err;transquery"DELETE..." x error;forvar i = 0; i < n; i++transquery"INSERT..." yi error;transcommit; //Implictly calls resume(), which calls execute()/* In the case written above, COMMIT is placed at the end of the Queue, yet theentire transaction can be rolled back if an error occurs. Nesting these querieswas not required. */
Even multiple Queues work! They get executed in the order that
execute() is called.
Use normally. Same as node-mysql, except that if a Queue is still pending completion, this query may be queued for later execution.
Creates a new query Queue.
Creates a new query Queue with "START TRANSACTION" as the first queued query.
The Queue object will also have
Same as node-mysql. This query will be queued for execution until
is called on the
Executes all queries that were queued using
Queue.query. Until all query
callbacks complete, it is guaranteed that all queries in this Queue
will be executed in order, with no other queries intermixed. That is, during
execution of this query Queue, all queries executed using
be queued until this Queue is empty and all callbacks of this Queue have
finished executing. That means that a query added to a Queue can also queue
a query using
Queue.query, and it will be executed before any
call. Thus, nested query queueing is supported in query callbacks, allowing
support for transactions and more.
See the source code for further documentation.
execute() on an already executing Queue has no effect.
execute() on a paused Queue has no effect. (see
execute() is called and all queries have completed, the Queue
will be empty again, returning control to either: (a) another Queue that has been
queued for execution; or (b) the main node-mysql queue (a.k.a. queries executed
client.query). Once a Queue is empty and has finished executing, you may
continue to use
Queue.execute to queue and execute more
queries; however, as noted below, you should never reuse a Queue created by
Available only if this Queue was created with
cb(err, info) when the COMMIT has completed.
As of version 0.3.0, the behavior of
commit()is called, then 'COMMIT' will be queued to be executed immediately. If this behavior is desired, and you are not sure if the queue will be empty, simply call
commit()is called, then 'COMMIT' will be queued for execution when the queue is empty and all query callbacks have completed.
commit() also implicitly calls
resume() on the Queue.
You may only call
commit() once. Once you call
commit() on this Queue,
you should discard it. To avoid calling
commit() twice, you can check
to see if it exists; once you call
commit(), in most circumstances, the
function is deleted from the Queue object after it is called.
As of version 0.3.0, it is sometimes
possible to call
rollback() even after
commit() has been called.
If 'COMMIT' is queued for execution (i.e. if the queue is not empty when
commit() is called), then you may call
rollback() on this Queue,
as long as
rollback() occurs before the 'COMMIT' is executed (i.e. when the
Queue is empty and all query callbacks have completed).
You might use the functionality in a scenario where you only want your query
callbacks to call
rollback() if an error occurred (i.e. a foreign key
constraint was violated). If no error occurs, you want to call
Rather than nesting all of these queries to determine whether or not to
rollback(), you can simply queue up all of your queries,
commit() to queue up a 'COMMIT', and call
rollback() in your
query callbacks if an error occurs.
If you do not call
rollback() and the Queue has completed
commit() will be called automatically to end the transaction;
however, one should NOT rely on this behavior. In fact, mysql-queues
will print nasty warning messages if you do not explicitly
rollback() a transaction.
Available only if this Queue was created with
This executes 'ROLLBACK' immediately, purges the remaining queries in the
queue, and immediately returns control to the main queue. Finally, the
cb(err, info) is called when the ROLLBACK has completed.
You may only call
rollback() once. To avoid calling it twice, you can
check to see if it exists; once you call
rollback(), the function is
deleted from the Queue object. Also, once you call
rollback(), you cannot
Note: Before 0.2.3,
rollback() would add the 'ROLLBACK' query to the Queue
and the Queue would continue executing. This was changed in 0.2.3 because it
is more natural for a ROLLBACK operation to abort the remaining Queue, since
it will be rolled back anyway. As mentioned above, this also allows you to
queue the COMMIT query at the bottom of the queue, and if an error occurs
before the COMMIT, you can safely
rollback() the entire transaction.
Pauses the Queue, preventing it from returning control to the next Queue or
to the main node-mysql Queue. You can call
resume() to resume the Queue,
or if the Queue is a transaction,
automatically resume the Queue.
By default, the Queue will remain paused until you call
resume() or end
the transaction; however, you may set an optional maximum wait duration,
which will prevent the Queue from pausing for too long.
CAUTION: A paused Queue will block all queries for this connection. Use with care.
Pausing a Queue is useful to make additional asynchronous calls within a query callback. An example of this is shown below.
Resumes Queue execution. This function basically unpauses the Queue and
Attaches mysql-queues to the mysql client. When
debug mode is enabled,
debugging messages are printed to standard error when certain exceptions occur.
When you queue a query, the call stack becomes somewhat useless, and it can
become difficult to determine which query is causing a problem. The debug
feature allows you to more easily determine which query that caused a problem.
//You may be tempted to do this...var fs = require'fs';var trans = dbstartTransaction;transquery"INSERT ..."fsreadFile"foobar.txt"//By now, it's too late to use `trans`ifdata == "something"transcommit;elsetransrollback;;//The query callback is now done!! This is your last chance//to call `commit` or `rollback`execute;
In the case above, an asynchronous call was placed in the query callback.
This won't work as expected. The query callback completes and automatically
commit() before the asychronous filesystem call completes. In this
example, you will get a warning message, your transaction will be committed
no matter what, and your program may throw an exception after the I/O
operation completes (because neither
rollback() can be
called more than once).
To be clear, the scope of this problem is not limited by asynchronous file I/O operations; any asychronous call can cause this problem - even a query to another database will cause this problem (i.e. if you execute a series of MySQL queries and then update Redis, for example)
Possible solutions include: (in order of personal preference)
Queue.pause()right before the asynchrous operation. This is the easy way out, but it comes at a small cost. If you pause a Queue, no query can be executed during the asynchronous operation. So, for scalability reasons, be sure that your asynchronous operation runs quickly (i.e. a Redis command or something). Don't do any video encoding on a 1 GB file.
Queue.pause()because the query execution is paused during the synchronous operation, which will take just as long. But, this works, too.
And finally, to be clear, you are allowed to do asynchronous calls within the
query callback of a transaction. You just need to
pause() beforehand because the Queue will be empty by the time the
asynchronous operation completes.
Please feel free to contact me via GitHub, send pull requests, open issues, etc.
I am open to suggestions and criticisms.