From bad529683e808abb32c9c93d86f7ae143d32907d Mon Sep 17 00:00:00 2001 From: Wei Cao Date: Mon, 4 May 2026 06:12:12 +0800 Subject: [PATCH] [style-harmonize] generalize CONFIG GET to engine-neutral runtime readback in reconfigure-version-skew James (Oracle TL) post-merge review on PR #47 (commit 4367296663): 'CONFIG GET' is Redis/Valkey-specific, but the silent regression detection methodology should be cross-engine. Suggested generalization to 'engine-specific runtime readback' with engine examples. This fixup adds an engine-neutral readback command table in chapter 5 showing the runtime readback command/source per engine: - Valkey / Redis: CONFIG GET - MariaDB / MySQL: SHOW VARIABLES / SELECT @@param - PostgreSQL: SHOW / current_setting / pg_reload_conf - Oracle: SHOW PARAMETER / v$parameter - SQL Server: sys.configurations / sp_configure - OceanBase: __all_sys_parameter / SHOW PARAMETERS Plus generalizes 3 strategic mentions from 'CONFIG GET' to 'engine readback (e.g. CONFIG GET / v$parameter / SHOW VARIABLES)' style: - chapter 1 silent regression definition (line 40) - chapter 2 KB version inference clue (line 85) - chapter 5 actionable verification rule (line 156) Trap T4 'CONFIG SET silent +OK' kept as Redis/Valkey-specific because it's a genuine engine-specific behavior, not a generalization candidate. Other CONFIG GET mentions in chapter 7/8 left because they appear in Redis/Valkey-specific examples / test matrices. This is exactly the cross-engine generalization westonnnn requested to be visible in parent docs (msg=ea854a7a / 8c0b2e62 cross-engine usage annotation convention). --- docs/addon-reconfigure-version-skew-guide.md | 23 ++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/addon-reconfigure-version-skew-guide.md b/docs/addon-reconfigure-version-skew-guide.md index 7736cbb..4883e8d 100644 --- a/docs/addon-reconfigure-version-skew-guide.md +++ b/docs/addon-reconfigure-version-skew-guide.md @@ -37,7 +37,7 @@ addon 同一份 chart 部署在不同 KB 版本上，行为分歧需要 addon - **legacy reload 路径**：`paramsdef.yaml` / `ParametersDefinition` 里的 `reloadAction.shellTrigger`；KB 1.0.x / 1.1.x 的主推路径，1.2 main 进入 deprecated / 移除窗口 - **CMPD reconfigure 路径**：`ComponentDefinition.spec.configs[].reconfigure.exec`；KB 1.2 main 的主推路径，对 1.0.x / 1.1.x 控制器在多数情况下被忽略 -- **silent regression**：reconfigure OpsRequest 报 `Succeed`、controller hash 收口、但 valkey/redis runtime 的 `CONFIG GET` 仍返回旧值；跨版本演化里最常见的 trap 形态 +- **silent regression**：reconfigure OpsRequest 报 `Succeed`、controller hash 收口、但**引擎 runtime 实际值仍是旧值**（valkey/redis 用 `CONFIG GET` 读，Oracle 用 `v$parameter`，MariaDB 用 `SHOW VARIABLES`，等等 — 见 chapter 5 cross-engine readback 表）；跨版本演化里最常见的 trap 形态 - **fan-out 语义**：reconfigure 是只在 primary 上执行（KB 默认）还是分发到所有 pod（addon 显式 `targetPodSelector: All`） - **version band**：指 KB 的 release tag 区间，例如 1.0.x / 1.1.x / 1.2.x（含 main）；不同 version band 的接口契约可能不一致 @@ -82,7 +82,7 @@ addon 同一份 chart 部署在不同 KB 版本上，行为分歧需要 addon **最强的 ground truth**：**直接 deploy 到目标 KB 版本上发起一次 minimum reconfigure OpsRequest**，观察： - controller phase（Succeed / Failed） - live `ParametersDefinition` / `ComponentParameter` / `OpsRequest` 状态 -- runtime `CONFIG GET` 实际值（**这条最关键**，下面 chapter 5 详述） +- runtime engine readback 实际值（**这条最关键**，下面 chapter 5 详述；具体命令按引擎选 — Redis/Valkey `CONFIG GET` / Oracle `v$parameter` / MariaDB `SHOW VARIABLES` / SQL Server `sys.configurations` / OceanBase `__all_sys_parameter`） ## chapter 3：目标 KB 版本会走哪条路径 — controller 角度的判定 @@ -139,7 +139,22 @@ target KB version? |---|---|---| | controller | `OpsRequest=Succeed`、`ComponentParameter=Succeed`、live config-hash 收口 | — | | addon action | `reload-parameter.sh` exit 0、reload action log 无 error | — | -| runtime（**唯一可信**） | — | 在每个数据 pod 上 `redis-cli CONFIG GET ` 直接读 runtime 值，对照 desired | +| runtime（**唯一可信**） | — | 在每个数据 pod 上做 **engine-specific runtime readback** 直接读 runtime 值，对照 desired | + +### Engine-specific runtime readback 命令对照（cross-engine reference） + +verification 应用层必须用每个引擎自己的 runtime 读取通道；以下是常用引擎的 readback 入口（Per James msg=54af835d cross-engine generalization input）： + +| Engine | Runtime readback command / source | Notes | +|---|---|---| +| Valkey / Redis | `valkey-cli CONFIG GET ` / `redis-cli CONFIG GET ` | 注意 `CONFIG SET` 静默 +OK 失败语义（见 trap T4） | +| MariaDB / MySQL | `SHOW VARIABLES LIKE ''` 或 `SELECT @@` | 区分 GLOBAL vs SESSION scope | +| PostgreSQL | `SHOW ` 或 `SELECT current_setting('')` | 部分参数 reload 后 `pg_reload_conf()` 才生效 | +| Oracle | `SHOW PARAMETER ` (sqlplus) 或 `SELECT value FROM v$parameter WHERE name=''` | 区分 spfile vs runtime；部分参数 require restart（不属于 dynamic 参数） | +| SQL Server | `SELECT * FROM sys.configurations WHERE name=''` 或 `EXEC sp_configure ''` | `RECONFIGURE` 后 `value_in_use` 才反映 runtime | +| OceanBase | `SELECT * FROM oceanbase.__all_sys_parameter WHERE name=''` 或 `SHOW PARAMETERS LIKE ''` | 区分 cluster-level / tenant-level scope | + +**通用原则**：runtime ground truth 必须从 engine **本身**读，不能只看 controller phase / addon action exit code / config-hash 收口。本 guide 后续 chapter 用 `CONFIG GET` 当 example, 实际跑 verify 时按上表换成对应引擎的 readback。 **typical silent regression 现场**： - chart 是 1.0/1.1 风格（仅 paramsdef.reloadAction），部署到 1.2 main controller @@ -153,7 +168,7 @@ target KB version? - cmpd reconfigure 被忽略 ok - 但如果 reload-parameter.sh 在两条路径下行为不一致（参数名转换、authentication、retry 逻辑），会有微妙 drift -**actionable**：跨版本部署时 reconfigure 验证至少要 **bring-down 到 runtime CONFIG GET 一次**，不能只看 controller phase。 +**actionable**：跨版本部署时 reconfigure 验证至少要 **bring-down 到 runtime engine readback 一次**（per chapter 5 上方表格选对应引擎命令；Redis/Valkey 用 `CONFIG GET`，Oracle 用 `SHOW PARAMETER` / `v$parameter`，等等），不能只看 controller phase。 ## chapter 6：portability 套路 — 双写 / 单写 / template variant