Elaborate on 'upsertManyWhere'

[lfborjas]

Expand the documentation of the Postgres version of upsertManyWhere: it wasn't clear how the second argument behaves and at least two coders interpreted it backwards introducing a subtle production bug; hopefully the examples now make it clear!

I don't have a dev env setup for this so I didn't run stylish-haskell, nor do I know if a documentation update warrants a version bump — happy to comply if necessary though!

Before submitting your PR, check that you've:

• Documented new APIs with Haddock markup
• Added @since declarations to the Haddock
• Ran stylish-haskell on any changed files.
• Adhered to the code style (see the .editorconfig file for details)

After submitting your PR:

• Update the Changelog.md file with a link to your PR
• Bumped the version number if there isn't an (unreleased) on the Changelog
• Check that CI passes (or if it fails, for reasons unrelated to your change, like CI timeouts)

[parsonsmatt]

This is a big improvement, thank you! Left a few comments for further improvement

[parsonsmatt]

This wording is a little confusing to me (but, hey, the function itself is a bit confusing!) I think if I were to write it, I'd say something like:

The second list describes what happens if one of the records to be inserted conflicts with a unique key in the database. The 'HandleUpdateCollision' type has more documentation on this. Briefly, we can:

1. copyField will copy the value from the record we tried to insert into the record in the database table.
2. copyUnlessEq (describe this)
3. copyUnlessNull (describe this)
4. etc

[lfborjas]

I like the more abridged approach, thank you! — I'm not 100% sure but, if I follow the docs I think the one of the records part might be a lil bit misleading, since there could be multiple collisions each of which will be resolved in the ON CONFLICT clause (in my mind one of means that only one collision would be resolved? Maybe I'm reading too deep into it.)

Maybe something like what happens for a record proposed for insertion whose unique key conflicts with an existing record in the database (as you can see, the more precise I attempt to get, the more I veer into verbosity lol)

[parsonsmatt]

That's a great point! Thanks.

It is a rather tricky thing to articulate!

The second list describes what happens to the records which have unique key conflicts with existing rows in the database. The HandleUpdateCollision type documents this more thoroughly. Briefly,

1. copyField will update the row in the database with the value of the field of the record we attempted to insert.

is another attempt, but I'm not thrilled with it.

But let me try and break this down:

1. We have a [record] that we want to upsert into the database.
2. If the record does not exist, then we insert it.
3. If the record already exists by some Unique record, then we use [HandleUpdateCollision record] to specify how to handle the collision for that record.

You know, it's occuring to me that this is much easier to express in the singular. For example, upsertWhere :: rec -> [HandleUpdateCollision rec] -> [Update rec] -> [Filter rec] -> m (). We can talk about that like:

Attempt to insert the record into the database. If there is a unique key conflict, and the [Filter rec] are satisfied for the record we are attempting to insert, then we use the [HandleUpdateCollision record] and [Update rec] to specify how to update the record.

I think that [Update rec] aren't included in upsertWhere because it's easy enough to just edit the record itself and copy the field in.

But if upsertWhere is documented in an easy to explain manner, then we can make upsertManyWhere as:

Like upsertWhere, but does a batch upsert for all of the records in the list.

[parsonsmatt]

I might start with "The third argument is a list containing updates..." or similar, so the reader knows that we're now talking about the third argument. I'd also front-load that the update only happens if a conflict occurred.

Possibly,

The third argument specifies arbitrary Updates you can perform on conflicting rows.

With some more elaboration

[parsonsmatt]

Fantastic example!