From 8929f7403253cfe4453a2c50b84dcff6fbcc7d1a Mon Sep 17 00:00:00 2001
From: Gregor Giesen <gregor@giesen.net>
Date: Fri, 3 Mar 2023 10:45:31 +0100
Subject: [PATCH] Docs for `skip` attribute of `FromRow` macro

---
 sqlx-core/src/from_row.rs | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs
index 08246bbc8a..93a8f5ed27 100644
--- a/sqlx-core/src/from_row.rs
+++ b/sqlx-core/src/from_row.rs
@@ -123,6 +123,44 @@ use crate::row::Row;
 ///
 /// This field is compatible with the `default` attribute.
 ///
+/// #### `skip`
+///
+/// This is a variant of the `default` attribute which instead always takes the value from
+/// the `Default` implementation for this field type ignoring any results in your query.
+/// This can be useful, if some field does not satifisfy the trait bounds (i.e.
+/// `sqlx::decode::Decode`, `sqlx::type::Type`), in particular in case of nested structures.
+/// For example:
+///
+/// ```rust,ignore
+/// #[derive(sqlx::FromRow)]
+/// struct Address {
+///     user_name: String,
+///     street: String,
+///     city: String,
+/// }
+///
+/// #[derive(sqlx::FromRow)]
+/// struct User {
+///     name: String,
+///     #[sqlx(skip)]
+///     addresses: Vec<Address>,
+/// }
+/// ```
+///
+/// Given 2 querys
+///
+/// ```sql
+/// SELECT name FROM users;
+/// ```
+///
+/// and
+///
+/// ```sql
+/// SELECT user_name, street, city addresses;
+/// ```
+///
+/// the addresses can be assigned to the empty `addresses` field of each `User`.
+///
 /// ## Manual implementation
 ///
 /// You can also implement the [`FromRow`] trait by hand. This can be useful if you