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.
| blob (blob &&)
| You can move a blob, but not copy it. The original becomes unusable.
blob & | operator= (blob &&)
| You can move a blob, but not copy it. The original becomes unusable.
| 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`.
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.
template<typename DATA >
void | write (DATA const &data)
| Write `data` large object, at the current position.
void | resize (std::int64_t size)
| Resize large object to `size` bytes.
std::int64_t | tell () const
| Return the current reading/writing position in the large object.
std::int64_t | seek_abs (std::int64_t offset=0)
| Set the current reading/writing position to an absolute offset.
std::int64_t | seek_rel (std::int64_t offset=0)
| Move the current reading/writing position forwards by an offset.
std::int64_t | seek_end (std::int64_t offset=0)
| Set the current position to an offset relative to the end of the blob.
void | close ()
| Close this blob.

## Static Public Member Functions

static oid | create (dbtransaction &, oid=0)
| Create a new, empty large object.
static void | remove (dbtransaction &, oid)
| Delete a large object, or fail if it does not exist.
static blob | open_r (dbtransaction &, oid)
| Open blob for reading. Any attempt to write to it will fail.
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`.
static void | append_from_buf (dbtransaction &tx, std::basic_string_view< std::byte > data, oid id)
| Append `data` to binary large object.
static oid | from_file (dbtransaction &, char const path[])
| Read client-side file and store it server-side as a binary large object.
static oid | from_file (dbtransaction &, char const path[], oid)
| Read client-side file and store it server-side as a binary large object.
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`.
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`.
static void | to_file (dbtransaction &, oid, char const path[])
| Write a binary large object's contents to a client-side file.

## Static Public Attributes

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

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

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

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

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

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

static constexpr

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