PD: The etcd-backed scheduler that keeps TiKV regions in place

What PD actually does inside a TiKV cluster

PD is not a database and not a general scheduler. It is the control plane for TiKV, the distributed key-value store. Its job is to manage and schedule TiKV clusters. That means it decides where region replicas live, which TiKV stores are healthy, and how to balance load across them. The README states this plainly: PD manages and schedules TiKV clusters. Without TiKV, PD has nothing to schedule. It is a component, not a standalone product. If you are evaluating PD, you are really evaluating part of the TiKV ecosystem, and your decision must account for that dependency.

Embedded etcd is the fault-tolerance mechanism

The key architectural fact in the README is that PD supports fault-tolerance by embedding etcd. This is not a side detail. It means PD uses etcd's Raft consensus to replicate its own state across multiple PD nodes. In a multi-node PD deployment, if one PD dies, the others can still serve the cluster. The etcd embedding also gives PD a consistent metadata store for cluster configuration and region information. For a single-node setup, this is overkill, but the mechanism is what makes PD viable in production. The trade-off is operational complexity: you are now running an etcd cluster inside your control plane, with all the quorum and network requirements that come with Raft.

Single-node startup: real commands from the README

The README gives a concrete path to run PD on one machine. You set a HOST_IP environment variable, then launch pd-server with --name, --data-dir, --client-urls, --peer-urls, and --log-file. The example uses client-urls on port 2379 and peer-urls on 2380. You can verify it by curling the members endpoint: /pd/api/v1/members returns a JSON object with cluster_id, members, and leader. The README shows the expected response shape, which is useful if you are scripting health checks. The Docker route is similar: you can build the image locally with docker build -t pingcap/pd or pull pingcap/pd from Docker Hub. The docker run command maps ports 2379 and 2380 and uses --advertise-client-urls and --advertise-peer-urls to tell clients and peers how to reach the container from outside.

The REST API is your window into cluster state

PD exposes a REST API under /pd/api/v1. The README only shows the members endpoint, but that is enough to see the shape of the interface. The response includes cluster_id, a list of members with their peer_urls and client_urls, and a leader object. This is the kind of endpoint you would poll for readiness checks or to confirm which PD node is leading. The API also returns CORS headers, as shown in the httpie example, which means browser-based tools can call it directly. The documentation does not list every endpoint, so you will need to consult the official PD API docs for the full surface. But the members endpoint alone gives you a concrete way to verify that a single-node PD is alive and electing itself as leader.

Where PD is the wrong tool

PD is the wrong tool if you need a standalone scheduler or a generic metadata store. It is tightly coupled to TiKV. The README says it outright: PD needs to run with TiKV to work. You cannot use PD to manage regions for another storage engine, and you cannot use its etcd embedding as a general-purpose key-value database. For a single-node evaluation, PD is trivial to start, but it is not useful alone. You will need at least one TiKV instance to see any scheduling behavior. Also, the single-node configuration is not fault-tolerant. The README's example runs one PD process, and if that process dies, the cluster loses its placement driver. The embedded etcd only helps when you run multiple PD nodes.

The natural alternative: etcd itself

If you are considering PD for its etcd-based coordination, you should look at etcd directly. etcd is a distributed key-value store with Raft consensus, and it is the underlying mechanism PD uses. The difference in approach is that etcd is a general-purpose coordination service. You can store any small, critical data in it, and you get leader election and watch APIs out of the box. PD, by contrast, wraps etcd with TiKV-specific logic: region scheduling, store health tracking, and placement decisions. If your problem is just distributed coordination, etcd is simpler and more flexible. If your problem is scheduling TiKV regions, PD is the dedicated tool. The choice is not PD versus etcd; it is whether you need the scheduling layer or just the consensus layer.

Maintenance, licensing, and upgrade cost

PD is written in Go and licensed under Apache-2.0, which is permissive and does not impose copyleft obligations. That is a low-friction license for internal use or embedding. For maintenance, the build process requires Go 1.25 or later, and the make command produces pd-server, pd-ctl, and pd-recover binaries. Those three binaries hint at the operational surface: pd-ctl for control, pd-recover for disaster recovery. The release cadence is visible from the tags: v8.5.8, v8.5.7, v8.5.6, with dates in 2026. That is a stable minor version line with patch releases. The upgrade cost is tied to the TiDB ecosystem. PD versions track the TiDB release train, so you cannot upgrade PD independently without checking compatibility with your TiKV and TiDB versions. The README points to TiUP for cluster deployment, which is the standard way to manage upgrades, but the version coupling remains a real constraint.

Editorial conclusion

Adopt PD if you are running a TiKV cluster and need region scheduling and cluster metadata management with etcd-based fault tolerance. Do not adopt it as a standalone key-value store or general-purpose scheduler; it requires TiKV to be useful. Before adopting, verify the exact PD version you plan to use against your TiKV and TiDB versions, since PD releases are tied to the TiDB release train. Check the official compatibility matrix, not just the latest release tag, before production deployment.

Official sources

1. Official README
2. Project repository
3. Release notes