libpqxx
7.5.0
|
Stream data from the database. More...
#include <stream_from.hxx>
Public Types | |
using | raw_line = std::pair< std::unique_ptr< char, std::function< void(char *)> >, std::size_t > |
Public Member Functions | |
Use | query () factory instead.") stream_from(transaction_base & |
Execute query, and stream over the results. More... | |
Use | table () or raw_table() factory instead.") stream_from(transaction_base & |
Stream all rows in table, all columns. More... | |
template<typename Iter > | |
Use | table () or raw_table() factory instead.") stream_from( transaction_base & |
Stream given columns from all rows in table. More... | |
template<typename Columns > | |
Use | table () or raw_table() factory instead.") stream_from( transaction_base &tx |
Stream given columns from all rows in table. More... | |
Use the from_table_t overload instead | stream_from (transaction_base &tx, std::string_view table) |
template<typename Columns > | |
Use the from_table_t overload instead | stream_from (transaction_base &tx, std::string_view table, Columns const &columns) |
template<typename Iter > | |
Use the from_table_t overload instead | stream_from (transaction_base &, std::string_view table, Iter columns_begin, Iter columns_end) |
~stream_from () noexcept | |
operator bool () const noexcept | |
May this stream still produce more data? More... | |
bool | operator! () const noexcept |
Has this stream produced all the data it is going to produce? More... | |
void | complete () |
Finish this stream. Call this before continuing to use the connection. More... | |
template<typename Tuple > | |
stream_from & | operator>> (Tuple &) |
Read one row into a tuple. More... | |
template<typename... Vs> | |
stream_from & | operator>> (std::variant< Vs... > &)=delete |
Doing this with a std::variant is going to be horrifically borked. More... | |
template<typename... TYPE> | |
auto | iter () |
Iterate over this stream. Supports range-based "for" loops. More... | |
std::vector< zview > const * | read_row () |
Read a row. Return fields as views, valid until you read the next row. More... | |
raw_line | get_raw_line () |
Read a raw line of text from the COPY command. More... | |
template<typename Columns > | |
stream_from (transaction_base &tx, from_table_t, std::string_view table_name, Columns const &columns) | |
template<typename Iter > | |
stream_from (transaction_base &tx, from_table_t, std::string_view table, Iter columns_begin, Iter columns_end) | |
Static Public Member Functions | |
static stream_from | query (transaction_base &tx, std::string_view q) |
Factory: Execute query, and stream the results. More... | |
Streaming data from tables | |
You can use | |
static stream_from | raw_table (transaction_base &tx, std::string_view path, std::string_view columns=""sv) |
Factory: Stream data from a pre-quoted table and columns. More... | |
static stream_from | table (transaction_base &tx, table_path path, std::initializer_list< std::string_view > columns={}) |
Factory: Stream data from a given table. More... | |
Public Attributes | |
Use | from_query_t |
Use std::string_view | query |
Use | from_table_t |
Use std::string_view | table |
Use std::string_view Iter | columns_begin |
Use std::string_view Iter Iter | columns_end |
Use std::string_view Columns const & | columns |
Stream data from the database.
Retrieving data this way is likely to be faster than executing a query and then iterating and converting the rows fields. You will also be able to start processing before all of the data has come in.
There are also downsides. If there's an error, it may leave the entire connection in an unusable state, so you'll have to give the whole thing up. Also, your connection to the database may break before you've received all the data, so you may end up processing only part of the data. Finally, opening a stream puts the connection in a special state, so you won't be able to do many other things with the connection or the transaction while the stream is open.
There are two ways of starting a stream: you stream either all rows in a table (using one of the factories, table()
or raw_table()
), or the results of a query (using the query()
factory).
Usually you'll want the stream
convenience wrapper in transaction_base, so you don't need to deal with this class directly.
pqxx::transaction_focus
active on it at a time. using pqxx::stream_from::raw_line = std::pair<std::unique_ptr<char, std::function<void(char *)> >, std::size_t> |
Use the from_table_t overload instead pqxx::stream_from::stream_from | ( | transaction_base & | tx, |
std::string_view | table | ||
) |
table()
or raw_table()
instead. References pqxx::from_table.
Use the from_table_t overload instead pqxx::stream_from::stream_from | ( | transaction_base & | tx, |
std::string_view | table, | ||
Columns const & | columns | ||
) |
table()
or raw_table()
instead. References pqxx::from_table.
Use the from_table_t overload instead pqxx::stream_from::stream_from | ( | transaction_base & | , |
std::string_view | table, | ||
Iter | columns_begin, | ||
Iter | columns_end | ||
) |
table()
or raw_table()
instead.
|
noexcept |
pqxx::stream_from::stream_from | ( | transaction_base & | tx, |
from_table_t | , | ||
std::string_view | table_name, | ||
Columns const & | columns | ||
) |
References pqxx::from_table.
pqxx::stream_from::stream_from | ( | transaction_base & | tx, |
from_table_t | , | ||
std::string_view | table, | ||
Iter | columns_begin, | ||
Iter | columns_end | ||
) |
References pqxx::from_table, pqxx::separated_list(), and table.
void pqxx::stream_from::complete | ( | ) |
Finish this stream. Call this before continuing to use the connection.
Consumes all remaining lines, and closes the stream.
This may take a while if you're abandoning the stream before it's done, so skip it in error scenarios where you're not planning to use the connection again afterwards.
References pqxx::ignore_unused().
pqxx::stream_from::raw_line pqxx::stream_from::get_raw_line | ( | ) |
Read a raw line of text from the COPY command.
Referenced by pqxx::stream_to::operator<<().
auto pqxx::stream_from::iter | ( | ) |
Iterate over this stream. Supports range-based "for" loops.
Produces an input iterator over the stream.
Do not call this yourself. Use it like "for (auto data : stream.iter())".
|
noexcept |
May this stream still produce more data?
|
noexcept |
Has this stream produced all the data it is going to produce?
stream_from & pqxx::stream_from::operator>> | ( | Tuple & | t | ) |
Read one row into a tuple.
Converts the row's fields into the fields making up the tuple.
For a column which can contain nulls, be sure to give the corresponding tuple field a type which can be null. For example, to read a field as int
when it may contain nulls, read it as std::optional<int>
. Using std::shared_ptr
or std::unique_ptr
will also work.
References pqxx::internal::throw_null_conversion().
|
delete |
Doing this with a std::variant
is going to be horrifically borked.
|
static |
Factory: Execute query, and stream the results.
The query can be a SELECT query or a VALUES query; or it can be an UPDATE, INSERT, or DELETE with a RETURNING clause.
The query is executed as part of a COPY statement, so there are additional restrictions on what kind of query you can use here. See the PostgreSQL documentation for the COPY command:
https://www.postgresql.org/docs/current/sql-copy.html
References pqxx::from_query.
Use pqxx::stream_from::query | ( | ) | & |
Execute query, and stream over the results.
query()
instead.
|
static |
Factory: Stream data from a pre-quoted table and columns.
Use this factory if you need to create multiple streams using the same table path and/or columns list, and you want to save a bit of work on composing the internal SQL statement for starting the stream. It lets you compose the string representations for the table path and the columns list, so you can compute these once and then re-use them later.
tx | The transaction within which the stream will operate. |
path | Name or path for the table upon which the stream will operate. If any part of the table path may contain special characters or be case-sensitive, quote the path using pqxx::connection::quote_table(). |
columns | Columns which the stream will read. They should be comma-separated and, if needed, quoted. You can produce the string using pqxx::connection::quote_columns(). If you omit this argument, the stream will read all columns in the table, in schema order. |
References pqxx::transaction_base::conn(), pqxx::from_table, and table.
std::vector< pqxx::zview > const * pqxx::stream_from::read_row | ( | ) |
Read a row. Return fields as views, valid until you read the next row.
Returns nullptr
when there are no more rows to read. Do not attempt to read any further rows after that.
Do not access the vector, or the storage referenced by the views, after closing or completing the stream, or after attempting to read a next row.
A pqxx::zview
is like a std::string_view
, but with the added guarantee that if its data pointer is non-null, the string is followed by a terminating zero (which falls just outside the view itself).
If any of the views' data pointer is null, that means that the corresponding SQL field is null.
|
static |
Factory: Stream data from a given table.
This is the convenient way to stream from a table.
Use pqxx::stream_from::table | ( | ) | & |
Stream all rows in table, all columns.
table()
or raw_table()
instead. Use pqxx::stream_from::table | ( | ) | & |
Stream given columns from all rows in table.
table()
or raw_table()
instead. Use pqxx::stream_from::table | ( | ) | & |
Stream given columns from all rows in table.
query()
instead. Use std::string_view Columns const& pqxx::stream_from::columns |
Use std::string_view Iter pqxx::stream_from::columns_begin |
Use std::string_view Iter Iter pqxx::stream_from::columns_end |
Use pqxx::stream_from::from_query_t |
Use pqxx::stream_from::from_table_t |
Use std::string_view pqxx::stream_from::query |
pqxx::stream_from pqxx::stream_from::table |
Referenced by raw_table(), and stream_from().