query_as_with not properly documented and no examples

[liciana24]

Bug Description

the query_as_with function is not properly documented and has no examples. does not seem to work similar to query_as() with fetch_one(). clarification needed.

Minimal Reproduction

https://docs.rs/sqlx/latest/sqlx/fn.query_as_with.html

Info

• SQLx version: [REQUIRED]
• SQLx features enabled: [REQUIRED]
• Database server and version: [REQUIRED] (MySQL / Postgres / SQLite <x.y.z>)
• Operating system: [REQUIRED]
• rustc --version: [REQUIRED]

[xuehaonan27]

@abonander
It seems that using query_as_with is not encouraged. Maybe you should use query_as + bind instead.

The type of the second parameter of query_as_with should implement IntoArguments<'q, DB>,. Only AnyArguments, MySqlArguments, PgArguments, SqliteArguments. All of the has default method to construct but none of them has API to modify them. So it's impossible to pass the second arguments into query_as_with.

Maybe we should just make query_as_with private/deprecated or notify users to user other methods instead.

[zdenek-crha]

I run into this ticket when trying to implement 'repository structthat can work with multiple database backends and trying to encapsulateQueryAs` instance construction into helper functions.

The query_as_with() is extremely useful for that. Let me demonstrate on example:

Goal: Have database agnostic function that constructs QueryAs instance from struct with arguments.

pub struct Args {
    pub id: i32,
    // ... possibly more fields ...
}

#[derive(sqlx::FromRow)]
pub struct Data {
    pub id: i32,
    pub data: String,
    // ... snip many fields ...
}

async fn make_query<'q, D: Database>(args: Args) -> QueryAs<'q, D, Data, Args> {
    ???
}

My first attempt was using query_as + bind as suggested by @xuehaonan27:

async fn make_query<'q, D: Database>(args: Args) -> QueryAs<'q, D, Data, D::Arguments<'q>>
where
    i32: for<'f> sqlx::Encode<'f, D> + sqlx::Type<D>,
    // ... possibly more trait bounds ...
    Data: for<'r> sqlx::FromRow<'r, D::Row>,
{
    sqlx::query_as::<D, Data>(r#"SQL"#)
        .bind(args.id)
        // ... possibly more fields ...
}

I have several issues with the solution:

• bounds needed for bind() look like complex magic
• no visible connection between bounds and types of fields in Args
• when Args changes, all query builder functions needs update

My second attempt uses query_as_with looks lot nicer:

async fn make_query<'q, D: Database>(args: Args) -> QueryAs<'q, D, Data, Args>
where
    Args: sqlx::IntoArguments<'q, D>,
    Data: for<'r> sqlx::FromRow<'r, D::Row>,
{
    sqlx::query_as_with(r#"SQL"#, args)
}

It solves all above issues. When new fields is added to Args only IntoArguments implementation need to be updated and the connection is quite explicit.

I think deprecating and removing query_as_with() would limit crate users. The FromRow and IntoArguments for nice natural pair for in/out conversions. But it won't work without way t use arguments instance in query.

What I would like is to rather fix usability issues around Arguments and IntoArguments traits to make them easier to understand and use. I've described some in #3586