launchbadge
Improve documentation on insertion using user-defined types
I have found these related issues/pull requests
Slightly related: in #148 , usage of user-defined types for read access is discussed. The discussion ends on a couple of comments on write access (insertion; e.g. this).
Description
The following is not a bug in implementation but something one might consider a bug in documentation.
I recently encountered problems in trying to figure out how to insert into a table using user-defined types by means of the query! macro. Apparently, I'm not the only one finding this a little hard to figure out:
As noted in above discussion, the solution actually is contained in the documentation. However, I'd argue it's split in a little disadvantageous way across multiple pages:
-
The documentation on the
Typetrait explicitly mentions the requirement of using type overrides for user-defined types:With compile-time verification, the use of type overrides is currently required to make use of any user-defined types.
However, it only includes a read-access example - not a write-access (insertion) one.
-
The overrides being a strict requirement is not mentioned in
query!'s documentation. While the documentation actually has a section on type overrides, said section reads more like an "optional" suggestion to supress typechecking.
I'd like to suggest including a basic example on insertion in the docs on query!, similar to the solution to above discussion on users.rust-lang.org to improve discoverability for users.
Reproduction steps
See e.g. this discussion on users.rust-lang.org.
SQLx version
0.8.4
Enabled SQLx features
"runtime-tokio-rustls", "macros", "postgres"
Database server and version
Postgres 17
Operating system
Ubuntu 24.04
Rust version
1.86.0
