allow use streaming query rows from promise-connection

[jimmyolo]

https://github.com/mysqljs/mysql#streaming-query-rows
sometime, streaming results interface is useful
add streamingQuery to PromiseConnection
directly export original connection.query to access streaming interface

[sidorares]

I was thinking to have async iterator instead of node stream-like api, see example here: #677 (comment)

[jimmyolo]

looks great!! close this

[sidorares]

I'll put some notes here:

The whole point of streaming is to save resourses ( memory & cpu ). We should be able to avoid buffering all the rows we don't need and potentially skip parsing rest of the rows if exit early from iterator loop.

https://jakearchibald.com/2017/async-iterators-and-generators/

The way fetch() api work is it has 2 stages: 1st await gives you headers, second await is to start reading rest of the body. We could model querying rows similar:

non-streaming version:

   const  response = await connection.fetchQuery('sql');
   // response.fields, response.insertId etc already available here
   const rows = await response.getRows();

streaming version:

   const  response = await connection.fetchQuery('sql');
   // response.fields, response.insertId etc already available here
   for await (const row of response.rows) {
      if (row.id === '123') {
         soSomethingWith(row); // obviously not really great example because we could do the same withe WHERE id=123 sql but hope I demonstrated the point
         break;  // after this we can even skip row packets parsing. We still have to receive all the packets because of the way protocol works but can optimise here by not de-serealising all the packets we won't need
      }
   }  

Still not sure if this is api I like. Since we already have buffering "get all rows" api first we can only model streaming api to stream rows:

   const rows = conn.streamQuery('sql');
   for await (const row of rows) {
     console.log(row); 
  }

• slighly shorter but less flexible. Also in first example not sure if I like 'fetchQuery' name but don't see anything better yet. @gajus do you use async iterators / streams in your helper wrappers? Any suggestions on potential async streaming api?

[jimmyolo]

I found MariaDB official Node.js connector https://github.com/MariaDB/mariadb-connector-nodejs

they use queryStream to return Readable stream https://github.com/MariaDB/mariadb-connector-nodejs/blob/52616f0ef7d2045928a804ea5b27b9151dc88174/lib/connection.js#L168

[sidorares]

@victor0801x node Streams and async iterators are quite different, we need to communicate clearly the difference and ideally have api similar to other async streaming libraries ( in my example it's fetch() but I'd like to see more )