userver: userver/storages/postgres/io/supported_types.hpp Source File
Loading...
Searching...
No Matches
supported_types.hpp
1#pragma once
2
3/// @page pg_types uPg: Supported data types
4///
5/// uPg provides data type support with a system of buffer parsers and
6/// formatters.
7/// Please refer to @ref pg_io for more information about the system.
8///
9/// @see @ref userver_postgres_parse_and_format
10///
11/// @par Fundamental PostgreSQL types
12///
13/// The fundamental PostgreSQL types support is provided by the driver. The
14/// table below shows supported Postgres types and their mapping to C++ types
15/// provided by the driver. Column "Default" marks the Postgres type to which
16/// a C++ type is mapped when used as a parameter. Where the C++ type is N/A
17/// it means that the PosgreSQL data type is not supported. When there is a
18/// C++ type in parenthesis, it is a data type that will be supported later
19/// and the C++ type is planned counterpart.
20/// PG type | C++ type | Default |
21/// ----------------- | --------------------------------------- | ------- |
22/// smallint | std::int16_t | + |
23/// integer | std::int32_t | + |
24/// bigint | std::int64_t | + |
25/// smallserial | std::int16_t | |
26/// serial | std::int32_t | |
27/// bigserial | std::int64_t | |
28/// boolean | bool | + |
29/// real | float | + |
30/// double precision | double | + |
31/// numeric(p) | decimal64::Decimal | + |
32/// decimal(p) | decimal64::Decimal | + |
33/// money | N/A | |
34/// text | std::string | + |
35/// char(n) | std::string | |
36/// varchar(n) | std::string | |
37/// "char" | char | + |
38/// timestamp | std::chrono::system_clock::time_point | + |
39/// timestamptz | storages::postgres::TimePointTz | + |
40/// date | utils::datetime::Date | + |
41/// time | utils::datetime::TimeOfDay | + |
42/// timetz | N/A | |
43/// interval | std::chrono::microseconds | |
44/// bytea | container of one-byte type | |
45/// bit(n) | utils::Flags | |
46/// ^ | std::bitset<N> | |
47/// ^ | std::array<bool, N> | |
48/// bit varying(n) | utils::Flags | |
49/// ^ | std::bitset<N> | |
50/// ^ | std::array<bool, N> | |
51/// uuid | boost::uuids::uuid | + |
52/// json | formats::json::Value | |
53/// jsonb | formats::json::Value | + |
54/// int4range | storages::postgres::IntegerRange | |
55/// ^ | storages::postgres::BoundedIntegerRange | |
56/// int8range | storages::postgres::BigintRange | |
57/// ^ | storages::postgres::BoundedBigintRange | |
58/// inet | utils::ip::AddressV4 | |
59/// ^ | utils::ip::AddressV6 | |
60/// cidr | utils::ip::NetworkV4 | |
61/// ^ | utils::ip::NetworkV6 | |
62/// macaddr | utils::Macaddr | |
63/// macaddr8 | utils::Macaddr8 | |
64/// numrange | N/A | |
65/// tsrange | N/A | |
66/// tstzrange | N/A | |
67/// daterange | N/A | |
68///
69/// @warning The library doesn't provide support for C++ unsigned integral
70/// types intentionally as PostgreSQL doesn't provide unsigned types and
71/// using the types with the database is error-prone.
72///
73/// For more information on timestamps and working with time zones please see
74/// @ref pg_timestamp
75///
76/// @anchor pg_arrays
77/// @par Arrays
78///
79/// The driver supports PostgreSQL arrays provided that the element type is
80/// supported by the driver, including user types.
81///
82/// Array parser will throw storages::postgres::DimensionMismatch if the
83/// dimensions of C++ container do not match that of the buffer received from
84/// the server.
85///
86/// Array formatter will throw storages::postgres::InvalidDimensions if
87/// containers on same level of depth have different sizes.
88///
89/// @par User-defined PostgreSQL types
90///
91/// The driver provides support for user-defined PostgreSQL types:
92/// - domains
93/// - enumerations
94/// - composite types
95/// - custom ranges
96///
97/// For more information please see
98/// @ref scripts/docs/en/userver/pg_user_types.md.
99///
100/// @par C++ strong typedefs
101///
102/// The driver provides support for C++ strong typedef idiom. For more
103/// information see @ref pg_strong_typedef
104///
105/// @par PostgreSQL ranges
106///
107/// PostgreSQL range type support is provided by `storages::postgres::Range`
108/// template.
109///
110/// @par Geometry types
111///
112/// For geometry types the driver provides parsing/formatting from/to
113/// on-the-wire representation. The types provided do not define any calculus.
114///
115/// @anchor pg_bytea
116/// @par PostgreSQL bytea support
117///
118/// The driver allows reading and writing raw binary data from/to PostgreSQL
119/// `bytea` type.
120///
121/// Reading and writing to PostgreSQL is implemented for `std::string`,
122/// `std::string_view` and `std::vector` of `char` or `unsigned char`.
123///
124/// @warning When reading to `std::string_view` the value MUST NOT be used after
125/// the PostgreSQL result set is destroyed.
126///
127/// @code{.cpp}
128/// namespace pg = storages::postgres;
129/// using namespace std::string_literals;
130/// std::string s = "\0\xff\x0afoobar"s;
131/// trx.Execute("select $1", pg::Bytea(tp));
132/// @endcode
133///
134/// @par Network types
135///
136/// The driver offers data types to store IPv4, IPv6, and MAC addresses, as
137/// well as network specifications (CIDR).
138///
139/// @par Bit string types
140///
141/// The driver supports PostgreSQL `bit` and `bit varying` types.
142///
143/// Parsing and formatting is implemented for integral values
144/// (e.g. `uint32_t`, `uint64_t`), `utils::Flags`, `std::array<bool, N>`
145/// and `std::bitset<N>`.
146///
147/// Example of using the bit types from tests:
148/// @snippet storages/postgres/tests/bitstring_pgtest.cpp Bit string sample
149///
150/// @par PostgreSQL types not covered above
151///
152/// The types not covered above or marked as N/A in the table of fundamental
153/// types will be eventually supported later, on request from the driver's
154/// users.
155///
156/// ----------
157///
158/// @htmlonly <div class="bottom-nav"> @endhtmlonly
159/// ⇦ @ref pg_process_results | @ref pg_user_row_types ⇨
160/// @htmlonly </div> @endhtmlonly
161
162//@{
163/** @name Traits etc */
164#include <userver/storages/postgres/io/nullable_traits.hpp>
165#include <userver/storages/postgres/io/traits.hpp>
166#include <userver/storages/postgres/io/type_mapping.hpp>
167#include <userver/storages/postgres/io/type_traits.hpp>
168//@}
169
170//@{
171/** @name Data types */
172#include <userver/storages/postgres/io/bytea.hpp>
173#include <userver/storages/postgres/io/chrono.hpp>
174#include <userver/storages/postgres/io/decimal64.hpp>
175#include <userver/storages/postgres/io/enum_types.hpp>
176#include <userver/storages/postgres/io/floating_point_types.hpp>
177#include <userver/storages/postgres/io/integral_types.hpp>
178#include <userver/storages/postgres/io/string_types.hpp>
179#include <userver/storages/postgres/io/time_of_day.hpp>
180#include <userver/storages/postgres/io/uuid.hpp>
181//@}
182
183//@{
184/** @name Row types */
185#include <userver/storages/postgres/io/row_types.hpp>
186//@}
187
188//@{
189/** @name Type derivatives */
190#include <userver/storages/postgres/io/array_types.hpp>
191#include <userver/storages/postgres/io/composite_types.hpp>
192#include <userver/storages/postgres/io/optional.hpp>
193#include <userver/storages/postgres/io/range_types.hpp>
194#include <userver/storages/postgres/io/strong_typedef.hpp>
195//@}
196
197//@{
198/** @name JSON types */
199#include <userver/storages/postgres/io/json_types.hpp>
200//@}
201
202//@{
203/** @name User type registry */
204#include <userver/storages/postgres/io/user_types.hpp>
205//@}