# PD Placement Rules Known Cases

Source note: adapted from the Feishu `PD oncall handbook` <https://pingcap.feishu.cn/wiki/E5KkwI6VJiFA4nkcaVEcDhWonqu>.

## Leader Imbalance After Placement-Rule Adjustment or Large-Scale TiKV Failures

- Phenomenon:
  - After a large placement-rule change or many TiKV failures, leaders can become temporarily concentrated on stores with smaller store IDs.
- Root cause:
  - During leader transfer, PD can prefer the smallest eligible target store ID in the short term.
- Workaround:
  - Usually do nothing and allow `balance-leader-scheduler` to smooth the distribution.
- Related oncall:
  - v8.5.1 leader became significantly imbalanced after applying placement rules `TICKET-6623`

## PD Leader Transfer May Reset Placement Rules

- Phenomenon:
  - Placement rules that depend on labels configured through `pd-ctl` can be reset after PD leader transfer.
- Workaround:
  - Reapply placement rules after leader transfer.
  - Upgrade to patched versions.
- Related oncall:
  - v8.1.2 placement rule reset after leader transfer `NAID-11507` / `GTOC-7779`

## Placement Rules in SQL Can Override PD-Level Placement Rules

- Phenomenon:
  - Table-level placement rules created by SQL can override cluster-level PD placement rules instead of inheriting them.
- Key commands:

```bash
tiup ctl:<version> pd config placement-rule rule-group show
tiup ctl:<version> pd config placement-rule show
```

- Workaround:
  - Prefer placement rules in SQL on `v7.5+`.
  - If mixing SQL and PD-level rules, understand override precedence explicitly.
- Related oncall:
  - v6.5.7 asked whether placement-rule and placement rule in SQL can be mixed `TICKET-4474`

## SQL Placement Policy Can Drop Location-Label Inheritance

- Phenomenon:
  - If SQL placement policy does not set `SURVIVAL_PREFERENCES`, table-level placement can stop inheriting cluster-level location labels.
- Impact:
  - Two replicas can appear on the same physical host.
- Workaround:
  - Set `SURVIVAL_PREFERENCES`.
- Related oncall:
  - v7.5.0 replica-read and traffic-switching anomaly related to placement config `ONCALL-6944`

## Disabling Placement Rule Can Cause TiDB GC Errors

- Phenomenon:
  - If placement rules are disabled and TiDB later tries to delete placement rules during GC, PD can return `StatusPreconditionFailed`.
- Workaround:
  - Ignore if there is no functional impact.
  - Or re-enable placement rules.
- Related oncall:
  - v6.5.12 TiDB logged `delete placement-rules failed` `TICKET-5867`

## Without Isolation Labels, Two Replicas Can Land on the Same Host

- Phenomenon:
  - If isolation labels are not configured and space is tight, two replicas of one region can land on different TiKV instances on the same host.
- Workaround:
  - Configure isolation labels.
- Related oncall:
  - v5.2.1 two replicas of one region were on the same host `ONCALL-6973`