What is the right Query API?

[Virgiel]

Our API is similar to postgres one:

• query_one: one and only one row
• query_opt: none or only one row
• query: zero or many rows
• query_raw: row stream

But other API exists.

diesel:

• load: zero or many rows
• first: first row
• .optional(): handle NotFound as an optional type instead of an error mixed with others

sqlx:

• fetch: row stream
• fetch_all: zero or many row
• fetch_one: first row
• fetch_optional: none or first row

Should we check that only one row is returned as postgres does, or should we return only the first row? Maybe have both one and first ? Should we provide an optional variant or always return an option and let the user deal with it as the standard API does?

[LouisGariepy]

I like the way postgres enforces stricter invariants with one. For queries where it matters enough to the user that they chose to use this particular method, its safe to assume they do indeed want one and only row. I.e., I think one and opt a useful tools for users to make common assertions about their queries.

I personally don't see much value in adding first. Maybe if it was first(n) where n is the number of rows taken, but even then I personally think its clearer to stream and take however many elements you need (and let the user deal with it as they wnat). That said I'm not opposed to it either, maybe it turns out this use case is common enough to warrant it.

Of course, I'd like to hear as many opinions on this as possible so we get a full picture 😄

[Virgiel]

Now for the other query functions. I think we should replace vec and raw with all and iter. What do you think?

[LouisGariepy]

Yeah that makes it way more consistent.