Data from `db.query` is not populated until `rs.move_next` is called

[OpenSauce04]

When not using the rs.each block to read each row sequentially, it is seemingly necessary for rs.move_next to be called before the returned data can be accessed.
This doesn't seem to be documented in any visible fashion and lead to half an hour of staring at my query trying to figure out what was wrong with my code.

As an example, the following causes read the column <column> returned a Nil but a Int64 was expected.:

DB.open <uri> do |db|
  db.query "SELECT <column> FROM <table> WHERE <column> = <value>" do |rs|
    puts rs.read(Int32)
  end
end

By contrast, this code returns the expected value, even if the table only has a single row:

DB.open <uri> do |db|
  db.query "SELECT <column> FROM <table> WHERE <column> = <value>" do |rs|
    rs.move_next # <-- Added line
    puts rs.read(Int32)
  end
end

As I mentioned before, this seems to imply that calling rs.move_next or use of the rs.each block is mandatory for the query results to be populated, which unless I'm misunderstanding something seems a unintuitive.
If this intended, please document it somewhere easily visible to save future trial and error sessions from other potential users.

[bcardiff]

I see #query as a factory of the result set.
From your snippets it seems that you expect a single record. Using #query_one is the api designed for that.
If on top of that you only need to read a single column from a single record then #scalar offers you a best api.

Either query_one or scalar (without ?) will fail if no rows are returned which is what you will identify by calling move_next.

Adding an implicit move_next although it seems ergonomic in this example I think it hides some decision you need to make on how to handle empty results. I think is more a mismatch of expectation on what #query does w.r.t. #query_one and #scalar.

I wonder were do you think this is best to be described. The readme shows a #scalar example and #query with #each...

My apologies for the late response.