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

void	write (std::basic_string_view< std::byte > data)
	Write `data` to 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 (but leave the actual binary large object on the server). 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 ( )

References close(), and pqxx::connection::process_notice().

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 (but leave the actual binary large object on the server).

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

You don't have to call this. The destructor will do it for you. However in the unlikely event that closing the object should fail, the destructor can't throw an exception. The close() function can.

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.

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.

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

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

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.

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.

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

void pqxx::blob::write ( std::basic_string_view< std::byte > data )

Write data to 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 chunk_limit.

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

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