Integer determining how many replicas shardmanctl should configure for each DBMS. This setting can only be changed for a Shardman cluster with a manual-topology mode.

String determining the policy of placing DBMS instances. Currently, cross and manual placement policy is only supported. The former value clover is used as an alias for cross policy.

With cross placement policy, nodes are grouped in clovers, where each node is running the master DBMS server and replicas for all other nodes in the clover. The number of nodes in a clover is determined by Repfactor and equals Repfactor + 1.

manual placement policy allows you to manually add/remove the required number of replicas to/from the specified replication groups. In this case, Rеpfactor is only used for recommendation purposes and does not impose restrictions.

Allows you to specify a directory other than the default one (/var/lib/pgpro/sdm-14/data) for storing data. This parameter cannot be changed after the cluster has been initialized.

Ports starting with this integer are assigned to PostgeSQL instances. This parameter cannot be changed after the cluster has been initialized.

Ports starting with this integer are assigned to Silk (Shardman InterLinK) instances. This parameter cannot be changed after the cluster has been initialized.

Authentication method used by the administrative user to connect to the DBMS. Can be any authentication method supported by PostgreSQL. scram-sha-256 is currently recommended. md5 is currently allowed but not recommended. This parameter cannot be changed after the cluster has been initialized. Located under a separate Users block for each array element.

Default: trust.

An array that can have two possible values, su for superuser or repl for replication.

Defines settings for the secure HTTP/HTTPS connection, with Port being an API port, and PortMetrics being a port for the metrics. If these ports are the same, then API and metrics listen to the same port.

Default: 15432.

Name of the user. Created on cluster initialization. Defaults to the name of the effective user running shardmanctl init. This parameter cannot be changed after the cluster has been initialized. Located under a separate Users block for each array element.

Password for the user. Can be changed using shardmanctl config update credentials. Located under a separate Users block for each array element.

Client certificate for the administrative DBMS user.

Location of the root certificate file for the DBMS user connection.

Client private key for the administrative DBMS user.

SSL mode for the DBMS user. Allowed values: verify-ca and verify-full.

Client certificate for the replication DBMS user.

Client private key for the replication DBMS user.

Shard cluster specification. For more details, see ShardSpec Parameters. Can be changed using shardmanctl config update.

This object contains FDW settings.

These settings can be changed using shardmanctl config update (with the exception of settings related to authorization, server connection, SSL and Kerberos, as well as the service, target_session_attrs options).

Foreign servers corresponding to Shardman replication groups will also get extended_features setting automatically enabled. Never set this parameter for postgres_fdw foreign servers which you define for your own purposes (for example, to load data into Shardman cluster).

JSON array of pg_hba.conf strings. The default value allows user from the su group access from anywhere with AuthMethod authentication method. If the value of defaultSUReplAccessMode is strict, pg_hba.conf strings must explicitly allow users from the groups su or repl access from all Shardman cluster nodes.

When enabled, it sets a peer authentication via unix socket for the postgres user, if strictUserHBA is not set to true.

Default: false.

Determines whether replicas should use synchronous replication. Should be true in a Shardman cluster.

Default: true.

Maximum number of required synchronous standbys when synchronous replication is enabled. Should be >= Repfactor in a Shardman cluster. Default: Repfactor.

Prohibits adding automatically generated lines to pg_hba.conf file. Default: false.

Determines whether a DBMS instance should be automatically restarted after a change of the pgParameters hash table that requires a restart. Should be enabled in a Shardman cluster.

Default: true.

Enable master demotion in case the replica group master has lost connectivity with etcd. The master attempts to connect to each of its standby nodes to determine if any of them has become the master. If it discovers another master, it shuts down its own DBMS instance until the connectivity with etcd is restored. If the master fails to connect to one of its standby nodes for a long time, a DBMS instance shutdown occurs.

Default: false.

The timeout during which the master attempts to connect to its standbys in cases where connectivity with etcd is lost. Works only if the masterDemotionEnabled parameter is set to true.

Default: 30s.

Enable the monitor for the MinSynchronousStandbys value for every replica group. If a node loses connection with the cluster (all keepers are unhealthy: a keeper does not update its state longer than minSyncMonitorUnhealthyTimeout), the monitor decreases the MinSynchronousStandbys value for every replica group related to the disconnected node to the maximum available value. This allows preventing the read-only condition caused by the fake replica. The maximum available value is always less than or equal to the value specified in the cluster configuration. If all keepers related to the disconnected node become healthy, the monitor changes MinSynchronousStandbys value for the replica group to the value specified in the cluster configuration.

Default: false.

Time interval after which the node (and all keepers related to this node) will be considered in an unhealthy condition. Works only if the minSyncMonitorEnabled parameter is set to true.

Default: 30s.

Enable the monitor that creates a syncpoint every minute, ensuring the Shardman can restore to a consistent LSN. At each syncpoint, the cluster's state is consistent, meaning that all transactions are complete. If this parameter is set to true, PITR will be guaranteed to work. If set to true, it saves the syncpoint history in etcd with the key shardman/{cluster_name}/data/cluster/syncpoints.

Default: false.

Specifies how often a syncpoint is created (seconds).

Default: 60 seconds.

Enables monitor that periodically creates syncpoints.

Default: true.

Amount of the most recent syncpoints stored.

Default: 60.

Before full resync of a replica, the cluster software first tries to do pg_rewind. Because the rewind operation is significantly faster than other approaches when the database is large and only a small fraction of blocks differs between the clusters. The dbWaitRewindTimeout parameter specifies the maximum working time for pg_rewind (examples of values: 5m, 30s, 1m30s).

Default: 7m.

Array of names of physical replication slots that are created on the master. Each slot name must begin with the stolon_ prefix.

If true, physical replication slots are also created on standby nodes.

The limit of the volume by which replication slots defined by the additionalReplicationSlots configuration parameter can lag behind. If this value is exceeded, the slot is recreated. Specify the value as a number followed by a unit of measurement. Possible units: B, kB, kiB, MB, MiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB, ZB, ZiB, YB, and YiB. For example: 100MB.

Hash table that determines PostgreSQL settings, including Shardman-specific settings. Supports the following placeholders for postgres parameters: {{dataDir}} for data directory, {{keeperDir}} for keeper data directory under dataDir, {{keeperName}} for keeper name, {{keeperID}} for keeper ID, {{cluster}} for cluster name, {{shard}} for shard name, {{host}} for host with the working postgres instance.

Enables or disables Commit Sequence Number (CSN) based tracking of the transaction visibility for a snapshot.

PostgreSQL uses the clock timestamp as a CSN, so enabling CSN-based snapshots can be useful for implementing global snapshots and global transaction visibility.

When this parameter is enabled, PostgreSQL creates the pg_csn directory under PGDATA to keep track of CSN and XID mappings.

Default: off.

Enables estimation logic for plan costs. It helps the planner choose generic plans more often considering the runtime pruning.

Default: off.

If enabled, custom plans can be created to execute statements inside SQL functions. These plans depend on the parameter values.

Query plans can be cached within one query. First, the plan is built five times with different parameter values, then a generic plan is created regardless of the values. If custom and generic plan price is slightly different, then the generic plan is cached and is set to be used in the future. However, custom plans allow a more effective way of excluding queries to the sharded table partitions if the choice of these partitions depends on the query parameter.

Default: off.

Enables the use of MergeAppend plans by the query planner.

Default: on.

Enables or disables the query planner's use of async-aware merge append plan types. The default is on.

Specifies the minimal age of records that are allowed to be vacuumed, in seconds.

All global transactions must start on all participant nodes within csn_snapshot_defer_time seconds after start, otherwise, they are aborted with a “csn snapshot too old” error.

Default: 15.

Specifies the maximum possible clock skew (in nanoseconds) in the cluster. Adds a delay before every commit in the system to ensure external consistency. If set to 0, external consistency is not guaranteed. Value suffixes ns, us, ms and s are allowed.

Default: 0.

Size of CSNLSNMap.

The commit record of each completed transaction in Shardman contains the assigned CSN for this transaction. This value, together with the LSNof this record, forms a pair of values (CSN, LSN). Each of the cluster nodes stores a certain number of such pairs in RAM in a special structure - the CSNLSNMap. This map is used to get the syncpoint. See the “Syncpoints and Consistent Backup” section of the Internals chapter for more information.

Default: 1024.

When checked against the csn_max_shift value, raises an error if the csn_max_shift value is exceeded.

Default: off.

Maximum CSN shift in seconds for distributed queries and imported snapshots. If the shift exceeds the csn_max_shift value, an error or warning will occur. If the value is set to 0, no check is run.

Default: 15 (seconds).

Specifies how often foreign statistics should be gathered during autovacuum, in seconds. If the value of foreign_analyze_interval is less than autovacuum_naptime, foreign statistics will be gathered each autovacuum_naptime seconds.

Default: 60.

Turns on a fast path for foreign join planning. When it is on, foreign join paths for SELECT queries are searched before all other possible paths and the search stops for a join as soon as a foreign join path is found.

Default: off.

Enables or disables the query planner's logic of transforming correlated subqueries into semi-joins.

Default: on.

A TCP port the server listens on. For a Shardman cluster, the port is assigned automatically by the system and is based on the PGsInitialPort parameter. If changed manually, the value will be overwritten by the configuration parameter that is automatically assigned.

Enables the extended partition pruning for the prepared queries with a known partitioning key. If turned on, the partition-wise join plans can be pruned.

Default: off.

When set to on, Shardman will write diagnostic information about a backend crash into a file.

Default: on.

Specifies a comma-separated list of character strings that contain data sources to provide data for a crash dump. Possible values of the strings are as follows:

Default: system,module,queries,cpu_context,instruction_pointer

Specifies the directory where information about a backend crash is to be stored. The value of stderr sends information about the crash to stderr. If this parameter is set to the empty string '', the $PGDATA/crash_info directory is used. If you wish to keep the files elsewhere, create the target directory in advance and grant appropriate privileges.

Default: ''.

Enables or disables dumping of long-running query state by timer, which allows profiling such queries. The timer is launched by the interval specified in crash_info_timer_interval and measures query processing time. When query execution time exceeds the threshold specified in crash_info_query_threshold, the query state is dumped to disk. The default value is off. For the timer to operate, crash_info_dump must be set at least to queries. This setting can be changed only by superusers using the SET command in the current session or in the configuration file globally.

This parameter can only be set at server start in the postgresql.conf file. To re-read the parameter value, restart the server or send the SIGHUP signal to the main server process.

Sets the time interval to launch the timer, in milliseconds. The default value is 1000. This setting can be changed only by superusers using the SET command in the current session or in the configuration file globally.

This parameter can only be set at server start in the postgresql.conf file. To re-read the parameter value, restart the server or send the SIGHUP signal to the main server process.

Sets the threshold value for the query processing time, in milliseconds. When reached, the query state is dumped to disk. The default value is 3000. This setting can be changed only by superusers using the SET command in the current session or in the configuration file globally.

This parameter can only be set at server start in the postgresql.conf file. To re-read the parameter value, restart the server or send the SIGHUP signal to the main server process.

Logs the remote contexts. If enabled, in case of an error, displays a field Remote CONTEXT. Note that if the standart log level is set to log_verbosity=terse, the shardman.context_log will be disabled automatically.

Default: on.

Turns on alternative estimations for foreign join costs, which highly increases chances for join of several foreign tables referring to the same server to be pushed down. The cost of original join is estimated as (1 - 1/(cost + 1)), where cost is an originally estimated cost for this remote join.

Default: off.

Defines how to include the EXPLAIN command output from the remote servers if the query plan contains ForeignScan nodes. The possible values are: none to exclude the EXPLAIN output from the remote servers, full to include the EXPLAIN output from the remote servers, collapsed to include the EXPLAIN output only for the first ForeignScan node under its Append/MergeAppend.

Default: collapsed.

Sets postgres_fdw to try fetching the first portion of cursor data immediately after declaration and delay the cursor closing.

This postgres_fdw parameter forces it to avoid closing cursors after the end of scan. Cursors are closed at the end of transaction.

Default: off.

Enables or disables postgres_fdw logic of pushing down subqueries referencing only foreign server tables to this foreign server.

Default: off.

Sets postgres_fdw to use the two-phase commit (2PC) protocol for distributed transactions.

This postgres_fdw parameter forces it to use a two-phase commit if the transaction touches several nodes. When set to auto, a two-phase commit is only used in transactions with enable_csn_snapshot=true and isolation level equal to or higher than REPEATABLE READ.

Temporary tables cannot be used in 2PC transactions.

Default: auto.

When enabled, the planner estimates a foreign join cost in a way similar to a cost of a hash-join whenever possible. This cost is compared to the default cost (which is similar to nested loops) and the smaller cost is selected for the path.

Default: off.

Enables cost estimation for foreign scans as if they were index scans.

When disabled, the cost of scanning of a foreign table is estimated as a sequential scan added to the cost of data transfer and local filtering if some filters are applied locally. When enabled, any remote scan can be estimated as index scan, should there be any suitable index.

If a foreign table is a part of a sharded table, then information about its indexes is taken from a random local partition of the sharded table. This decision is made based on assumption that data distribution between the sharded table partitions is uniform, and definition of local and remote partitions match.

Expecting the remote scan to be executed as index scan makes foreign scan costs comparable to local scan costs, which can be important for further path selection. Note that this estimation makes planning more expensive, and is not recommended for simple queries.

Default: off.

When enabled, sorting on the remote server is considered if it allows performing MergeJoin or MergeAppend operations. This parameter is enabled by default in new installations but must be explicitly enabled in upgraded clusters.

Sets Shardman extension to broadcast DDL statements to all replication groups.

When this parameter is on, Shardman extension broadcasts supported DDL statements to all replication groups if it does make sense for those statements. You can enable/disable this behavior anytime. This parameter is not honored when set in configuration file. Note that it does not affect sequences, as they are only created per shard.

Default: off.

Enable pushing down limit clauses through the underlying appends. When on, Shardman optimizer will try to push down a limit clause to the subpaths of the underlying Append/MergeAppend plan node if they reference postgres_fdw foreign tables. This optimization works only for SELECT plans when limit option is represented as a constant or a parameter. It is also restricted for Append paths, corresponding to a partitioned table.

Default: on.

Specifies the default number of sharded table partitions.

A sharded table has this default number of partitions unless num_parts is specified in CREATE TABLE.

To allow scaling, shardman.num_parts should be larger than the expected maximum number of nodes in a Shardman cluster.

Possible values are from 1 to 1000.

Default: 20.

Specifies the replication group ID of a Shardman node.

This parameter is set by Shardman utilities when the node is added to the cluster and should never be changed manually.

Default: -1.

Sets Shardman to propagate all DDL statements that touch sharded and global relations to all replication groups.

When this parameter is on, Shardman broadcasts all supported utility statements touching sharded and global relations to all replication groups. It is not recommended to turn this off. This parameter is not honored when set in configuration file.

Default: on.

Enables cluster-wide synchronization of configuration parameters set by user. The configuration parameters are propagated with each remote query.

Default: on.

Excludes the options not to be propagated to a remote cluster.

Default: local system configuration parameters that are never synchronized.

Switches between modes of query planning/execution. Possible values are none and text.

none means that query planning/execution will not use the Silk transport.

text means that the text query representation is transferred via Silk transport for remote execution.

Default: none.

Silk transport uses IP address specified by this parameter for node identification. If the host name is specified, it is resolved and the first IP address corresponding to this name, is used.

Default: node hostname.

The Silk routing daemon listens for incoming connections on this IP address. If the host name is specified, it is resolved and the first IP address corresponding to this name, is used.

Default: node hostname.

The Silk routing daemon listens for incoming connections on this port. This setting should be the same for all nodes in the Shardman cluster.

Default: 8888.

Enables tracing of queries passing through the Silk pipeline. The tracing results can be accessed by running the EXPLAIN command with ANALYZE set to ON.

Default: off.

Number of background workers allocated for distributed execution. This setting must be less than max_worker_processes (including auxilary postgres worker processes).

Default: 2.

Sets the base maximum amount of memory to be used by a Silk stream (as a buffer size) before writing to the temporary disk files. If this value is specified without units, the default is kilobytes.

Note that most queries can perform multiple fetch operations at the same time, usually one for each remote partition of a sharded table, if any. Each fetch operation is generaly allowed to use as much memory as this value specifies before it starts to write data into temporary files. Also, several running sessions can execute such operations concurrently. Therefore, the total memory used by Silk for buffers could be many times the value of shardman.silk_stream_work_mem and is correlated with shardman.num_parts. Thus, mind this fact when choosing the value.

Default: 16MB.

Number of rows in a chunk that the silkworm worker extracts and sends to the multiplexer as a result, per one reading iteration.

Default: 100.

Size of queue for jobs that have not yet been assigned to the silkworm multiplexer workers, in case all the workers are busy.

Default: 1024.

Maximum message size that can be transfered with Silk, in bytes. Note that this parameter does not limit the maximum size of the result returned by the query. It only affects messages sent to workers. Increasing this parameter value will result in a proportional memory increase consumed by Shardman. It is strongly recommended to use the default value unless there is an urgent need.

Default: 524288.

Handshake timeout between multiplexers of different nodes, in seconds.

Default: 3.

Enables additional CPU scheduling settings for multiplexer processes (silkroad and silkworm).

When this parameter is fifo, Shardman assigns scheduling policy SCHED_FIFO for processes silkroad and each of silkworm. It assigns the static schediling priority (sched_priority) to values shardman.silkroad_sched_priority and shardman.silkworm_sched_priority respectively.

This setting improves silk transport performance while it operates under heavy CPU load.

Note that postgres binary need to have CAP_SYS_NICE capability to use this option. If no appropriate capability was assigned to the process, enabling this setting will have no effect. The capability must be assigned to postgres binary before starting postgres. Postgres (i.e. processes silkroad and silkworm) will apply scheduling options once during service start. You need restart postgres service if you want to change scheduling options.

Default: none.

Value of static scheduling priority (sched_priority) for silkroad process. It only makes sense if shardman.silk_scheduler_mode equals to 'fifo'.

Default: 2.

Value of static scheduling priority (sched_priority) for silkworm processes (the same value for each of them). It only makes sense if shardman.silk_scheduler_mode equals to 'fifo'.

Default: 1.

Enables pinning of multiplexer processes (silkroad and silkworm) to CPU cores to eliminate negative effects of thread's cross-cpu migration.

When this parameter is true, silkroad process will be pinned to the first available CPU core and silkworm processes (all of them) will pinned to all available CPU cores except the first one.

This setting improves silk transport performance while it operates under heavy CPU load.

Note that postgres binary need to have CAP_SYS_NICE capability to use this option. If no appropriate capability was assigned to the process, enabling this setting will have no effect. The capability must be assigned to postgres binary before starting postgres. Postgres (i.e. processes silkroad and silkworm) will apply affinity options once during service start. You need restart postgres service if you want to change affinity options.

Default: false.

Controls the mode of handling read events. It has three possible values: none, round_robin, and shortest_job_first.

The none mode means no control nor additional overhead. Yet in this case, the channel may become occupied by just one distributed query.

The round_robin mode means the events created earlier are the first ones to be processed, for each event loop. If enabled, all the backends are grouped, and the client backends are prioritized over the other.

The shortest_job_first mode means full control over the traffic. If enabled, all the backends are grouped, and the client backends are prioritized over the others, along with the workers with the least session traffic.

Default: round_robin.

Enables or disables the metrics with prefix transferred_ and time-based metrics (with prefixes read_efd_, write_efd_, and sort_time_). If disabled, these metrics have 0 values.

Default: off.

Enables or disables Silk logging.

Default: off.

Defines the Silk message categories to be traced.

Default:streams, routing, events.

Name of the database that all Silk workers connect to.

Default: postgres.

shardman.monitor_interval is deprecated and acts as noop.

Use shardman.monitor_dxact_interval instead.

Interval between checks for outdated prepared transactions.

The Shardman monitor background process wakes up every shardman.monitor_dxact_interval seconds and attempts to check and resolve any prepared transactions that did not complete and became outdated for some reason. To resolve these transactions, the Shardman monitor process determines the coordinator of the transaction and requests the transaction status from the coordinator. Based on the status of the transaction, Shardman monitor will either roll back or commit the transaction.

To disable the prepared transaction resolution logic, set shardman.monitor_dxact_interval to 0.

Default: 5 (seconds).

Each cluster node freezes its own xmin value for csn_snapshot_defer_time seconds to support global transactions. Large csn_snapshot_defer_time values can negatively impact the performance. Shardman monitor has a routine that every shardman.monitor_trim_csnxid_map_interval seconds updates xmin on all nodes to the minimum possible value (taking into account active transactions).

The background routine will run on only one node in the Shardman cluster. Note that this will give an additional load on this node.

To disable such updates, set shardman.monitor_trim_csnxid_map_interval to 0.

Default: 5 (seconds).

Maximum allowed age of prepared transactions before a resolution attempt.

During the resolution of a prepared transaction, Shardman monitor determines whether the transaction is outdated or not. A transaction becomes outdated if it was prepared more than shardman.monitor_dxact_timeout seconds ago.

Default: 5 (seconds).

Specifies the minimum delay between xmin updates on all nodes. See shardman.monitor_trim_csnxid_map_interval for more information.

Possible values are from 1 to 600.

Default: 5.

Interval between checks for distributed deadlock conditions.

The Shardman monitor background process wakes up every shardman.monitor_deadlock_interval seconds and searches for distributed deadlocks in the cluster. It gathers information about mutual locks from all nodes and looks for circular dependencies between transactions. If it detects a deadlock, it resolves it by canceling one of the backend processes involved in the lock.

To disable the distributed deadlock resolution logic, set shardman.monitor_deadlock_interval to 0.

Default: 2 (seconds).

Enables remote plan caching for FDW queries produced by locally cached plans.

Default: off.

Specifies how much memory per worker can be used for remote plan caches.

Default: 0 (caches are disabled).

Specifies the buffer size for INSERT and DELETE commands executed on a global table.

Default: 64K.

The statistics for the network latency (wait time) for inter-cluster operations, in milliseconds. It can be accessed by running the EXPLAIN command with the network parameter enabled, and via the pgpro_stats view pgpro_stats_sdm_statements.

Default: on.

Enables or disables statistics collection for time spent on a transaction.

Default: off.

Enables the optimizer to generate additional non-equivalence conditions using equivalence classes.

Default: off.

Enables the optimizer to generate additional conditions from the IN () expression.

Default: off.

Specifies whether the sharded statements are tracked and aggregated by pgpro_stats.

Default: on.

Sets the maximum number of nodes that are tracked by pgpro_stats for query fragments.

It actually sets the maximum amount of the status entries that pgpro_stats can store for the pgpro_stats_sdm_stats_updated function. It does not affect the statistics tracking itself.

Default: 2048.

Sets algorithm for transport compression during statistics transferring between nodes.

Transport compression is used to compress statistical entries passed from the shard nodes to the coordinator. The possible values are pglz, zlib, lz4, zstd or off.

Default: pglz.

Enables or disables statistics collection for wait counters by enabling or disabling functions that calculate metrics of wait events.

Default: off.

Enables or disables statistics collection the invalidation messages by enabling or disabling functions that calculate metrics of invalidation messages.

If disabled, the pgpro_stats_inval_status view is empty.

Default: off.

Enables or disables statistics collection for resource usage counters by enabling or disabling functions that calculate metrics of OS resource usage.

Default: off.

Enables or disables Shardman-specific statements processing. This parameter has three possible values. none with no processing, normalized (default) with generalized statements being processed, and all with all statements being processed.