Loading...
Searching...
No Matches
Binary data

The database has two ways of storing binary data: BYTEA is like a string, but containing bytes rather than text characters. And large objects are more like a separate table containing binary objects.

Generally you'll want to use BYTEA for reasonably-sized values, and large objects for very large values.

That's the database side. On the C++ side, in libpqxx, all binary data must be either pqxx::bytes or pqxx::bytes_view; or if you're building in C++20 or better, anything that's a block of contiguous std::byte in memory.

So for example, if you want to write a large object, you'd create a pqxx::blob object. And you might use that to write data in the form of pqxx::bytes_view.

Your particular binary data may look different though. You may have it in a std::string, or a std::vector<unsigned char>, or a pointer to char accompanied by a size (which could be signed or unsigned, and of any of a few different widths). Sometimes that's your choice, or sometimes some other library will dictate what form it takes.

So long as it's basically still a block of bytes though, you can use pqxx::binary_cast to construct a pqxx::bytes_view from it.

There are two forms of binary_cast. One takes a single argument that must support std::data() and std::size():

std::string hi{"Hello binary world"};
my_blob.write(pqxx::binary_cast(hi);
pqxx::binary_cast
bytes_view binary_cast(TYPE const &data)
End a code block started by "ignore-deprecated-pre.hxx".
Definition util.hxx:409

The other takes a pointer and a size:

char const greeting[] = "Hello binary world";
char const *hi = greeting;
my_blob.write(pqxx::binary_cast(hi, sizeof(greeting)));

# Caveats

There are some restrictions on binary_cast that you must be aware of.

First, your data must of a type that gives us bytes. So: char, unsigned char, signed char, int8_t, uint8_t, or of course std::byte. You can't feed in a vector of double, or anything like that.

Second, the data must be laid out as a contiguous block in memory. If there's no std::data() implementation for your type, it's not suitable.

Third, binary_cast only constructs something like a std::string_view. It does not make a copy of your actual data. So, make sure that your data remains alive and in the same place while you're using it.