userver: components::Postgres Class Reference
No Matches
components::Postgres Class Reference

#include <userver/storages/postgres/component.hpp>

Detailed Description

PosgreSQL client component.

Provides access to a PostgreSQL cluster.

Dynamic options:

Static configuration example:

# yaml
dbalias: taxi
blocking_task_processor: task-processor-name
max_replication_lag: 60s
min_pool_size: 4
max_pool_size: 15
max_queue_size: 200
max_statement_metrics: 50

You must specify either dbalias or dbconnection. If the component is configured with an alias, it will lookup connection data in Secdist.

It is a common practice to provide a database connection string via environment variables. To retrieve a value from the environment use dbconnection#env: THE_ENV_VARIABLE_WITH_CONNECTION_STRING as described in yaml_config::YamlConfig.

You must specify blocking_task_processor as well.

max_replication_lag can be used to tune replication lag limit for replicas. Once the replica lag exceeds this value it will be automatically disabled. Note, however, that client-size lag detection is not precise in nature and can only provide the precision of couple seconds.

Secdist format

A PosgreSQL alias in secdist is described as a JSON array of objects containing a single cluster description. There are two formats of describing a cluster, the first one assigns predefined roles to DSNs, the second one is just a list of DSNs and the Postgres component takes care of discovering the cluster's topology itself.

Predefined roles

In predefined roles format the component requires single-host connection strings.

"shard_number" : 0,
"master": "host=localhost dbname=example",
"sync_slave": "host=localhost dbname=example",
"slaves": [
"host=localhost dbname=example"

The predefined roles format is deprecated and the support will be removed soon.

Automatic discovery

In automatic discovery format the connection strings are any valid PostgreSQL connection strings including multi-host ones with the exception of target_session_attrs which will be ignored.

"shard_number" : 0,
"hosts": [
"host=host1,host2,host3 dbname=example",

The shard_number parameter is required in both formats and must match the index of cluster description object in the alias array.

Please see PostgreSQL documentation on connection strings.

Static options:

Name Description Default value
dbalias name of the database in secdist config (if available)
dbconnection connection DSN string (used if no dbalias specified)
blocking_task_processor name of task processor for background blocking operations
max_replication_lag replication lag limit for usable slaves 60s
sync-start perform initial connections synchronously false
dns_resolver server hostname resolver type (getaddrinfo or async) 'async'
persistent-prepared-statements cache prepared statements or not true
user-types-enabled allow use of user-defined types true
check-user-types cancel service start if some user types have not been loaded, which helps to detect missing migrations false
ignore_unused_query_params disable check for not-NULL query params that are not used in query false
monitoring-dbalias name of the database for monitorings calculated from dbalias or dbconnection options
max_prepared_cache_size prepared statements cache size limit 200
max_statement_metrics limit of exported metrics for named statements 0
min_pool_size number of connections created initially 4
max_pool_size maximum number of created connections for "connlimit_mode: manual" 15
max_queue_size maximum number of clients waiting for a connection 200
connecting_limit limit for concurrent establishing connections number per pool (0 - unlimited) 0
connlimit_mode max_connections setup mode (manual or auto), also see uPg: Automatic connection limit auto
error-injection artificial error injection settings, error_injection::Settings
postgresql/functional_tests/basic_chaos/postgres_service.cpp, and samples/digest_auth_service/auth_digest.cpp.

Definition at line 141 of file component.hpp.

+ Inheritance diagram for components::Postgres:
+ Collaboration diagram for components::Postgres:

Public Member Functions

 Postgres (const ComponentConfig &, const ComponentContext &)
 Component constructor.
 ~Postgres () override
 Component destructor.
storages::postgres::ClusterPtr GetCluster () const
 Cluster accessor for default shard number.
storages::postgres::ClusterPtr GetClusterForShard (size_t shard) const
 Cluster accessor for specific shard number.
size_t GetShardCount () const
 Get total shard count.
storages::postgres::DatabasePtr GetDatabase () const
 Get database object.
void ExtendStatistics (utils::statistics::Writer &writer)
 Reports statistics for PostgreSQL driver.
- Public Member Functions inherited from components::ComponentBase
 ComponentBase (const ComponentConfig &, const ComponentContext &)
 ComponentBase (ComponentBase &&)=delete
 ComponentBase (const ComponentBase &)=delete
 ~ComponentBase () override=default
ComponentHealth GetComponentHealth () const override
void OnLoadingCancelled () override
void OnAllComponentsLoaded () override
void OnAllComponentsAreStopping () override
- Public Member Functions inherited from components::RawComponentBase
 RawComponentBase (RawComponentBase &&)=delete
 RawComponentBase (const RawComponentBase &)=delete

Static Public Member Functions

static yaml_config::Schema GetStaticConfigSchema ()
- Static Public Member Functions inherited from components::ComponentBase
static yaml_config::Schema GetStaticConfigSchema ()
- Static Public Member Functions inherited from components::RawComponentBase
static yaml_config::Schema GetStaticConfigSchema ()

Static Public Attributes

static constexpr size_t kDefaultShardNumber = 0
 Default shard number.
static constexpr storages::postgres::CommandControl kDefaultCommandControl
 Default command control.

Additional Inherited Members

- Protected Types inherited from components::ComponentBase
using LoggableComponentBase = ComponentBase
 Legacy alias, use ComponentBase instead.

Member Function Documentation

◆ GetDatabase()

storages::postgres::DatabasePtr components::Postgres::GetDatabase ( ) const

Get database object.

Definition at line 166 of file component.hpp.

Member Data Documentation

◆ kDefaultCommandControl

constexpr storages::postgres::CommandControl components::Postgres::kDefaultCommandControl
Initial value:

Default command control.

Definition at line 146 of file component.hpp.

◆ kDefaultShardNumber

constexpr size_t components::Postgres::kDefaultShardNumber = 0

Default shard number.

Definition at line 144 of file component.hpp.

The documentation for this class was generated from the following file: