pqxx::stream_to Class Reference

Efficiently write data directly to a database table. More...

`#include <stream_to.hxx>`

Inheritance diagram for pqxx::stream_to:
[legend]

## Public Member Functions

| stream_to (transaction_base &, const std::string &table_name)
| Create a stream, without specifying columns. More...
template<typename Columns >
| stream_to (transaction_base &, const std::string &table_name, const Columns &columns)
| Create a stream, specifying column names as a container of strings. More...
template<typename Iter >
| stream_to (transaction_base &, const std::string &table_name, Iter columns_begin, Iter columns_end)
| Create a stream, specifying column names as a sequence of strings. More...
| ~stream_to () noexcept
void | complete () override
| Complete the operation, and check for errors. More...
template<typename Tuple >
stream_to & | operator<< (const Tuple &)
| Insert a row of data. More...
stream_to & | operator<< (stream_from &)
| Stream a `stream_from` straight into a `stream_to`. More...
Public Member Functions inherited from pqxx::stream_base
| stream_base (transaction_base &)
virtual | ~stream_base () noexcept=default
| operator bool () const noexcept
bool | operator! () const noexcept
Public Member Functions inherited from pqxx::internal::transactionfocus
| transactionfocus (transaction_base &t)
| transactionfocus ()=delete
| transactionfocus (const transactionfocus &)=delete
transactionfocus & | operator= (const transactionfocus &)=delete
Public Member Functions inherited from pqxx::internal::namedclass
| namedclass (const std::string &Classname)
| namedclass (const std::string &Classname, const std::string &Name)
const std::string & | name () const noexcept
| Object name, or the empty string if no name was given. More...
const std::string & | classname () const noexcept
| Class name. More...
std::string | description () const
| Combination of class name and object name; or just class name. More...

## Additional Inherited Members

Protected Member Functions inherited from pqxx::internal::transactionfocus
void | register_me ()
void | unregister_me () noexcept
void | reg_pending_error (const std::string &) noexcept
bool | registered () const noexcept
Static Protected Member Functions inherited from pqxx::stream_base
template<typename C >
static std::string | columnlist (const C &)
template<typename I >
static std::string | columnlist (I begin, I end)
Protected Attributes inherited from pqxx::stream_base
bool | m_finished
Protected Attributes inherited from pqxx::internal::transactionfocus
transaction_base & | m_trans

## Detailed Description

Efficiently write data directly to a database table.

If you wish to insert rows of data into a table, you can compose INSERT statements and execute them. But it's slow and tedious, and you need to worry about quoting and escaping the data.

If you're just inserting a single row, it probably won't matter much. You can use prepared or parameterised statements to take care of the escaping for you. But if you're inserting large numbers of rows you will want something better.

Inserting rows one by one tends to take a lot of time, especially when you are working with a remote database server over the network. Every single row involves sending the data over the network, and waiting for a reply. Do it "in bulk" using `stream_to`, and you may find that it goes many times faster, sometimes even by orders of magnitude.

Here's how it works: you create a `stream_to` stream to start writing to your table. You will probably want to specify the columns. Then, you feed your data into the stream one row at a time. And finally, you call the stream's `complete()` to tell it to finalise the operation, wait for completion, and check for errors.

You insert data using the `<<` ("shift-left") operator. Each row must be something that can be iterated in order to get its constituent fields: a `std::tuple`, a `std::vector`, or anything else with a `begin` and `end`. It could be a class of your own. Of course the fields have to match the columns you specified when creating the stream.

There is also a matching stream_from for reading data in bulk.

## Constructor & Destructor Documentation

## stream_to() [1/3]

pqxx::stream_to::stream_to | ( | transaction_base & | tb,
|  | const std::string & | table_name
| ) |  |

Create a stream, without specifying columns.

Fields will be inserted in whatever order the columns have in the database.

You'll probably want to specify the columns, so that the mapping between your data fields and the table is explicit in your code, and not hidden in an "implicit contract" between your code and your schema.

Implementation of the pqxx::stream_to class.

pqxx::stream_to enables optimized batch updates to a database table.

Copyright (c) 2000-2019, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

## stream_to() [2/3]

template<typename Columns >

pqxx::stream_to::stream_to | ( | transaction_base & | tb,
|  | const std::string & | table_name,
|  | const Columns & | columns
| ) |  |

Create a stream, specifying column names as a container of strings.

## stream_to() [3/3]

template<typename Iter >

pqxx::stream_to::stream_to | ( | transaction_base & | tb,
|  | const std::string & | table_name,
|  | Iter | columns_begin,
|  | Iter | columns_end
| ) |  |

Create a stream, specifying column names as a sequence of strings.

## ~stream_to()

pqxx::stream_to::~stream_to | ( |  | ) |

noexcept

## Member Function Documentation

## complete()

void pqxx::stream_to::complete | ( |  | ) |

override virtual

Complete the operation, and check for errors.

Always call this to close the stream in an orderly fashion, even after an error. (In the case of an error, abort the transaction afterwards.)

The only circumstance where it's safe to skip this is after an error, if you're discarding the entire connection right away.

Implements pqxx::stream_base.

## operator<<() [1/2]

template<typename Tuple >

stream_to & pqxx::stream_to::operator<< | ( | const Tuple & | t | ) |

Insert a row of data.

The data can be any type that can be iterated. Each iterated item becomes a field in the row, in the same order as the columns you specified when creating the stream.

Each field will be converted into the database's format using `pqxx::to_string`.

References pqxx::separated_list().

## operator<<() [2/2]

pqxx::stream_to & pqxx::stream_to::operator<< | ( | stream_from & | tr | ) |

Stream a `stream_from` straight into a `stream_to`.

This can be useful when copying between different databases. If the source and the destination are on the same database, you'll get better performance doing it all in a regular query.

References pqxx::stream_from::get_raw_line().

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

- stream_to.hxx
- stream_to.cxx