userver: userver/storages/postgres/postgres.hpp Source File
Loading...
Searching...
No Matches
postgres.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/postgres/postgres.hpp
4/// This file is mainly for documentation purposes and inclusion of all headers
5/// that are required for working with PostgreSQL userver component.
6
7#include <userver/storages/postgres/cluster.hpp>
8#include <userver/storages/postgres/component.hpp>
9#include <userver/storages/postgres/exceptions.hpp>
10#include <userver/storages/postgres/result_set.hpp>
11#include <userver/storages/postgres/transaction.hpp>
12
13/// @page pg_driver uPg Driver
14///
15/// 🐙 **userver** provides access to PostgreSQL database servers via
16/// components::Postgres. The uPg driver is asynchronous, it suspends
17/// current coroutine for carrying out network I/O.
18///
19/// @section features Features
20/// - PostgreSQL cluster topology discovery;
21/// - Manual cluster sharding (access to shard clusters by index);
22/// - Connection pooling;
23/// - Queries are transparently converted to prepared statements to use less
24/// network on next execution, give the database more optimization freedom,
25/// avoid the need for parameters escaping as the latter are now send
26/// separately from the query;
27/// - Automatic PgaaS topology discovery;
28/// - Selecting query target (master/slave);
29/// - Connection failover;
30/// - Transaction support;
31/// - Variadic template query parameter passing;
32/// - Query result extraction to C++ types;
33/// - More effective binary protocol usage for communication rather than the
34/// libpq's text protocol;
35/// - Caching the low-level database (D)escribe responses to save about a half
36/// of network bandwidth on select statements that return multiple columns
37/// (compared to the libpq implementation);
38/// - Portals for effective background cache updates;
39/// - Queries pipelining to execute multiple queries in one network roundtrip
40/// (for example `begin + set transaction timeout + insert` result in one
41/// roundtrip);
42/// - Ability to manually control network roundtrips via
43/// storages::postgres::QueryQueue to gain maximum efficiency
44/// in case of multiple unrelated select statements;
45/// - Mapping PostgreSQL user types to C++ types;
46/// - Transaction error injection via pytest_userver.sql.RegisteredTrx;
47/// - LISTEN/NOTIFY support via storages::postgres::Cluster::Listen();
48/// - @ref scripts/docs/en/userver/deadline_propagation.md .
49///
50/// @section toc More information
51/// - For configuration see components::Postgres
52/// - For cluster topology see storages::postgres::Cluster
53/// - @ref pg_transactions
54/// - @ref pg_run_queries
55/// - @ref pg_process_results
56/// - @ref pg_types
57/// - @ref pg_user_types
58/// - @ref pg_errors
59/// - @ref pg_topology
60///
61/// ----------
62///
63/// @htmlonly <div class="bottom-nav"> @endhtmlonly
64/// ⇦ @ref scripts/docs/en/userver/lru_cache.md | @ref pg_transactions ⇨
65/// @htmlonly </div> @endhtmlonly
66
67USERVER_NAMESPACE_BEGIN
68
69namespace storages {
70/// @brief Top namespace for uPg driver
71///
72/// For more information see @ref pg_driver
73namespace postgres {
74/// @brief uPg input-output.
75///
76/// Namespace containing classes and functions for defining datatype
77/// input-output and specifying mapping between C++ and PostgreSQL types.
78namespace io {
79/// @brief uPg input-output traits.
80///
81/// Namespace with metafunctions detecting different type traits needed for
82/// PostgreSQL input-output operations
83namespace traits {} // namespace traits
84} // namespace io
85} // namespace postgres
86} // namespace storages
87
88USERVER_NAMESPACE_END