Clearer query API

[LouisGariepy]

Non-returning statements have this peculiar property that they are executed right after binding their parameters. Meanwhile, statements that return something are only executed after using one of the finalizers.

I'd like to explore the idea of adding an execute finalizer for non-returning statements.

Originally suggested here #88 (reply in thread).

[jacobsvante]

This will be a great addition for clarity IMO 👍

[Virgiel]

It is hard to create ergonomic API with the strictness of Rust. Ultimately we would have this :

insert_book().execute(&client, &"The Great Gatsby").await?;
insert_book().execute(&client, name: &"The Great Gatsby").await?;

But because Rust does not support named arguments neither function overloading we need to have two variant :

insert_book().args(&client, &"The Great Gatsby").await?;
insert_book().struct(&client, Params { name: &"The Great Gatsby" }).await?;

We could use generic functions allowing either struct or tuple, but we would lose some tooling ergonomics:

insert_book().execute(&client, (&"The Great Gatsby")).await?;
insert_book().execute(&client, Params { name: &"The Great Gatsby" }).await?;

[jacobsvante]

I don't know what makes it hard to do in Rust because of its strictness as I don't really know the internals of cornucopia, but I'm sure you're right.

Looking at your examples I think execute() would be closer to the current API, if you're not changing anything else. Perhaps it should even be called bind_execute() to make it completely clear. This would go well with the struct equivalent to bind() – params() – which would then be called params_execute().

[LouisGariepy]

Originally, I thought the suggestion was something like

// this (proposed)
insert_book().bind(&client, &"The Great Gatsby").execute().await?;
// instead of that (current)
insert_book().execute(&client, &"The Great Gatsby").await?;

This has the benefit to make all queries have a consistent api query_name().bind(...).finalizer(), where finalizer is a method that extracts a number of rows (e.g. vec, one, etc.).

I might have misunderstood the suggestion completely though (sorry if this is the case!). I'll amend the issue title if this the case, just let me know.

[Virgiel]

I see how this make the code closer to the SQL semantics, but I think we can resolve this without making the syntax more verbose or generating new types with a simple naming change.

What do you think of this :

insert_book().execute(&client, &"The Great Gatsby").await?;
insert_book().execute_struct(&client, Params { name: &"The Great Gatsby" }).await?;

select_books().query(&client, &"The Great Gatsby").vec().await?;
select_books().query_struct(&client, Params { name: &"The Great Gatsby" }).vec().await?;

Compared to our current syntax:

insert_book().bind(&client, &"The Great Gatsby").await?;
insert_book().params(&client, Params { name: &"The Great Gatsby" }).await?;

select_books().bind(&client, &"The Great Gatsby").vec().await?;
select_books().params(&client, Params { name: &"The Great Gatsby" }).vec().await?;

[Virgiel]

execute_struct and query_struct are a little verbose and misleading, so I welcome any naming proposition. We could do something similar to rfind for 'reverse find' in std with pexecute and pquery for 'params execute' and 'params query'.

[LouisGariepy]

As discussed, we should take a stance on this before releasing the next version. Adding to the milestone.

[jacobsvante]

Personally I prefer a "release often" mentality as releases can get stuck for a long time while waiting for a few PRs (e.g clap v3). I would recommend deferring until 0.10.