libpqxx  7.9.0
stream_to.hxx
1 /* Definition of the pqxx::stream_to class.
2  *
3  * pqxx::stream_to enables optimized batch updates to a database table.
4  *
5  * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/stream_to.hxx instead.
6  *
7  * Copyright (c) 2000-2024, Jeroen T. Vermeulen.
8  *
9  * See COPYING for copyright license. If you did not receive a file called
10  * COPYING with this source code, please notify the distributor of this
11  * mistake, or contact the author.
12  */
13 #ifndef PQXX_H_STREAM_TO
14 #define PQXX_H_STREAM_TO
15 
16 #if !defined(PQXX_HEADER_PRE)
17 # error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
18 #endif
19 
20 #include "pqxx/separated_list.hxx"
21 #include "pqxx/transaction_base.hxx"
22 
23 
24 namespace pqxx
25 {
27 
80 class PQXX_LIBEXPORT stream_to : transaction_focus
81 {
82 public:
84 
105  transaction_base &tx, std::string_view path, std::string_view columns = "")
106  {
107  return {tx, path, columns};
108  }
109 
111 
120  static stream_to table(
121  transaction_base &tx, table_path path,
122  std::initializer_list<std::string_view> columns = {})
123  {
124  auto const &conn{tx.conn()};
125  return raw_table(tx, conn.quote_table(path), conn.quote_columns(columns));
126  }
127 
128 #if defined(PQXX_HAVE_CONCEPTS)
130 
137  template<PQXX_CHAR_STRINGS_ARG COLUMNS>
138  static stream_to
139  table(transaction_base &tx, table_path path, COLUMNS const &columns)
140  {
141  auto const &conn{tx.conn()};
142  return stream_to::raw_table(
143  tx, conn.quote_table(path), tx.conn().quote_columns(columns));
144  }
145 
147 
154  template<PQXX_CHAR_STRINGS_ARG COLUMNS>
155  static stream_to
156  table(transaction_base &tx, std::string_view path, COLUMNS const &columns)
157  {
158  return stream_to::raw_table(tx, path, tx.conn().quote_columns(columns));
159  }
160 #endif // PQXX_HAVE_CONCEPTS
161 
162  explicit stream_to(stream_to &&other) :
163  // (This first step only moves the transaction_focus base-class
164  // object.)
165  transaction_focus{std::move(other)},
166  m_finished{other.m_finished},
167  m_buffer{std::move(other.m_buffer)},
168  m_field_buf{std::move(other.m_field_buf)},
169  m_finder{other.m_finder}
170  {
171  other.m_finished = true;
172  }
173  ~stream_to() noexcept;
174 
176  [[nodiscard]] constexpr operator bool() const noexcept
177  {
178  return not m_finished;
179  }
181  [[nodiscard]] constexpr bool operator!() const noexcept
182  {
183  return m_finished;
184  }
185 
187 
193  void complete();
194 
196 
205  template<typename Row> stream_to &operator<<(Row const &row)
206  {
207  write_row(row);
208  return *this;
209  }
210 
212 
217 
219 
225  template<typename Row> void write_row(Row const &row)
226  {
227  fill_buffer(row);
228  write_buffer();
229  }
230 
232 
235  template<typename... Ts> void write_values(Ts const &...fields)
236  {
237  fill_buffer(fields...);
238  write_buffer();
239  }
240 
242 
251  [[deprecated("Use table() or raw_table() factory.")]] stream_to(
252  transaction_base &tx, std::string_view table_name) :
253  stream_to{tx, table_name, ""sv}
254  {}
255 
257 
259  template<typename Columns>
260  [[deprecated("Use table() or raw_table() factory.")]] stream_to(
261  transaction_base &, std::string_view table_name, Columns const &columns);
262 
264 
266  template<typename Iter>
267  [[deprecated("Use table() or raw_table() factory.")]] stream_to(
268  transaction_base &, std::string_view table_name, Iter columns_begin,
269  Iter columns_end);
270 
271 private:
273  stream_to(
274  transaction_base &tx, std::string_view path, std::string_view columns);
275 
276  bool m_finished = false;
277 
279  std::string m_buffer;
280 
282  std::string m_field_buf;
283 
285  internal::char_finder_func *m_finder;
286 
288  void write_raw_line(std::string_view);
289 
291 
293  void write_buffer();
294 
296  static constexpr std::string_view null_field{"\\N\t"};
297 
299  template<typename T>
300  static std::enable_if_t<nullness<T>::always_null, std::size_t>
301  estimate_buffer(T const &)
302  {
303  return std::size(null_field);
304  }
305 
307 
310  template<typename T>
311  static std::enable_if_t<not nullness<T>::always_null, std::size_t>
312  estimate_buffer(T const &field)
313  {
314  return is_null(field) ? std::size(null_field) : size_buffer(field);
315  }
316 
318  void escape_field_to_buffer(std::string_view data);
319 
321 
327  template<typename Field>
328  std::enable_if_t<not nullness<Field>::always_null>
329  append_to_buffer(Field const &f)
330  {
331  // We append each field, terminated by a tab. That will leave us with
332  // one tab too many, assuming we write any fields at all; we remove that
333  // at the end.
334  if (is_null(f))
335  {
336  // Easy. Append null and tab in one go.
337  m_buffer.append(null_field);
338  }
339  else
340  {
341  // Convert f into m_buffer.
342 
343  using traits = string_traits<Field>;
344  auto const budget{estimate_buffer(f)};
345  auto const offset{std::size(m_buffer)};
346 
347  if constexpr (std::is_arithmetic_v<Field>)
348  {
349  // Specially optimised for "safe" types, which never need any
350  // escaping. Convert straight into m_buffer.
351 
352  // The budget we get from size_buffer() includes room for the trailing
353  // zero, which we must remove. But we're also inserting tabs between
354  // fields, so we re-purpose the extra byte for that.
355  auto const total{offset + budget};
356  m_buffer.resize(total);
357  auto const data{m_buffer.data()};
358  char *const end{traits::into_buf(data + offset, data + total, f)};
359  *(end - 1) = '\t';
360  // Shrink to fit. Keep the tab though.
361  m_buffer.resize(static_cast<std::size_t>(end - data));
362  }
363  else if constexpr (
364  std::is_same_v<Field, std::string> or
365  std::is_same_v<Field, std::string_view> or
366  std::is_same_v<Field, zview>)
367  {
368  // This string may need escaping.
369  m_field_buf.resize(budget);
370  escape_field_to_buffer(f);
371  }
372  else if constexpr (
373  std::is_same_v<Field, std::optional<std::string>> or
374  std::is_same_v<Field, std::optional<std::string_view>> or
375  std::is_same_v<Field, std::optional<zview>>)
376  {
377  // Optional string. It's not null (we checked for that above), so...
378  // Treat like a string.
379  m_field_buf.resize(budget);
380  escape_field_to_buffer(f.value());
381  }
382  // TODO: Support deleter template argument on unique_ptr.
383  else if constexpr (
384  std::is_same_v<Field, std::unique_ptr<std::string>> or
385  std::is_same_v<Field, std::unique_ptr<std::string_view>> or
386  std::is_same_v<Field, std::unique_ptr<zview>> or
387  std::is_same_v<Field, std::shared_ptr<std::string>> or
388  std::is_same_v<Field, std::shared_ptr<std::string_view>> or
389  std::is_same_v<Field, std::shared_ptr<zview>>)
390  {
391  // TODO: Can we generalise this elegantly without Concepts?
392  // Effectively also an optional string. It's not null (we checked
393  // for that above).
394  m_field_buf.resize(budget);
395  escape_field_to_buffer(*f);
396  }
397  else
398  {
399  // This field needs to be converted to a string, and after that,
400  // escaped as well.
401  m_field_buf.resize(budget);
402  auto const data{m_field_buf.data()};
403  escape_field_to_buffer(
404  traits::to_buf(data, data + std::size(m_field_buf), f));
405  }
406  }
407  }
408 
410 
416  template<typename Field>
417  std::enable_if_t<nullness<Field>::always_null>
418  append_to_buffer(Field const &)
419  {
420  m_buffer.append(null_field);
421  }
422 
424  template<typename Container>
425  std::enable_if_t<not std::is_same_v<typename Container::value_type, char>>
426  fill_buffer(Container const &c)
427  {
428  // To avoid unnecessary allocations and deallocations, we run through c
429  // twice: once to determine how much buffer space we may need, and once to
430  // actually write it into the buffer.
431  std::size_t budget{0};
432  for (auto const &f : c) budget += estimate_buffer(f);
433  m_buffer.reserve(budget);
434  for (auto const &f : c) append_to_buffer(f);
435  }
436 
438  template<typename Tuple, std::size_t... indexes>
439  static std::size_t
440  budget_tuple(Tuple const &t, std::index_sequence<indexes...>)
441  {
442  return (estimate_buffer(std::get<indexes>(t)) + ...);
443  }
444 
446  template<typename Tuple, std::size_t... indexes>
447  void append_tuple(Tuple const &t, std::index_sequence<indexes...>)
448  {
449  (append_to_buffer(std::get<indexes>(t)), ...);
450  }
451 
453  template<typename... Elts> void fill_buffer(std::tuple<Elts...> const &t)
454  {
455  using indexes = std::make_index_sequence<sizeof...(Elts)>;
456 
457  m_buffer.reserve(budget_tuple(t, indexes{}));
458  append_tuple(t, indexes{});
459  }
460 
462  template<typename... Ts> void fill_buffer(const Ts &...fields)
463  {
464  (..., append_to_buffer(fields));
465  }
466 
467  constexpr static std::string_view s_classname{"stream_to"};
468 };
469 
470 
471 template<typename Columns>
473  transaction_base &tx, std::string_view table_name, Columns const &columns) :
474  stream_to{tx, table_name, std::begin(columns), std::end(columns)}
475 {}
476 
477 
478 template<typename Iter>
480  transaction_base &tx, std::string_view table_name, Iter columns_begin,
481  Iter columns_end) :
482  stream_to{
483  tx,
484  tx.quote_name(
485  table_name,
486  separated_list(",", columns_begin, columns_end, [&tx](auto col) {
487  return tx.quote_name(*col);
488  }))}
489 {}
490 } // namespace pqxx
491 #endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:33
std::string separated_list(std::string_view sep, ITER begin, ITER end, ACCESS access)
Represent sequence of values as a string, joined by a given separator.
Definition: separated_list.hxx:44
std::size_t size_buffer(TYPE const &...value) noexcept
Estimate how much buffer space is needed to represent values as a string.
Definition: strconv.hxx:524
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition: connection.hxx:185
constexpr bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:513
std::basic_ostream< CHAR > & operator<<(std::basic_ostream< CHAR > &s, field const &value)
Write a result field to any type of stream.
Definition: field.hxx:520
Reference to one row in a result.
Definition: row.hxx:47
Stream data from the database.
Definition: stream_from.hxx:79
Efficiently write data directly to a database table.
Definition: stream_to.hxx:81
static stream_to raw_table(transaction_base &tx, std::string_view path, std::string_view columns="")
Stream data to a pre-quoted table and columns.
Definition: stream_to.hxx:104
stream_to & operator<<(Row const &row)
Insert a row of data.
Definition: stream_to.hxx:205
constexpr bool operator!() const noexcept
Has this stream been through its concluding complete()?
Definition: stream_to.hxx:181
static stream_to table(transaction_base &tx, table_path path, std::initializer_list< std::string_view > columns={})
Create a stream_to writing to a named table and columns.
Definition: stream_to.hxx:120
void write_values(Ts const &...fields)
Insert values as a row.
Definition: stream_to.hxx:235
stream_to(transaction_base &tx, std::string_view table_name)
Create a stream, without specifying columns.
Definition: stream_to.hxx:251
stream_to(stream_to &&other)
Definition: stream_to.hxx:162
void write_row(Row const &row)
Insert a row of data, given in the form of a std::tuple or container.
Definition: stream_to.hxx:225
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:88
std::string quote_name(std::string_view identifier) const
Escape an SQL identifier for use in a query.
Definition: transaction_base.hxx:227
constexpr connection & conn() const noexcept
The connection in which this transaction lives.
Definition: transaction_base.hxx:936
Base class for things that monopolise a transaction's attention.
Definition: transaction_focus.hxx:29