#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...

blob &	operator= (blob &&)
	You can move a blob, but not copy it. The original becomes unusable. More...

	blob (blob const &)=delete

blob &	operator= (blob const &)=delete

	~blob ()

std::size_t	read (bytes &buf, std::size_t size)
	Read up to `size` bytes of the object into `buf`. More...

template<typename ALLOC >
bytes_view	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, bytes_view data, oid id=0)
	Create a binary large object containing given `data`. More...

static void	append_from_buf (dbtransaction &tx, bytes_view 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, bytes &, 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, bytes &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,
		bytes_view	data,
		oid	id
	)

static

Append data to binary large object.

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

References seek_end().

◆ append_to_buf()

std::size_t pqxx::blob::append_to_buf	(	dbtransaction &	tx,
		oid	id,
		std::int64_t	offset,
		bytes &	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.

◆ 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.

◆ 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().

◆ from_buf()

pqxx::oid pqxx::blob::from_buf	(	dbtransaction &	tx,
		bytes_view	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(), and pqxx::connection::process_notice().

◆ 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.

◆ 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

◆ 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	(	bytes &	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.

◆ read() [2/2]

template<typename ALLOC >

bytes_view 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.

◆ 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,
		bytes &	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.

◆ 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.

Member Data Documentation

◆ chunk_limit

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

staticconstexpr

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.

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

blob.hxx
blob.cxx

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ blob() [1/3]

◆ blob() [2/3]

◆ blob() [3/3]

◆ ~blob()

Member Function Documentation

◆ append_from_buf()

◆ append_to_buf()

◆ close()

◆ create()

◆ from_buf()

◆ from_file() [1/2]

◆ from_file() [2/2]

◆ open_r()

◆ open_rw()

◆ open_w()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ read() [1/2]

◆ read() [2/2]

◆ remove()

◆ resize()

◆ seek_abs()

◆ seek_end()

◆ seek_rel()

◆ tell()

◆ to_buf()

◆ to_file()

◆ write()

Member Data Documentation

◆ chunk_limit