wsrep_sync_wait 是 galera cluster 中控制读操作等待本地写集应用/提交完成的位掩码变量，值为 0（不等待）、1（等 apply）、3（等 apply+commit）等，需按查询语义动态设置 session 级别值，不可全局设死或依赖 wsrep_causal_reads。
wsrep_sync_wait 是什么，为什么不能只看文档值
wsrep_sync_wait 是 Galera Cluster 中控制客户端读取行为的关键变量，它不决定“要不要同步”，而是决定“等不等写入在本节点可见”。它的值不是开关，而是一个位掩码（bitmask），每一位对应一种同步等待条件。比如设为 1 表示等待本节点已应用所有来自其他节点的写集；设为 3（即 1 | 2）则额外等待本节点已提交（commit）这些写集。
常见错误是直接设成 7 或 15，以为“越大全局越一致”——实际会显著拖慢读请求，尤其在跨机房或高延迟网络下，可能让 SELECT 卡住几秒。这不是 bug，是设计使然：Galera 的因果一致性靠的是写集传播+本地 apply 顺序，wsrep_sync_wait 只是暴露了其中一环的等待粒度。
- 值为
0：完全不等待，读可能看到旧数据（stale read），但最快 - 值为
1：等待本地 apply 完毕，能保证读到本节点已收到的所有写（多数场景够用） - 值为
3：再加一层 commit 等待，适合需要强 read-after-write 语义的单会话逻辑 - 值 ≥
4：涉及流控、认证队列等内部状态，极少需要，且副作用难预测
如何在应用层安全启用 wsrep_sync_wait
不能全局设死 wsrep_sync_wait，必须按查询语义动态控制。MySQL 客户端连接建立后，用 SET SESSION wsrep_sync_wait = N 设置，仅对当前 session 生效。注意：这个设置不会影响事务内已发出但未返回的查询，只对后续 SELECT 起作用。
典型使用场景是“写后立刻读”：比如用户注册后跳转到个人页，此时必须确保读到刚插入的记录。但若只是首页轮播图缓存查询，完全没必要开。
- 不要在连接池初始化时统一 SET，不同业务线程语义不同，容易互相干扰
- 避免在长事务中反复 SET/RESET，Galera 内部状态跟踪开销会上升
- PHP PDO、Python MySQLdb 等驱动需显式执行
SET SESSION，ORM 如 Django 默认不透传该变量 - 如果用代理（如 HAProxy、MaxScale），确认其不重写或丢弃
SET语句
因果一致性级别选 wsrep_causal_reads=ON 还是 wsrep_sync_wait
wsrep_causal_reads=ON 是更粗粒度的开关，它让每个读请求自动等同于 wsrep_sync_wait=1，且无法 per-session 关闭。表面看省事，实则代价固定：所有读都变慢，包括那些本来可以容忍 stale 的查询（如报表统计、日志归档）。
而 wsrep_sync_wait 是细粒度控制，你可以只在关键路径上加，其余走默认。两者不是互斥关系：wsrep_causal_reads=ON 实际就是给每个 SELECT 隐式加了 wsrep_sync_wait=1，但它绕过了你的主动判断。
- 线上建议关掉
wsrep_causal_reads，用wsrep_sync_wait按需开启 - 测试环境可开
wsrep_causal_reads=ON快速验证因果逻辑是否成立，但上线前必须切回手动控制 - 如果应用已重度依赖
wsrep_causal_reads，迁移时要逐模块检查读写耦合点，避免某处漏设导致数据错觉
监控和排障：怎么知道 wsrep_sync_wait 没白设
设了 wsrep_sync_wait 不代表生效——Galera 可能因流控（FC）、节点失联或认证失败而跳过等待逻辑。最直接的验证方式是查 SHOW STATUS LIKE 'wsrep_local_state_comment' 和 wsrep_local_recv_queue，但更实用的是观察慢日志里的 Query_time 是否出现非预期的尖峰。
一个常被忽略的坑：当节点处于 Joiner 或 Donor 状态时，wsrep_sync_wait 行为异常，可能永远阻塞或立即返回。所以必须配合集群健康检查（如 wsrep_cluster_status = Primary）再启用。
- 用
SELECT SLEEP(0.1)+SHOW STATUS LIKE 'wsrep_local_recv_queue'对比设前设后数值变化，确认队列确实在清空 - 慢日志里搜
wsrep_sync_wait相关关键词没用，它不打日志，得靠响应时间反推 - Percona Toolkit 的
pt-query-digest可聚合分析带SET SESSION wsrep_sync_wait的查询延迟分布
