libpqxx  7.7.3
pqxx::blob Class Reference

#include <blob.hxx>

Public Member Functions

 blob ()=default
 You can default-construct a blob, but it won't do anything useful. More...
 
 blob (blob &&)
 You can move a blob, but not copy it. The original becomes unusable. More...
 
bloboperator= (blob &&)
 You can move a blob, but not copy it. The original becomes unusable. More...
 
 blob (blob const &)=delete
 
bloboperator= (blob const &)=delete
 
 ~blob ()
 
std::size_t read (std::basic_string< std::byte > &buf, std::size_t size)
 Read up to size bytes of the object into buf. More...
 
template<typename ALLOC >
std::basic_string_view< std::byte > read (std::vector< std::byte, ALLOC > &buf)
 Read up to std::size(buf) bytes from the object. More...
 
template<typename DATA >
void write (DATA const &data)
 Write data large object, at the current position. More...
 
void resize (std::int64_t size)
 Resize large object to size bytes. More...
 
std::int64_t tell () const
 Return the current reading/writing position in the large object. More...
 
std::int64_t seek_abs (std::int64_t offset=0)
 Set the current reading/writing position to an absolute offset. More...
 
std::int64_t seek_rel (std::int64_t offset=0)
 Move the current reading/writing position forwards by an offset. More...
 
std::int64_t seek_end (std::int64_t offset=0)
 Set the current position to an offset relative to the end of the blob. More...
 
void close ()
 Close this blob. More...
 

Static Public Member Functions

static oid create (dbtransaction &, oid=0)
 Create a new, empty large object. More...
 
static void remove (dbtransaction &, oid)
 Delete a large object, or fail if it does not exist. More...
 
static blob open_r (dbtransaction &, oid)
 Open blob for reading. Any attempt to write to it will fail. More...
 
static blob open_w (dbtransaction &, oid)
 
static blob open_rw (dbtransaction &, oid)
 
static oid from_buf (dbtransaction &tx, std::basic_string_view< std::byte > data, oid id=0)
 Create a binary large object containing given data. More...
 
static void append_from_buf (dbtransaction &tx, std::basic_string_view< std::byte > data, oid id)
 Append data to binary large object. More...
 
static oid from_file (dbtransaction &, char const path[])
 Read client-side file and store it server-side as a binary large object. More...
 
static oid from_file (dbtransaction &, char const path[], oid)
 Read client-side file and store it server-side as a binary large object. More...
 
static void to_buf (dbtransaction &, oid, std::basic_string< std::byte > &, std::size_t max_size)
 Convenience function: Read up to max_size bytes from blob with id. More...
 
static std::size_t append_to_buf (dbtransaction &tx, oid id, std::int64_t offset, std::basic_string< std::byte > &buf, std::size_t append_max)
 Read part of the binary large object with id, and append it to buf. More...
 
static void to_file (dbtransaction &, oid, char const path[])
 Write a binary large object's contents to a client-side file. More...
 

Static Public Attributes

static constexpr std::size_t chunk_limit = 0x7fffffff
 Maximum number of bytes that can be read or written at a time. More...
 

Detailed Description

Binary large object.

This is how you store data that may be too large for the BYTEA type. Access operations are similar to those for a file: you can read, write, query or set the current reading/writing position, and so on.

These large objects live in their own storage on the server, indexed by an integer object identifier ("oid").

Two blob objects may refer to the same actual large object in the database at the same time. Each will have its own reading/writing position, but writes to the one will of course affect what the other sees.

Constructor & Destructor Documentation

◆ blob() [1/3]

pqxx::blob::blob ( )
default

You can default-construct a blob, but it won't do anything useful.

Most operations on a default-constructed blob will throw usage_error.

◆ blob() [2/3]

pqxx::blob::blob ( blob &&  other)

You can move a blob, but not copy it. The original becomes unusable.

◆ blob() [3/3]

pqxx::blob::blob ( blob const &  )
delete

◆ ~blob()

pqxx::blob::~blob ( )

Member Function Documentation

◆ append_from_buf()

void pqxx::blob::append_from_buf ( dbtransaction tx,
std::basic_string_view< std::byte >  data,
oid  id 
)
static

Append data to binary large object.

The underlying protocol only supports appending blocks up to 2 GB.

References chunk_limit, open_w(), and seek_end().

◆ append_to_buf()

std::size_t pqxx::blob::append_to_buf ( dbtransaction tx,
oid  id,
std::int64_t  offset,
std::basic_string< std::byte > &  buf,
std::size_t  append_max 
)
static

Read part of the binary large object with id, and append it to buf.

Use this to break up a large read from one binary large object into one massive buffer. Just keep calling this function until it returns zero.

The offset is how far into the large object your desired chunk is, and append_max says how much to try and read in one go.

References chunk_limit, open_r(), and seek_abs().

◆ close()

void pqxx::blob::close ( )

Close this blob.

This does not delete the blob from the database; it only terminates your local object for accessing the blob.

Resets the blob to a useless state similar to one that was default-constructed.

The destructor will do this for you automatically. Still, there is a reason to close() objects explicitly where possible: if an error should occur while closing, close() can throw an exception. A destructor cannot.

References chunk_limit.

Referenced by ~blob().

◆ create()

pqxx::oid pqxx::blob::create ( dbtransaction tx,
oid  id = 0 
)
static

Create a new, empty large object.

You may optionally specify an oid for the new blob. If you do, then the new object will have that oid – or creation will fail if there already is an object with that oid.

References pqxx::transaction_base::conn().

Referenced by from_buf().

◆ from_buf()

pqxx::oid pqxx::blob::from_buf ( dbtransaction tx,
std::basic_string_view< std::byte >  data,
oid  id = 0 
)
static

Create a binary large object containing given data.

You may optionally specify an oid for the new object. If you do, and an object with that oid already exists, creation will fail.

References pqxx::transaction_base::conn(), create(), open_w(), pqxx::connection::process_notice(), and write().

◆ from_file() [1/2]

pqxx::oid pqxx::blob::from_file ( dbtransaction tx,
char const  path[] 
)
static

Read client-side file and store it server-side as a binary large object.

◆ from_file() [2/2]

pqxx::oid pqxx::blob::from_file ( dbtransaction tx,
char const  path[],
oid  id 
)
static

Read client-side file and store it server-side as a binary large object.

In this version, you specify the binary large object's oid. If that oid is already in use, the operation will fail.

◆ open_r()

pqxx::blob pqxx::blob::open_r ( dbtransaction tx,
oid  id 
)
static

Open blob for reading. Any attempt to write to it will fail.

Referenced by append_to_buf(), and to_buf().

◆ open_rw()

pqxx::blob pqxx::blob::open_rw ( dbtransaction tx,
oid  id 
)
static

◆ open_w()

pqxx::blob pqxx::blob::open_w ( dbtransaction tx,
oid  id 
)
static

Referenced by append_from_buf(), and from_buf().

◆ operator=() [1/2]

pqxx::blob & pqxx::blob::operator= ( blob &&  other)

You can move a blob, but not copy it. The original becomes unusable.

◆ operator=() [2/2]

blob& pqxx::blob::operator= ( blob const &  )
delete

◆ read() [1/2]

std::size_t pqxx::blob::read ( std::basic_string< std::byte > &  buf,
std::size_t  size 
)

Read up to size bytes of the object into buf.

Uses a buffer that you provide, resizing it as needed. If it suits you, this lets you allocate the buffer once and then re-use it multiple times.

Resizes buf as needed.

Warning
The underlying protocol only supports reads up to 2GB at a time. If you need to read more, try making repeated calls to append_to_buf.

References chunk_limit.

Referenced by to_buf().

◆ read() [2/2]

template<typename ALLOC >
std::basic_string_view<std::byte> pqxx::blob::read ( std::vector< std::byte, ALLOC > &  buf)

Read up to std::size(buf) bytes from the object.

Deprecated:
As libpqxx moves to C++20 as its baseline language version, this will take and return std::span<std::byte>.

Retrieves bytes from the blob, at the current position, until buf is full (i.e. its current size is reached), or there are no more bytes to read, whichever comes first.

This function will not change either the size or the capacity of buf, only its contents.

Returns the filled portion of buf. This may be empty.

◆ remove()

void pqxx::blob::remove ( dbtransaction tx,
oid  id 
)
static

Delete a large object, or fail if it does not exist.

References pqxx::transaction_base::conn().

◆ resize()

void pqxx::blob::resize ( std::int64_t  size)

Resize large object to size bytes.

If the blob is more than size bytes long, this removes the end so as to make the blob the desired length.

If the blob is less than size bytes long, it adds enough zero bytes to make it the desired length.

◆ seek_abs()

std::int64_t pqxx::blob::seek_abs ( std::int64_t  offset = 0)

Set the current reading/writing position to an absolute offset.

Returns the new file offset.

Referenced by append_to_buf().

◆ seek_end()

std::int64_t pqxx::blob::seek_end ( std::int64_t  offset = 0)

Set the current position to an offset relative to the end of the blob.

You'll probably want an offset of zero or less.

Returns the new file offset.

Referenced by append_from_buf().

◆ seek_rel()

std::int64_t pqxx::blob::seek_rel ( std::int64_t  offset = 0)

Move the current reading/writing position forwards by an offset.

To move backwards, pass a negative offset.

Returns the new file offset.

◆ tell()

std::int64_t pqxx::blob::tell ( ) const

Return the current reading/writing position in the large object.

◆ to_buf()

void pqxx::blob::to_buf ( dbtransaction tx,
oid  id,
std::basic_string< std::byte > &  buf,
std::size_t  max_size 
)
static

Convenience function: Read up to max_size bytes from blob with id.

You could easily do this yourself using the open_r and read functions, but it can save you a bit of code to do it this way.

References open_r(), and read().

◆ to_file()

void pqxx::blob::to_file ( dbtransaction tx,
oid  id,
char const  path[] 
)
static

Write a binary large object's contents to a client-side file.

◆ write()

template<typename DATA >
void pqxx::blob::write ( DATA const &  data)

Write data large object, at the current position.

If the writing position is at the end of the object, this will append data to the object's contents and move the writing position so that it's still at the end.

If the writing position was not at the end, writing will overwrite the prior data, but it will not remove data that follows the part where you wrote your new data.

Warning
This is a big difference from writing to a file. You can overwrite some data in a large object, but this does not truncate the data that was already there. For example, if the object contained binary data "abc", and you write "12" at the starting position, the object will contain "12c".
The underlying protocol only supports writes up to 2 GB at a time. If you need to write more, try making repeated calls to append_from_buf.

References pqxx::transaction_base::conn(), and pqxx::to_buf().

Referenced by from_buf().

Member Data Documentation

◆ chunk_limit

constexpr std::size_t pqxx::blob::chunk_limit = 0x7fffffff
static

Maximum number of bytes that can be read or written at a time.

The underlying protocol only supports reads and writes up to 2 GB exclusive.

If you need to read or write more data to or from a binary large object, you'll have to break it up into chunks.

Referenced by append_from_buf(), append_to_buf(), close(), and read().


The documentation for this class was generated from the following files: