Home

New API proposal:

    var mysql = require('node-mysql');
    //create client with one local connection
    var client = mysql.createClient({ user: root });
    // add new connection using previous user/password/host
    client.addConnection();
    // add remote connection
    client.addConnection({ user: 'safe', password: 'strong', host: 'secure', reconnect: true });

    // execute single query:

    // simple way:
    client.query('select 1 as name', function(result, status) {
       // result is array of rows. Row is object with keys = field names, row.fieldname -> resultset value
       // result may be called more then once for multiple result queries
       // insertId is in optional status object
    });

    client.query('select * from huge_table')
       .on('field', function(fielddesc) {
           // field name, type and index
        })
        .on('row', function(row) {
           // row is array of values
        })
        .on('eos', function() { // better name? 'result_end'? 'endrs'?            
            // called at the end of each result set.
        })
        .on('end', function() {
            // end of query
        });

   // same api as for 'query, but with parameters
   // TODO: any special events for 'prepare' sub-command? prepared/taken from cache flag?
   client.execute('select ?,?,? from huge_table', [param1, param2, paramN], endOfResultCallback);

   // queue control (same api for execute)
   client.urgent().query(...);   // insert query in front of queries queue
   client.urgent(10).query(...); // insert query in front of all queries excluding queries older than 10 ms
   
   // commands execution timeout
   client.query(...).expire(200); 
   // if 200 ms happen _before_ command is sent to server, do not send it and emit 'expire' event for command
   // if command sent, 'expire' event is emitted and all replies are processed. 
   // It's your task to decide if you want to ignore or process data after commend expired
  

   // not sure if we really need this:
   //
   // - use dedicated connection
   // this removes connection from client connection list and creates another client with one connection
   client1 = client.getConnection();
   // remove all connections from client1 and add to client
   client.merge(client1);

Comment from @chrisdew:

I would like two things from a new API:

1. for it to use the standard NodeJS func0(args...., callback(err, res)) format. This would make interop with streamline and other libraries much easier. (I currently use an adaptor layer to turn mysql-native into such a form.)
2. not to break existing code - i.e. change the package name, or make it backwards compatible. I'm sure other users of mysql-native also have code in production which they don't want broken by npm.