PD Configuration File

The PD configuration file supports more options than command-line parameters. You can find the default configuration filehere.

This document only describes parameters that are not included in command-line parameters. Checkherefor the command line parameters.

Tip

If you need to adjust the value of a configuration item, refer toModify the configuration.

`name`

The unique name of a PD node
Default value:"pd"
To start multiply PD nodes, use a unique name for each node.

`data-dir`

The directory in which PD stores data
Default value:default.${name}"

`client-urls`

The list of client URLs to be listened to by PD
Default value:"http://127.0.0.1:2379"
When you deploy a cluster, you must specify the IP address of the current host asclient-urls(for example,"http://192.168.100.113:2379"). If the cluster runs on Docker, specify the IP address of Docker as"http://0.0.0.0:2379".

`advertise-client-urls`

The list of advertise URLs for the client to access PD
Default value:"${client-urls}"
In some situations such as in the Docker or NAT network environment, if a client cannot access PD through the default client URLs listened to by PD, you must manually set the advertise client URLs.
For example, the internal IP address of Docker is172.17.0.1, while the IP address of the host is192.168.100.113and the port mapping is set to-p 2380:2380. In this case, you can setadvertise-client-urlsto"http://192.168.100.113:2380". The client can find this service through"http://192.168.100.113:2380".

`peer-urls`

The list of peer URLs to be listened to by a PD node
Default value:"http://127.0.0.1:2380"
When you deploy a cluster, you must specifypeer-urlsas the IP address of the current host, such as"http://192.168.100.113:2380". If the cluster runs on Docker, specify the IP address of Docker as"http://0.0.0.0:2380".

`advertise-peer-urls`

The list of advertise URLs for other PD nodes (peers) to access a PD node
Default:"${peer-urls}"
In some situations such as in the Docker or NAT network environment, if the other nodes (peers) cannot access the PD node through the default peer URLs listened to by this PD node, you must manually set the advertise peer URLs.
For example, the internal IP address of Docker is172.17.0.1, while the IP address of the host is192.168.100.113and the port mapping is set to-p 2380:2380. In this case, you can setadvertise-peer-urlsto"http://192.168.100.113:2380". The other PD nodes can find this service through"http://192.168.100.113:2380".

`initial-cluster`

The initial cluster configuration for bootstrapping
Default value:"{name}=http://{advertise-peer-url}"
For example, ifnameis "pd", andadvertise-peer-urlsis"http://192.168.100.113:2380",initial-clusteris"pd=http://192.168.100.113:2380".

If you need to start three PD servers, theinitial-clustermight be:


                
                 pd1=http://192.168.100.113:2380, pd2=http://192.168.100.114:2380, pd3=192.168.100.115:2380

`initial-cluster-state`

The initial state of the cluster
Default value:"new"

`initial-cluster-token`

Identifies different clusters during the bootstrap phase
Default value:"pd-cluster"
If multiple clusters that have nodes with same configurations are deployed successively, you must specify different tokens to isolate different cluster nodes.

`lease`

The timeout of the PD Leader Key lease. After the timeout, the system re-elects a Leader.
Default value:3
Unit: second

`quota-backend-bytes`

The storage size of the meta-information database, which is 8GiB by default
Default value:8589934592

`auto-compaction-mod`

The automatic compaction modes of the meta-information database
Available options:periodic(by cycle) andrevision(by version number).
Default value:periodic

`auto-compaction-retention`

The time interval for automatic compaction of the meta-information database whenauto-compaction-retentionisperiodic. When the compaction mode is set torevision, this parameter indicates the version number for the automatic compaction.
Default value: 1h

`force-new-cluster`

Determines whether to force PD to start as a new cluster and modify the number of Raft members to1
Default value:false

`tso-update-physical-interval`

The interval at which PD updates the physical time of TSO.
In a default update interval of TSO physical time, PD provides at most 262144 TSOs. To get more TSOs, you can reduce the value of this configuration item. The minimum value is1ms.
Decreasing this configuration item might increase the CPU usage of PD. According to the test, compared with the interval of50ms,CPU usageof PD will increase by about 10% when the interval is1ms.
Default value:50ms
Minimum value:1ms

pd-server

Configuration items related to pd-server

`server-memory-limit`New in v6.6.0

Warning

This configuration is an experimental feature. It is not recommended to use it in production environments.

The memory limit ratio for a PD instance. The value0means no memory limit.
Default value:0
Minimum value:0
Maximum value:0.99

`server-memory-limit-gc-trigger`New in v6.6.0

Warning

This configuration is an experimental feature. It is not recommended to use it in production environments.

The threshold ratio at which PD tries to trigger GC. When the memory usage of PD reaches the value ofserver-memory-limit* the value ofserver-memory-limit-gc-trigger, PD triggers a Golang GC. Only one GC is triggered in one minute.
Default value:0.7
Minimum value:0.5
Maximum value:0.99

`enable-gogc-tuner`New in v6.6.0

Warning

This configuration is an experimental feature. It is not recommended to use it in production environments.

Controls whether to enable the GOGC Tuner.
Default value:false

`gc-tuner-threshold`New in v6.6.0

Warning

This configuration is an experimental feature. It is not recommended to use it in production environments.

The maximum memory threshold ratio for tuning GOGC. When the memory exceeds this threshold, i.e. the value ofserver-memory-limit* the value ofgc-tuner-threshold, GOGC Tuner stops working.
Default value:0.6
Minimum value:0
Maximum value:0.9

`flow-round-by-digit`New in TiDB 5.1

Default value: 3
PD rounds the lowest digits of the flow number, which reduces the update of statistics caused by the changes of the Region flow information. This configuration item is used to specify the number of lowest digits to round for the Region flow information. For example, the flow100512will be rounded to101000because the default value is3. This configuration replacestrace-region-flow.

Note

If you have upgraded your cluster from a TiDB 4.0 version to the current version, the behavior offlow-round-by-digitafter the upgrading and the behavior oftrace-region-flow在升级之前默认情况下是一致的。This means that if the value oftrace-region-flowis false before the upgrading, the value offlow-round-by-digitafter the upgrading is 127; if the value oftrace-region-flowistruebefore the upgrading, the value offlow-round-by-digitafter the upgrading is3.

`min-resolved-ts-persistence-interval`New in v6.0.0

Determines the interval at which the minimum resolved timestamp is persistent to the PD. If this value is set to0, it means that the persistence is disabled.
Default value: Before v6.3.0, the default value is"0s". Starting from v6.3.0, the default value is"1s", which is the smallest positive value.
Minimum value:0
Unit: second

Note

For clusters upgraded from v6.0.0~v6.2.0, the default value ofmin-resolved-ts-persistence-intervaldoes not change after the upgrade, which means that it will remain"0s". To enable this feature, you need to manually change the value of this configuration item.

security

Configuration items related to security

`cacert-path`

The path of the CA file
Default value: ""

`cert-path`

隐私加强邮件的路径(PEM)文件that contains the X509 certificate
Default value: ""

`key-path`

The path of the PEM file that contains the X509 key
Default value: ""

`redact-info-log`New in v5.0

Controls whether to enable log redaction in the PD log
When you set the configuration value totrue, user data is redacted in the PD log.
Default value:false

`log`

Configuration items related to log

`level`

Specifies the level of the output log
Optional value:"debug","info","warn","error","fatal"
Default value:"info"

`format`

The log format
Optional value:"text","json"
Default value:"text"

`disable-timestamp`

Whether to disable the automatically generated timestamp in the log
Default value:false

`log.file`

Configuration items related to the log file

`max-size`

The maximum size of a single log file. When this value is exceeded, the system automatically splits the log into several files.
Default value:300
Unit: MiB
Minimum value:1

`max-days`

The maximum number of days in which a log is kept
If the configuration item is not set, or the value of it is set to the default value 0, PD does not clean log files.
Default value:0

`max-backups`

The maximum number of log files to keep
If the configuration item is not set, or the value of it is set to the default value 0, PD keeps all log files.
Default value:0

`metric`

Configuration items related to monitoring

`interval`

The interval at which monitoring metric data is pushed to Prometheus
Default value:15s

`schedule`

Configuration items related to scheduling

`max-merge-region-size`

Controls the size limit ofRegion Merge. When the Region size is greater than the specified value, PD does not merge the Region with the adjacent Regions.
Default value:20
Unit: MiB

`max-merge-region-keys`

Specifies the upper limit of theRegion Mergekey. When the Region key is greater than the specified value, the PD does not merge the Region with its adjacent Regions.
Default value:200000

`patrol-region-interval`

Controls the running frequency at whichreplicaCheckerchecks the health state of a Region. The smaller this value is, the fasterreplicaCheckerruns. Normally, you do not need to adjust this parameter.
Default value:10ms

`split-merge-interval`

Controls the time interval between thesplitandmergeoperations on the same Region. That means a newly split Region will not be merged for a while.
Default value:1h

`max-snapshot-count`

Controls the maximum number of snapshots that a single store receives or sends at the same time. PD schedulers depend on this configuration to prevent the resources used for normal traffic from being preempted.
Default value value:64

`max-pending-peer-count`

Controls the maximum number of pending peers in a single store. PD schedulers depend on this configuration to prevent too many Regions with outdated logs from being generated on some nodes.
Default value:64

`max-store-down-time`

The downtime after which PD judges that the disconnected store cannot be recovered. When PD fails to receive the heartbeat from a store after the specified period of time, it adds replicas at other nodes.
Default value:30m

`max-store-preparing-time`New in v6.1.0

Controls the maximum waiting time for the store to go online. During the online stage of a store, PD can query the online progress of the store. When the specified time is exceeded, PD assumes that the store has been online and cannot query the online progress of the store again. But this does not prevent Regions from transferring to the new online store. In most scenarios, you do not need to adjust this parameter.
Default value:48h

`leader-schedule-limit`

The number of Leader scheduling tasks performed at the same time
Default value:4

`region-schedule-limit`

The number of Region scheduling tasks performed at the same time
Default value:2048

`enable-diagnostic`New in v6.3.0

Controls whether to enable the diagnostic feature. When it is enabled, PD records the state during scheduling to help diagnose. If enabled, it might slightly affect the scheduling speed and consume more memory when there are many stores.
Default value: Starting from v7.1.0, the default value is changed fromfalsetotrue. If your cluster is upgraded from a version earlier than v7.1.0 to v7.1.0 or later, the default value does not change.

`hot-region-schedule-limit`

Controls the hot Region scheduling tasks that are running at the same time. It is independent of the Region scheduling.
Default value:4

`hot-region-cache-hits-threshold`

The threshold used to set the number of minutes required to identify a hot Region. PD can participate in the hotspot scheduling only after the Region is in the hotspot state for more than this number of minutes.
Default value:3

`replica-schedule-limit`

The number of Replica scheduling tasks performed at the same time
Default value:64

`merge-schedule-limit`

The number of theRegion Mergescheduling tasks performed at the same time. Set this parameter to0to disableRegion Merge.
Default value:8

`high-space-ratio`

The threshold ratio below which the capacity of the store is sufficient. If the space occupancy ratio of the store is smaller than this threshold value, PD ignores the remaining space of the store when performing scheduling, and balances load mainly based on the Region size. This configuration takes effect only whenregion-score-formula-versionis set tov1.
Default value:0.7
Minimum value: greater than0
Maximum value: less than1

`low-space-ratio`

The threshold ratio above which the capacity of the store is insufficient. If the space occupancy ratio of a store exceeds this threshold value, PD avoids migrating data to this store as much as possible. Meanwhile, to avoid the disk space of the corresponding store being exhausted, PD performs scheduling mainly based on the remaining space of the store.
Default value:0.8
Minimum value: greater than0
Maximum value: less than1

`tolerant-size-ratio`

Controls thebalancebuffer size
Default value:0(automatically adjusts the buffer size)
Minimum value:0

`enable-cross-table-merge`

Determines whether to enable the merging of cross-table Regions
Default value:true

`region-score-formula-version`New in v5.0

Controls the version of the Region score formula
Default value:v2
Optional values:v1andv2. Compared to v1, the changes in v2 are smoother, and the scheduling jitter caused by space reclaim is improved.

Note

If you have upgraded your cluster from a TiDB 4.0 version to the current version, the new formula version is automatically disabled by default to ensure consistent PD behavior before and after the upgrading. If you want to change the formula version, you need to manually switch through thepd-ctlsetting. For details, refer toPD Control.

`store-limit-version`New in v7.1.0

Warning

Setting this configuration item to"v2"is an experimental feature. It is not recommended to use it in production environments.

Controls the version of the store limit formula
Default value:v1
Value options:
- v1: In v1 mode, you can manually modify thestore limitto limit the scheduling speed of a single TiKV.
- v2: (experimental feature) In v2 mode, you do not need to manually set thestore limitvalue, as PD dynamically adjusts it based on the capability of TiKV snapshots. For more details, refer toPrinciples of store limit v2.

`enable-joint-consensus`New in v5.0

Controls whether to use Joint Consensus for replica scheduling. If this configuration is disabled, PD schedules one replica at a time.
Default value:true

`hot-regions-write-interval`New in v5.4.0

The time interval at which PD stores hot Region information.
Default value:10m

Note

The information about hot Regions is updated every three minutes. If the interval is set to less than three minutes, updates during the interval might be meaningless.

`hot-regions-reserved-days`New in v5.4.0

Specifies how many days the hot Region information is retained.
Default value:7

`replication`

Configuration items related to replicas

`max-replicas`

The number of replicas, that is, the sum of the number of leaders and followers. The default value3means 1 leader and 2 followers. When this configuration is modified dynamically, PD will schedule Regions in the background so that the number of replicas matches this configuration.
Default value:3

`location-labels`

The topology information of a TiKV cluster
Default value:[]
Cluster topology configuration

`isolation-level`

The minimum topological isolation level of a TiKV cluster
Default value:""
Cluster topology configuration

`strictly-match-label`

Enables the strict check for whether the TiKV label matches PD'slocation-labels.
Default value:false

`enable-placement-rules`

Enablesplacement-rules.
Default value:true
SeePlacement Rules.

`label-property`

Configuration items related to labels

`key`

The label key for the store that rejected the Leader
Default value:""

`value`

The label value for the store that rejected the Leader
Default value:""

`dashboard`

Configuration items related to theTiDB Dashboardbuilt in PD.

`tidb-cacert-path`

The path of the root CA certificate file. You can configure this path when you connect to TiDB's SQL services using TLS.
Default value:""

`tidb-cert-path`

The path of the SSL certificate file. You can configure this path when you connect to TiDB's SQL services using TLS.
Default value:""

`tidb-key-path`

The path of the SSL private key file. You can configure this path when you connect to TiDB's SQL services using TLS.
Default value:""

`public-path-prefix`

When TiDB Dashboard is accessed behind a reverse proxy, this item sets the public URL path prefix for all web resources.
Default value:/dashboard
Donotmodify this configuration item when TiDB Dashboard is accessed not behind a reverse proxy; otherwise, access issues might occur. SeeUse TiDB Dashboard behind a Reverse Proxyfor details.

`enable-telemetry`

决定是否启用遥测collection feature in TiDB Dashboard.
Default value:false
SeeTelemetryfor details.

`replication-mode`

Configuration items related to the replication mode of all Regions. SeeEnable the DR Auto-Sync modefor details.

Controllor

This section describes the configuration items that are built into PD forResource Control.

`degraded-mode-wait-duration`

Time to wait to trigger the degradation mode. Degradation mode means that when the Local Token Bucket (LTB) and Global Token Bucket (GTB) are lost, the LTB falls back to the default resource group configuration and no longer has a GTB authorization token, thus ensuring that the service is not affected in the event of network isolation or anomalies.
Default value: 0s
The degradation mode is disabled by default.

`request-unit`

The following are the configuration items about theRequest Unit (RU).

`read-base-cost`

Basis factor for conversion from a read request to RU
Default value: 0.25

`write-base-cost`

Basis factor for conversion from a write request to RU
Default value: 1

`read-cost-per-byte`

Basis factor for conversion from read flow to RU
Default value: 1/(64 * 1024)
1 RU = 64 KiB read bytes

`write-cost-per-byte`

Basis factor for conversion from write flow to RU
Default value: 1/1024
1 RU = 1 KiB write bytes

`read-cpu-ms-cost`

Basis factor for conversion from CPU to RU
Default value: 1/3
1 RU = 3 millisecond CPU time

PD Configuration File

name

data-dir

client-urls

advertise-client-urls

peer-urls

advertise-peer-urls

initial-cluster

initial-cluster-state

initial-cluster-token

lease

quota-backend-bytes

auto-compaction-mod

auto-compaction-retention

force-new-cluster

tso-update-physical-interval

pd-server

server-memory-limitNew in v6.6.0

server-memory-limit-gc-triggerNew in v6.6.0

enable-gogc-tunerNew in v6.6.0

gc-tuner-thresholdNew in v6.6.0

flow-round-by-digitNew in TiDB 5.1

min-resolved-ts-persistence-intervalNew in v6.0.0

security

cacert-path

cert-path

key-path

redact-info-logNew in v5.0

log

level

format

disable-timestamp

log.file

max-size

max-days

max-backups

metric

interval

schedule

max-merge-region-size

max-merge-region-keys

patrol-region-interval

split-merge-interval

max-snapshot-count

max-pending-peer-count

max-store-down-time

max-store-preparing-timeNew in v6.1.0

leader-schedule-limit

region-schedule-limit

enable-diagnosticNew in v6.3.0

hot-region-schedule-limit

hot-region-cache-hits-threshold

replica-schedule-limit

merge-schedule-limit

high-space-ratio

low-space-ratio

tolerant-size-ratio

enable-cross-table-merge

region-score-formula-versionNew in v5.0

store-limit-versionNew in v7.1.0

enable-joint-consensusNew in v5.0

hot-regions-write-intervalNew in v5.4.0

hot-regions-reserved-daysNew in v5.4.0

replication

max-replicas

location-labels

isolation-level

strictly-match-label

enable-placement-rules

label-property

key

value

dashboard

tidb-cacert-path

tidb-cert-path

tidb-key-path

public-path-prefix

enable-telemetry

replication-mode

Controllor

`name`

`data-dir`

`client-urls`

`advertise-client-urls`

`peer-urls`

`advertise-peer-urls`

`initial-cluster`

`initial-cluster-state`

`initial-cluster-token`

`lease`

`quota-backend-bytes`

`auto-compaction-mod`

`auto-compaction-retention`

`force-new-cluster`

`tso-update-physical-interval`

`server-memory-limit`New in v6.6.0

`server-memory-limit-gc-trigger`New in v6.6.0

`enable-gogc-tuner`New in v6.6.0

`gc-tuner-threshold`New in v6.6.0

`flow-round-by-digit`New in TiDB 5.1

`min-resolved-ts-persistence-interval`New in v6.0.0

`cacert-path`

`cert-path`

`key-path`

`redact-info-log`New in v5.0

`log`

`level`

`format`

`disable-timestamp`

`log.file`

`max-size`

`max-days`

`max-backups`

`metric`

`interval`

`schedule`

`max-merge-region-size`

`max-merge-region-keys`

`patrol-region-interval`

`split-merge-interval`

`max-snapshot-count`

`max-pending-peer-count`

`max-store-down-time`

`max-store-preparing-time`New in v6.1.0

`leader-schedule-limit`

`region-schedule-limit`

`enable-diagnostic`New in v6.3.0

`hot-region-schedule-limit`

`hot-region-cache-hits-threshold`

`replica-schedule-limit`

`merge-schedule-limit`

`high-space-ratio`

`low-space-ratio`

`tolerant-size-ratio`

`enable-cross-table-merge`

`region-score-formula-version`New in v5.0

`store-limit-version`New in v7.1.0

`enable-joint-consensus`New in v5.0

`hot-regions-write-interval`New in v5.4.0

`hot-regions-reserved-days`New in v5.4.0

`replication`

`max-replicas`

`location-labels`

`isolation-level`

`strictly-match-label`

`enable-placement-rules`

`label-property`

`key`

`value`

`dashboard`

`tidb-cacert-path`

`tidb-cert-path`

`tidb-key-path`

`public-path-prefix`

`enable-telemetry`

`replication-mode`

`degraded-mode-wait-duration`

`request-unit`

`read-base-cost`

`write-base-cost`