userver: uPg: Supported data types
Loading...
Searching...
No Matches
uPg: Supported data types

uPg provides data type support with a system of buffer parsers and formatters. Please refer to pg_io for more information about the system.

See also
Postgres parsers and formatters
Fundamental PostgreSQL types

The fundamental PostgreSQL types support is provided by the driver. The table below shows supported Postgres types and their mapping to C++ types provided by the driver. Column "Default" marks the Postgres type to which a C++ type is mapped when used as a parameter. Where the C++ type is N/A it means that the PosgreSQL data type is not supported. When there is a C++ type in parenthesis, it is a data type that will be supported later and the C++ type is planned counterpart.

PG type C++ type Default
smallint std::int16_t +
integer std::int32_t +
bigint std::int64_t +
smallserial std::int16_t
serial std::int32_t
bigserial std::int64_t
boolean bool +
real float +
double precision double +
numeric(p) decimal64::Decimal +
decimal(p) decimal64::Decimal +
money N/A
text std::string +
char(n) std::string
varchar(n) std::string
"char" char +
timestamp std::chrono::system_clock::time_point +
timestamptz storages::postgres::TimePointTz +
date utils::datetime::Date +
time utils::datetime::TimeOfDay +
timetz N/A
interval std::chrono::microseconds
bytea container of one-byte type
bit(n) utils::Flags
std::bitset<N>
std::array<bool, N>
bit varying(n) utils::Flags
std::bitset<N>
std::array<bool, N>
uuid boost::uuids::uuid +
json formats::json::Value
jsonb formats::json::Value +
int4range storages::postgres::IntegerRange
storages::postgres::BoundedIntegerRange
int8range storages::postgres::BigintRange
storages::postgres::BoundedBigintRange
inet utils::ip::AddressV4
utils::ip::AddressV6
cidr utils::ip::NetworkV4
utils::ip::NetworkV6
macaddr utils::Macaddr
macaddr8 utils::Macaddr8
numrange N/A
tsrange N/A
tstzrange N/A
daterange N/A
Warning
The library doesn't provide support for C++ unsigned integral types intentionally as PostgreSQL doesn't provide unsigned types and using the types with the database is error-prone.

For more information on timestamps and working with time zones please see uPg timestamp support

Arrays

The driver supports PostgreSQL arrays provided that the element type is supported by the driver, including user types.

Array parser will throw storages::postgres::DimensionMismatch if the dimensions of C++ container do not match that of the buffer received from the server.

Array formatter will throw storages::postgres::InvalidDimensions if containers on same level of depth have different sizes.

User-defined PostgreSQL types

The driver provides support for user-defined PostgreSQL types:

  • domains
  • enumerations
  • composite types
  • custom ranges

For more information please see uPg: PostgreSQL user type mappings.

C++ strong typedefs

The driver provides support for C++ strong typedef idiom. For more information see uPg: support for C++ 'strong typedef' idiom

PostgreSQL ranges

PostgreSQL range type support is provided by storages::postgres::Range template.

Geometry types

For geometry types the driver provides parsing/formatting from/to on-the-wire representation. The types provided do not define any calculus.

PostgreSQL bytea support

The driver allows reading and writing raw binary data from/to PostgreSQL bytea type.

Reading and writing to PostgreSQL is implemented for std::string, std::string_view and std::vector of char or unsigned char.

Warning
When reading to std::string_view the value MUST NOT be used after the PostgreSQL result set is destroyed.
namespace pg = storages::postgres;
using namespace std::string_literals;
std::string s = "\0\xff\x0afoobar"s;
trx.Execute("select $1", pg::Bytea(tp));
Network types

The driver offers data types to store IPv4, IPv6, and MAC addresses, as well as network specifications (CIDR).

Bit string types

The driver supports PostgreSQL bit and bit varying types.

Parsing and formatting is implemented for integral values (e.g. uint32_t, uint64_t), utils::Flags, std::array<bool, N> and std::bitset<N>.

Example of using the bit types from tests:

res = conn->Execute("select 25::bit(8)");
auto bits = res[0][0].As<std::bitset<8>>();
EXPECT_EQ(bits, 0b11001);
res = conn->Execute("select $1::text", bits);
EXPECT_EQ(res[0][0].As<std::string>(), "00011001");
std::uint8_t num{};
res = conn->Execute("select 42::bit(8)");
res[0][0].To(pg::Bit(num));
EXPECT_EQ(num, 42);
PostgreSQL types not covered above

The types not covered above or marked as N/A in the table of fundamental types will be eventually supported later, on request from the driver's users.