feat: allow opt-out of PgHasArrayType with #[derive(sqlx::Type)] (#2619)

closes #2611

sqlx-postgres/src/types/array.rs

@@ -9,6 +9,44 @@ use crate::types::Oid;
 use crate::types::Type;
 use crate::{PgArgumentBuffer, PgTypeInfo, PgValueFormat, PgValueRef, Postgres};
 
+/// Provides information necessary to encode and decode Postgres arrays as compatible Rust types.
+///
+/// Implementing this trait for some type `T` enables relevant `Type`,`Encode` and `Decode` impls
+/// for `Vec<T>`, `&[T]` (slices), `[T; N]` (arrays), etc.
+///
+/// ### Note: `#[derive(sqlx::Type)]`
+/// If you have the `postgres` feature enabled, `#[derive(sqlx::Type)]` will also generate
+/// an impl of this trait for your type if your wrapper is marked `#[sqlx(transparent)]`:
+///
+/// ```rust,ignore
+/// #[derive(sqlx::Type)]
+/// #[sqlx(transparent)]
+/// struct UserId(i64);
+///
+/// let user_ids: Vec<UserId> = sqlx::query_scalar("select '{ 123, 456 }'::int8[]")
+///    .fetch(&mut pg_connection)
+///    .await?;
+/// ```
+///
+/// However, this may cause an error if the type being wrapped does not implement `PgHasArrayType`,
+/// e.g. `Vec` itself, because we don't currently support multidimensional arrays:
+///
+/// ```rust,ignore
+/// #[derive(sqlx::Type)] // ERROR: `Vec<i64>` does not implement `PgHasArrayType`
+/// #[sqlx(transparent)]
+/// struct UserIds(Vec<i64>);
+/// ```
+///
+/// To remedy this, add `#[sqlx(no_pg_array)]`, which disables the generation
+/// of the `PgHasArrayType` impl:
+///
+/// ```rust,ignore
+/// #[derive(sqlx::Type)]
+/// #[sqlx(transparent, no_pg_array)]
+/// struct UserIds(Vec<i64>);
+/// ```
+///
+/// See [the documentation of `Type`][Type] for more details.
 pub trait PgHasArrayType {
     fn array_type_info() -> PgTypeInfo;
     fn array_compatible(ty: &PgTypeInfo) -> bool {