Documentation: Pool does not compute query.sql immediately

[venning]

I just wanted to record this for posterity in case someone else runs into it. It's not a big deal, but this gave me grief for a while, until I went through the code and realized Pool is actually working as it is supposed to. It might be worth documenting this. Otherwise, feel free to close this issue.

---

When you run Pool#query(sqlString, values, callback) or Pool#query(options, callback), the pool does not immediately format the sql statement due to the connection being acquired asynchronously (after Pool#query returns). The following does work but not as you'd expect:

var query = pool.query('INSERT INTO items SET ?', item, cb);
console.log(query.sql); // INSERT INTO items SET ?

The sql statement will be properly formatted/escaped once the underlying connection is acquired and Connection#query is called.

[dougwilson]

There is a PR #991 going on, but so far it's not backwards-compatible and we are not ready to release a 3.0 major version bump. If someone can put together a PR that's backwards-compatible, that would help a lot, otherwise you would have to work-around not using pool.query if you need the formatted SQL (or simply format before making the query using pool.format() .

[dougwilson]

If you're asking to add documentation to the readme or something, please feel free to make a PR, but as far as I know, we never documented that pool.query is supposed to return anything, so I don't think there is anything to change in the documentation.

Is there documentation that lead to you believe that pool.query has a return value? I would like to address that if I can figure out why people keep thinking this :)

[venning]

(I accidentally posted this before I was finished writing it.) @dougwilson, first thank you for the responses and sorry for reposting. I checked closed issues, but I guess I missed that this had come up before.

---

As for why the documentation was confusing for me (and likely others), I think it has to do with this logic:

• The first sentence in the documentation of .query seems to indicate that .query is identical for Connection and Pool. The specific phrase "call the .query() method on an object" makes it sound like it's the same method, not just named similarly, which appears to be the case.
• The documentation for .query then goes on to describe the three forms of .query without specific reference to Connection or Pool, except in the examples, reinforcing my belief that the methods are identical.
• Near as I can tell, there is no documentation for query().sql. It is referenced twice in examples, once in Escaping query values and once in Escaping query identifiers; in fact, I don't know if the return object of .query is documented anywhere.
• Once I see the examples using Connection#query().sql, I see if the return object from Pool#query has an sql string. It does.

If I believe that two instances of .query are identical, then it's a small leap from there to believe that the sql property of the return object of a call to one .query should be the same as the sql property of the return object of a call to another .query. See the problem? The documentation for .query doesn't differentiate its behavior based on the callee. Looking at the source code before creating this issue corrected my assumption.

I suppose the easiest thing would be to document the object that is returned by .query at some point and, in that documentation, note that the SQL string will not have been formatted synchronously for calls to Pool#query. If you'd like, I can open a PR with that change to the README.

[dougwilson]

Thanks for the feedback! Almost all the documentation was written my users in PRs, and I'm sure mistakes end up slipping by on accident, and we're very sorry! I definitely encourage you to make a PR with fixes and also if you think that slight changes will help people understand better.

[venning]

No need to apologize. node-myql has been fantastic for me. When I get a little time this week, I'll work on a PR.