suggestion: add documentation/examples for slightly more complex scenarios involving raw parameter bindings

[khoaHyh]

Description

Under Raw Parameter Binding, the docs say:

Since there is no unified syntax for array bindings, instead you need to treat them as multiple values by adding ? directly in your query.

The docs give this example:

const myArray = [1,2,3]
knex.raw('select * from users where id in (' + myArray.map(_ => '?').join(',') + ')', [...myArray]);

and says the query will become:

select * from users where id in (?, ?, ?) /* with bindings [1,2,3] */

Suggestion

We should add documentation for more complex queries with knex.raw and WHERE IN scenarios where string arrays are passed in.

I think the current examples are great but they are missing examples for more complex queries like if you have multiple bindings to pass and one of them is a string array (see example below). String arrays which are possible bindings to pass because you can have columns that enforce the types text, uuid, varchar(255) , etc. which are passed in as string arrays to the bindings.

Example: knex playground

• someone following the docs might see the simple example and think they can use the .join(',') method as their solution but the SQL code it evaluates to is not what they expect

There's this workaround but it's not documented or as elegant as the simpler examples: here

I found #1537 (comment) which, imo, provides the most straightforward solution to handling arrays in knex.raw and WHERE IN scenarios. I'd want something like this added to the docs so I know how to pass in string arrays as bindings when more parameters are involved and I can't use the .join solution.