Skip to content

Commit ae0a15f

Browse files
apolukhinapolukhin
committed
feat docs: draw more attention to ParameterStore
Tests: протестировано CI commit_hash:12ad079e8846e43999c43a6dddca16833df78a95
1 parent 52a2080 commit ae0a15f

9 files changed

Lines changed: 60 additions & 63 deletions

File tree

‎.mapping.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4634,6 +4634,7 @@
46344634
"scripts/docs/en/userver/os_signals.md":"taxi/uservices/userver/scripts/docs/en/userver/os_signals.md",
46354635
"scripts/docs/en/userver/periodics.md":"taxi/uservices/userver/scripts/docs/en/userver/periodics.md",
46364636
"scripts/docs/en/userver/pg_connlimit_mode_auto.md":"taxi/uservices/userver/scripts/docs/en/userver/pg_connlimit_mode_auto.md",
4637+
"scripts/docs/en/userver/pg_driver.md":"taxi/uservices/userver/scripts/docs/en/userver/pg_driver.md",
46374638
"scripts/docs/en/userver/pg_types.md":"taxi/uservices/userver/scripts/docs/en/userver/pg_types.md",
46384639
"scripts/docs/en/userver/pg_user_types.md":"taxi/uservices/userver/scripts/docs/en/userver/pg_user_types.md",
46394640
"scripts/docs/en/userver/profile_context_switches.md":"taxi/uservices/userver/scripts/docs/en/userver/profile_context_switches.md",

‎postgresql/include/userver/storages/postgres/parameter_store.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ namespace storages::postgres {
1414

1515
/// @ingroup userver_containers
1616
///
17-
/// @brief Class for dynamic PostgreSQL parameter list construction.
17+
/// @brief Class for dynamic PostgreSQL parameter list construction, allows query construction on the fly.
1818
///
1919
/// Typical use case for this container is to keep parameters around while the
2020
/// query is being constructed on the fly:

‎postgresql/include/userver/storages/postgres/postgres.hpp‎

Lines changed: 0 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -10,62 +10,6 @@
1010
#include <userver/storages/postgres/result_set.hpp>
1111
#include <userver/storages/postgres/transaction.hpp>
1212

13-
/// @page pg_driver uPg Driver
14-
///
15-
/// **Quality:** @ref QUALITY_TIERS "Platinum Tier".
16-
///
17-
/// 🐙 **userver** provides access to PostgreSQL database servers via
18-
/// components::Postgres. The uPg driver is asynchronous, it suspends
19-
/// current coroutine for carrying out network I/O.
20-
///
21-
/// @section features Features
22-
/// - PostgreSQL cluster topology discovery;
23-
/// - Manual cluster sharding (access to shard clusters by index);
24-
/// - Connection pooling;
25-
/// - Queries are transparently converted to prepared statements to use less
26-
/// network on next execution, give the database more optimization freedom,
27-
/// avoid the need for parameters escaping as the latter are now send
28-
/// separately from the query;
29-
/// - Automatic PgaaS topology discovery;
30-
/// - Selecting query target (master/slave);
31-
/// - Connection failover;
32-
/// - Transaction support;
33-
/// - Variadic template query parameter passing;
34-
/// - Query result extraction to C++ types;
35-
/// - More effective binary protocol usage for communication rather than the
36-
/// libpq's text protocol;
37-
/// - Caching the low-level database (D)escribe responses to save about a half
38-
/// of network bandwidth on select statements that return multiple columns
39-
/// (compared to the libpq implementation);
40-
/// - Portals for effective background cache updates;
41-
/// - Queries pipelining to execute multiple queries in one network roundtrip
42-
/// (for example `begin + set transaction timeout + insert` result in one
43-
/// roundtrip);
44-
/// - Ability to manually control network roundtrips via
45-
/// storages::postgres::QueryQueue to gain maximum efficiency
46-
/// in case of multiple unrelated select statements;
47-
/// - Mapping PostgreSQL user types to C++ types;
48-
/// - Transaction error injection via pytest_userver.sql.RegisteredTrx;
49-
/// - LISTEN/NOTIFY support via storages::postgres::Cluster::Listen();
50-
/// - @ref scripts/docs/en/userver/deadline_propagation.md .
51-
///
52-
/// @section toc More information
53-
/// - For configuration see components::Postgres
54-
/// - For cluster topology see storages::postgres::Cluster
55-
/// - @ref pg_transactions
56-
/// - @ref pg_run_queries
57-
/// - @ref pg_process_results
58-
/// - @ref scripts/docs/en/userver/pg_types.md
59-
/// - @ref scripts/docs/en/userver/pg_user_types.md
60-
/// - @ref pg_errors
61-
/// - @ref pg_topology
62-
///
63-
/// ----------
64-
///
65-
/// @htmlonly <div class="bottom-nav"> @endhtmlonly
66-
/// ⇦ @ref scripts/docs/en/userver/lru_cache.md | @ref pg_transactions ⇨
67-
/// @htmlonly </div> @endhtmlonly
68-
6913
USERVER_NAMESPACE_BEGIN
7014

7115
namespace storages {

‎postgresql/include/userver/storages/postgres/transaction.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ namespace storages::postgres {
5050
/// ----------
5151
///
5252
/// @htmlonly <div class="bottom-nav"> @endhtmlonly
53-
/// ⇦ @ref pg_driver | @ref pg_run_queries ⇨
53+
/// ⇦ @ref scripts/docs/en/userver/pg_driver.md | @ref pg_run_queries ⇨
5454
/// @htmlonly </div> @endhtmlonly
5555

5656
/// @page pg_run_queries uPg: Running queries

‎scripts/docs/en/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ and make sure that it builds and passes tests.
148148

149149

150150
## PostgreSQL
151-
* @ref pg_driver
151+
* @ref scripts/docs/en/userver/pg_driver.md
152152
* @ref pg_transactions
153153
* @ref pg_run_queries
154154
* @ref pg_process_results

‎scripts/docs/en/userver/build/options.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ userver is split into multiple CMake libraries.
1717
| `userver::grpc` | `USERVER_FEATURE_GRPC` | `grpc` | @ref scripts/docs/en/userver/grpc/grpc.md |
1818
| `userver::grpc-utest` | `USERVER_FEATURE_GRPC` + `USERVER_FEATURE_UTEST` | `grpc` | @ref scripts/docs/en/userver/grpc/grpc.md |
1919
| `userver::mongo` | `USERVER_FEATURE_MONGODB` | `mongo` | @ref scripts/docs/en/userver/mongodb.md |
20-
| `userver::postgresql` | `USERVER_FEATURE_POSTGRESQL` | `postgresql` | @ref pg_driver |
20+
| `userver::postgresql` | `USERVER_FEATURE_POSTGRESQL` | `postgresql` | @ref scripts/docs/en/userver/pg_driver.md |
2121
| `userver::redis` | `USERVER_FEATURE_REDIS` | `redis` | @ref scripts/docs/en/userver/redis.md |
2222
| `userver::redis-utest` | `USERVER_FEATURE_REDIS` + `USERVER_FEATURE_UTEST` | `redis` | @ref scripts/docs/en/userver/redis.md |
2323
| `userver::clickhouse` | `USERVER_FEATURE_CLICKHOUSE` | `clickhouse` | @ref clickhouse_driver |

‎scripts/docs/en/userver/framework_comparison.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ use ❌ and ❓ respectively.
2828
| Async HTTP server | ✔️ @ref components::Server "[↗]" | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ [[↗]][poco-net] |
2929
| Async gRPC client | ✔️ @ref scripts/docs/en/userver/grpc/grpc.md "[↗]" | ✔️ | ✔️ | ± third-party libs | ❌ | ❌ |
3030
| Async gRPC server | ✔️ @ref scripts/docs/en/userver/grpc/grpc.md "[↗]" | ✔️ | ✔️ | ± third-party libs | ❌ | ❌ |
31-
| Async PostgreSQL | ✔️ @ref pg_driver "[↗]" | ± third-party driver | ✔️ [[↗]][dapr-postgre] | ❌ [manual offloading][acti-db] | ✔️ [[↗]][drog-db] | ✔️ [[↗]][poco-db] |
32-
| PostgreSQL pipelining, binary protocol | ✔️ @ref pg_driver "[↗]" | ❌ | ❌ | ± third-party libs | ❌ | ❓ |
31+
| Async PostgreSQL | ✔️ @ref scripts/docs/en/userver/pg_driver.md "[↗]" | ± third-party driver | ✔️ [[↗]][dapr-postgre] | ❌ [manual offloading][acti-db] | ✔️ [[↗]][drog-db] | ✔️ [[↗]][poco-db] |
32+
| PostgreSQL pipelining, binary protocol | ✔️ @ref scripts/docs/en/userver/pg_driver.md "[↗]" | ❌ | ❌ | ± third-party libs | ❌ | ❓ |
3333
| Async Redis | ✔️ @ref scripts/docs/en/userver/redis.md "[↗]" | ± third-party driver | ✔️ [[↗]][dapr-redis] | ± third-party libs | ✔️ [[↗]][drog-redis] | ❓ |
3434
| Async Mongo | ✔️ @ref scripts/docs/en/userver/mongodb.md "[↗]" | ± third-party driver | ✔️ [[↗]][dapr-mongo] | ❌ [manual offloading][acti-db] | ❌ [[↗]][drog-db] | ❓ |
3535
| Async ClickHouse | ✔️ @ref clickhouse_driver "[↗]" | ± third-party driver | ❌ | ± third-party libs | ❌ [[↗]][drog-db] | ❓ |

‎scripts/docs/en/userver/lru_cache.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,5 +59,5 @@ Here's a brief introduction into LRU types:
5959
----------
6060

6161
@htmlonly <div class="bottom-nav"> @endhtmlonly
62-
⇦ @ref pg_cache | @ref pg_driver ⇨
62+
⇦ @ref pg_cache | @ref scripts/docs/en/userver/pg_driver.md ⇨
6363
@htmlonly </div> @endhtmlonly

‎scripts/docs/en/userver/pg_driver.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# uPg Driver
2+
3+
**Quality:** @ref QUALITY_TIERS "Platinum Tier".
4+
5+
🐙 **userver** provides access to PostgreSQL database servers via
6+
components::Postgres. The uPg driver is asynchronous, it suspends
7+
current coroutine for carrying out network I/O.
8+
9+
## Postgres driver Features
10+
- PostgreSQL cluster topology discovery;
11+
- Manual cluster sharding (access to shard clusters by index);
12+
- Connection pooling;
13+
- Queries are transparently converted to prepared statements to use less
14+
network on next execution, give the database more optimization freedom,
15+
avoid the need for parameters escaping as the latter are now send separately from the query;
16+
- Query construction on the fly via @ref storages::postgres::ParameterStore.
17+
- Automatic PgaaS topology discovery;
18+
- Selecting query target (master/slave);
19+
- Connection failover;
20+
- Transaction support via @ref storages::postgres::Transaction RAII wrapper;
21+
- Variadic template query parameter passing;
22+
- Query result extraction to C++ types;
23+
- More effective binary protocol usage for communication rather than the libpq's default text protocol;
24+
- Caching the low-level database (D)escribe responses to save about a half
25+
of network bandwidth on select statements that return multiple columns
26+
(compared to the libpq implementation);
27+
- Portals for effective background cache updates;
28+
- Queries pipelining to execute multiple queries in one network roundtrip
29+
(for example `begin + set transaction timeout + insert` result in one roundtrip);
30+
- Ability to manually control network roundtrips via
31+
@ref storages::postgres::QueryQueue to gain maximum efficiency in case of multiple unrelated select statements;
32+
- Mapping PostgreSQL user types to C++ types;
33+
- Transaction error injection via pytest_userver.sql.RegisteredTrx;
34+
- `LISTEN`/`NOTIFY` support via @ref storages::postgres::Cluster::Listen();
35+
- @ref scripts/docs/en/userver/deadline_propagation.md .
36+
37+
@section toc More information
38+
- For configuration see components::Postgres
39+
- For cluster topology see storages::postgres::Cluster
40+
- @ref pg_transactions
41+
- @ref pg_run_queries
42+
- @ref pg_process_results
43+
- @ref scripts/docs/en/userver/pg_types.md
44+
- @ref scripts/docs/en/userver/pg_user_types.md
45+
- @ref pg_errors
46+
- @ref pg_topology
47+
48+
----------
49+
50+
@htmlonly <div class="bottom-nav"> @endhtmlonly
51+
⇦ @ref scripts/docs/en/userver/lru_cache.md | @ref pg_transactions ⇨
52+
@htmlonly </div> @endhtmlonly

0 commit comments

Comments
 (0)