libpqxx
|
Efficiently write data directly to a database table. More...
#include <stream_to.hxx>
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 |
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 |
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.
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) 2001-2018, 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.
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.
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.
References pqxx::stream_base::columnlist().
|
noexcept |
References complete(), and pqxx::internal::transactionfocus::reg_pending_error().
|
overridevirtual |
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.
References pqxx::internal::transactionfocus::m_trans.
Referenced by ~stream_to().
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().
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_base::close(), pqxx::stream_from::get_raw_line(), pqxx::internal::transactionfocus::m_trans, and pqxx::internal::transactionfocus::register_me().