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:

• Related question in #148
• Related discussion on users.rust-lang.org

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 Type trait 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