Help Center/ GaussDB/ Developer Guide(Distributed_V2.0-8.x)/ Configuring GUC Parameters/ GUC Parameters/ Connection and Authentication/ Communications Library Parameters
Updated on 2025-05-29 GMT+08:00
View PDF
Share

Communications Library Parameters

This section describes parameter settings and value ranges for communications libraries.

tcp_keepalives_idle

Parameter description: Specifies the interval for transmitting keepalive signals on an OS that supports the TCP_KEEPIDLE socket option. If no keepalive signal is transmitted, the connection is in idle mode.

  • If the OS does not support TCP_KEEPIDLE, set this parameter to 0.
  • The parameter is ignored on an OS where connections are established using the UDS.
  • If this parameter is set to 0, the system value is used.
  • This parameter is not shared among different sessions. That is, different session connections may have different values.
  • The parameter value in the current session connection, not the value of the GUC copy, is displayed.

Parameter type: integer.

Unit: second

Value range: 0 to 3600

Default value: 60

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1. For example, if the value is 60 without a unit, tcp_keepalives_idle indicates 60s. If the value is 1min, tcp_keepalives_idle indicates 1 minute. If the unit is required, the value must be s, min, h, or d.

Setting suggestion: Before setting this parameter, ensure that the OS supports the TCP_KEEPIDLE socket option.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

tcp_keepalives_interval

Parameter description: Specifies the response time before retransmission on an OS that supports the TCP_KEEPINTVL socket option.

  • If the OS does not support TCP_KEEPINTVL, set this parameter to 0.
  • The parameter is ignored on an OS where connections are established using the UDS.
  • If this parameter is set to 0, the system value is used.
  • This parameter is not shared among different sessions. That is, different session connections may have different values.
  • The parameter value in the current session connection, not the value of the GUC copy, is displayed.

Parameter type: integer.

Unit: second

Value range: 0 to 180

Default value: 30

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1. For example, if the value is 60 without a unit, tcp_keepalives_interval indicates 60s. If the value is 1min, tcp_keepalives_interval indicates 1 minute. If the unit is required, the value must be s, min, h, or d.

Setting suggestion: Before setting this parameter, ensure that the OS supports the TCP_KEEPINTVL socket option.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

tcp_keepalives_count

Parameter description: Specifies the number of keepalive signals that can be waited before the GaussDB server is disconnected from the client on an OS that supports the TCP_KEEPCNT socket option.

  • If the OS does not support TCP_KEEPCNT, set this parameter to 0.
  • The parameter is ignored on an OS where connections are established using the UDS.
  • If this parameter is set to 0, the system value is used.
  • This parameter is not shared among different sessions. That is, different session connections may have different values.
  • The parameter value in the current session connection, not the value of the GUC copy, is displayed.

Parameter type: integer.

Unit: none

Value range: 0 to 100. 0 indicates that the connection is immediately broken if GaussDB does not receive a keepalive signal from the client.

Default value: 20

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Before setting this parameter, ensure that the OS supports the TCP_KEEPCNT socket option.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

tcp_user_timeout

Parameter description: Specifies the maximum duration for which the transmitted data can remain in the unacknowledged state before the TCP connection is forcibly closed when the GaussDB sends data on the OS that supports the TCP_USER_TIMEOUT socket option.

  • If the OS does not support the TCP_USER_TIMEOUT option, the value of this parameter does not take effect. The default value is 0.
  • The parameter is ignored on an OS where connections are established using the UDS.

Parameter type: integer.

Unit: ms

Value range: 0 to 3600000

Default value: 0, indicating that the value is set based on the OS.

Note that the effective result of this parameter varies according to the OS kernel.

  • For AArch64 EulerOS (Linux kernel version: 4.19), the timeout interval is the value of this parameter.
  • For x86 Euler 2.5 (Linux kernel version: 3.10), the timeout interval is not the value of this parameter but the maximum value in different ranges. That is, the timeout interval is the maximum upper limit of the total Linux TCP retransmission duration to which the value of tcp_user_timeout belongs. For example, when tcp_user_timeout is set to 40000, the total retransmission duration is 51 seconds.
    Table 1 Value of tcp_user_timeout for x86 Euler 2.5 (Linux kernel version: 3.10)

    Number of Linux TCP Retransmission Times

    Total Linux TCP Retransmission Duration Range (s)

    Example of tcp_user_timeout (ms)

    Actual Linux TCP Retransmission Duration (s)

    1

    (0.2,0.6]

    400

    0.6

    2

    (0.6,1.4]

    1000

    1.4

    3

    (1.4,3]

    2000

    3

    4

    (3,6.2]

    4000

    6.2

    5

    (6.2,12.6]

    10000

    12.6

    6

    (12.6,25.4]

    20000

    25.4

    7

    (25.4,51]

    40000

    51

    8

    (51,102.2]

    80000

    102.2

    9

    (102.2,204.6]

    150000

    204.6

    10

    (204.6,324.6]

    260000

    324.6

    11

    (324.6,444.6]

    400000

    444.6

    Note: The duration of each TCP retransmission increases exponentially with the number of retransmission times. When the duration of a TCP retransmission reaches 120 seconds, the duration of each subsequent retransmission does not change.

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Before setting this parameter, ensure that the OS supports the TCP_USER_TIMEOUT socket option.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

tcp_syn_retries

Parameter description: Specifies the number of SYN packet retransmissions due to SYN packet transmission failures in the three-way handshake for connecting to other internal nodes on the GaussDB that supports the TCP_SYNCNT socket option.

Parameter type: integer.

Unit: none

Value range: 0–127. The value 0 indicates OS-based.

Default value: 0

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value.

Risks and impacts of improper settings: If this parameter is set to a small value (greater than 0) and the network fluctuates, the number of SYN retransmissions is small. If the retransmission duration is shorter than the network recovery duration, the connection setup fails. If this parameter is set to a large value and the network is disconnected, the number of SYN retransmissions is large and the retransmission takes a long time. As a result, the overall error reporting time is prolonged.

  • If the OS does not support the TCP_SYNCNT option, setting this parameter to any value does not take effect but the value is 0 by default.
  • The parameter is ignored on an OS where connections are established using the UDS.

comm_tcp_mode

Parameter description: Specifies whether the communications library uses the TCP protocol to set up a data channel. The parameter setting takes effect after you restart the cluster.

SCTP is no longer supported. This parameter is provided for compatibility, but its value is fixed at on.

Parameter type: Boolean.

Unit: none

Value range: If this parameter is set to on for a CN, it connects to a DN using TCP. If this parameter is set to on for a DN, the DN communicates with each other using TCP.

Default value: on

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_sctp_port

Parameter description: Specifies the TCP port used to listen on data packet channels by the TCP proxy communications library.

Parameter type: integer.

Unit: none

Value range: 0–65535

Default value: 25110 (The actual value is the specified value of the port GUC parameter plus 2.)

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: You are advised not to set this parameter. Related configurations are automatically delivered during cluster installation.

Risks and impacts of improper settings: This port number is automatically allocated during cluster deployment. Do not change the parameter. If the port number is incorrectly configured, the database communication fails.

comm_control_port

Parameter description: Specifies the TCP listening port used by the TCP proxy communications library.

Parameter type: integer.

Unit: none

Value range: 0–65535

Default value: 25111 (The actual value is the specified value of the port GUC parameter plus 3.)

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: You are advised not to set this parameter. Related configurations are automatically delivered during cluster installation.

Risks and impacts of improper settings: This port number is automatically allocated during cluster deployment. Do not change the parameter. If the port number is incorrectly configured, the database communication fails.

comm_max_datanode

Parameter description: Specifies the maximum number of DNs supported by the TCP proxy communications library.

Parameter type: integer.

Unit: none

Value range: 1 to 8192

Default value: maximum number of primary DNs supported by each node.

Setting method: This parameter is a SIGHUP parameter. Set it based on instructions provided in Table 1. During scale-in, this parameter takes effect only after the cluster is restarted.

Setting suggestion: The recommended value is 256.

Risks and impacts of improper settings: If the parameter value is less than the number of DNs in the current cluster, the connection fails to be established. If the value is too large, too much memory is occupied.

comm_max_stream

Parameter description: Specifies the maximum number of concurrent data streams supported by the TCP proxy communications library. The value of this parameter must be greater than: Number of concurrent data streams x Number of operators in each stream x Square of query_dop.

Parameter type: integer.

Unit: none

Value range: 1–60000

Default value: 1024

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion:

  • You are advised not to set this parameter to a large value because this will cause high memory usage (256 bytes x comm_max_stream x comm_max_datanode). If the number of concurrent data streams is large, the query is complex and the SMP is large, resulting in insufficient memory.
  • If the process memory is sufficient, you can properly increase the value of comm_max_stream.

Risks and impacts of improper settings: If the value is too small, a large number of concurrent distributed stream queries are restricted. If the value is too large, too much memory may be occupied.

comm_max_receiver

Parameter description: Specifies the maximum number of receiver threads for the TCP proxy communications library.

Parameter type: integer.

Unit: none

Value range: 1 to 50

Default value: 4

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value to avoid thread switchover scheduling caused by excessive thread resources.

Risks and impacts of improper settings: If the value is too large, too many data receiving threads are started, wasting thread resources.

comm_quota_size

Parameter description: Specifies the maximum size of packets that can be consecutively sent by the TCP proxy communications library.

Parameter type: integer.

Unit: KB

Value range: 0 to 2048000

Default value: 1024

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1. For example, if the value is 1024 without a unit, comm_quota_size indicates 1024 KB. If the value is 1MB, comm_quota_size indicates 1 MB. The unit must be KB, MB, or GB if required.

Setting suggestion: Retain the default value. When you use a 1GE NIC, a small value ranging from 20 KB to 40 KB is recommended.

Risks and impacts of improper settings: If this parameter is set to a small value, the TCP communications library may wait for the quota during the sending and receiving phases.

comm_usable_memory

Parameter description: Specifies the maximum memory available for buffering on the TCP proxy communications library on a DN.

Parameter type: integer.

Unit: KB

Value range: 102400 to 1073741823

Default value: 4096000 (that is, 4000 MB)

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1. For example, if the value is 102400 without a unit, comm_usable_memory indicates 102400 KB. If the value is 100MB, comm_usable_memory indicates 100 MB. The unit must be KB, MB, or GB if required.

Setting suggestion: Retain the default value. Set this parameter based on the environment memory and deployment mode.

Risks and impacts of improper settings: If the value is too large, OOM occurs. If the value is too small, the performance of the TCP proxy communications library deteriorates.

comm_memory_pool

Parameter description: Specifies the size of the memory pool resources that can be used by the TCP proxy communications library on a DN.

Parameter type: integer.

Unit: KB

Value range: 102400 to 1073741823

Default value: 2048000 (that is, 2000 MB)

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1. For example, if the value is 102400 without a unit, comm_memory_pool indicates 102400 KB. If the value is 100MB, comm_memory_pool indicates 100 MB. The unit must be KB, MB, or GB if required.

Setting suggestion: Retain the default value. If the memory used by the communications library is small, set this parameter to a small value. Otherwise, set it to a large value.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_memory_pool_percent

Parameter description: Specifies the percentage of the memory pool resources that can be used by the TCP proxy communications library on a DN. This parameter is used to adaptively reserve memory used by the communications libraries.

Parameter type: integer.

Unit: none

Value range: 0 to 100

Default value: 0

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value. If the memory used by the communications library is small, set this parameter to a small value. Otherwise, set it to a large value.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_client_bind

Parameter description: Specifies whether to bind the client of the communications library to a specified IP address when the client initiates a connection.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The client is bound to a specified IP address.
  • off: The client is not bound to a specified IP address.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: If multiple IP addresses of a node in the cluster are on the same network segment, set this parameter to on. In this case, the client is bound to the IP address specified by listen_addresses. The concurrency performance of the cluster depends on the number of random ports because a port can be used by only one client at a time.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_no_delay

Parameter description: Specifies whether to use the NO_DELAY attribute of a communications library connection.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The NO_DELAY attribute is used.
  • off: The NO_DELAY attribute is not used.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Enable this parameter for delay-sensitive services and disable it for high throughput requirements. In addition, if packet loss occurs in the cluster because a large number of packets are received per second, set this parameter to off so that small packets are combined into large packets for transmission to reduce the total number of packets.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_debug_mode

Parameter description: Specifies whether to enable the debug mode of the TCP proxy communications library, that is, whether to print logs about the communication layer.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The debug logs of the communications library are printed.
  • off: The debug logs of the communications library are not printed.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: If this parameter is set to on, a large number of logs will be printed, adding extra overhead and reducing database performance. Therefore, set it to on only in debugging scenarios.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_ackchk_time

Parameter description: Specifies the duration after which the communications library server automatically triggers ACK when no data packet is received.

Parameter type: integer.

Unit: ms

Value range: 0 to 20000. 0: disabled.

Default value: 2000

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1. For example, if the value is 60 without a unit, comm_ackchk_time indicates 60 ms. If the value is 1min, comm_ackchk_time indicates 1 minute. The unit must be ms, s, min, h, or d if required.

Setting suggestion: Retain the default value.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_timer_mode

Parameter description: Specifies whether to enable the timer mode of the TCP proxy communications library, that is, whether to print timer logs in each phase of the communication layer.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The timer logs of the communications library are printed.
  • off: The timer logs of the communications library are not printed.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: If this parameter is set to on, a large number of logs will be printed, adding extra overhead and reducing database performance. Therefore, set it to on only in debugging scenarios.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

comm_stat_mode

Parameter description: Specifies whether to enable the statistics mode of the TCP proxy communications library, that is, whether to print statistics about the communication layer.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The statistics logs of the communications library are printed.
  • off: The statistics logs of the communications library are not printed.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: If this parameter is set to on, a large number of logs will be printed, adding extra overhead and reducing database performance. Therefore, set it to on only in debugging scenarios.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

enable_stateless_pooler_reuse

Parameter description: Specifies whether to enable the reuse of the pooler connection pool. After the parameter is enabled, existing idle TCP connections can be reused. The setting takes effect after the cluster is restarted.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The pooler reuse mode is enabled.
  • off: The pooler reuse mode is disabled.

Default value: on

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Synchronize the settings for CNs and DNs. If this parameter is set to off for CNs and on for DNs, the cluster communication fails. Set this parameter to the same value for CNs and DNs. Restart the cluster for the setting to take effect.

Risks and impacts of improper settings: If this parameter is disabled, the reuse granularity of the pooler connection pool decreases and the memory usage of DNs may increase.

comm_cn_dn_logic_conn

Parameter description: Specifies whether logical connections are used between CNs and DNs. The setting takes effect after the cluster is restarted.

Logical connections between CNs and DNs are no longer supported. This parameter is provided for compatibility, but its value is fixed at off.

Parameter type: Boolean.

Unit: none

Value range:

  • on: The connections between CNs and DNs are logical, with the libcomm component in use.
  • off: The connections between CNs and DNs are physical, with the libpq component in use.

Default value: off

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value.

Risks and impacts of improper settings: If this parameter is enabled, logical connections are used between CNs and DNs to eliminate the upper limit of sockets. Logical connections cause performance overhead of the communications library.

COMM_IPC

Parameter description: Specifies whether to print the packet sending and receiving status of each communication node.

Parameter type: Boolean.

Unit: none

Value range:
  • on: The function of logging packet sending and receiving status data is enabled.
  • off: The function of logging packet sending and receiving status data is disabled.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

set logging_module='on(COMM_IPC)';   -- Enable.
set logging_module='off(COMM_IPC)';   -- Disable.
show logging_module;   -- View the setting result.

Setting suggestion: If this parameter is set to on, a large number of logs will be printed, adding extra overhead and reducing database performance. Therefore, set it to on only in debugging scenarios and disable it in a timely manner.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.

COMM_PARAM

Parameter description: Specifies whether to print the session parameter settings during node communication.

Parameter type: Boolean.

Unit: none

Value range:
  • on: The function of logging the session parameter settings is enabled.
  • off: The function of logging the session parameter settings is disabled.

Default value: off

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

set logging_module='on(COMM_PARAM)';   -- Enabled
set logging_module='off(COMM_PARAM)';   -- Disabled
show logging_module;   -- View the setting result.

Setting suggestion: If this parameter is set to on, a large number of logs will be printed, adding extra overhead and reducing database performance. Therefore, set it to on only in debugging scenarios and disable it in a timely manner.

Risks and impacts of improper settings: Change the parameter value after fully understanding the parameter meaning and verifying it through testing.