From c2c33e06f7a6f05bd08d6f4ac176831761db1978 Mon Sep 17 00:00:00 2001
From: Tertium Organum <teorganica@gmail.com>
Date: Fri, 31 May 2024 19:33:00 +0300
Subject: [PATCH] feat docs: add an example for retrieving binary data from a
 'bytea' PostgreSQL field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The main part is

```cpp
row["data"].To(pg::Bytea(tgt_bin_str))
```

Tests: протестировано CI
1c95306de4f096f725f66307f939094defaaecf4

Pull Request resolved: https://github.com/userver-framework/userver/pull/590
---
 .../storages/postgres/io/supported_types.hpp    | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/postgresql/include/userver/storages/postgres/io/supported_types.hpp b/postgresql/include/userver/storages/postgres/io/supported_types.hpp
index a9a0abc6b7af..894938c305ef 100644
--- a/postgresql/include/userver/storages/postgres/io/supported_types.hpp
+++ b/postgresql/include/userver/storages/postgres/io/supported_types.hpp
@@ -127,8 +127,23 @@
 /// @code{.cpp}
 /// namespace pg = storages::postgres;
 /// using namespace std::string_literals;
+/// // using a "binary string"
 /// std::string s = "\0\xff\x0afoobar"s;
-/// trx.Execute("select $1", pg::Bytea(tp));
+/// std::vector<std::uint8_t> tgt_bin_str;
+/// // note: pg::Bytea(const T &) is used
+/// trx.Execute("select $1", pg::Bytea(s));
+/// // storing a byte array:
+/// std::vector<std::uint8_t> bin_str{1, 2, 3, 4, 5, 6, 7, 8, 9};
+/// trx.Execute("INSERT INTO mytable (data) VALUES ($1)", pg::Bytea(bin_str));
+/// // note: pg::Bytea(const T &) is used
+/// @endcode
+///
+/// To read data from bytea field:
+/// @code{.cpp}
+/// // SQL: data BYTEA {NOT} NULL
+/// auto res = trx.Execute("SELECT id, data FROM mytable WHERE id = $1", id);
+/// std::vector<std::uint8_t> tgt_bin_str; const auto& row = res.Front();
+/// row["data"].To(pg::Bytea(tgt_bin_str));  // note: pg::Bytea(T &) is used
 /// @endcode
 ///
 /// @par Network types