Skip to content

feat(charts): support maxReplicationLag on mysql backends - #88

Open
viicslen wants to merge 2 commits into
ProxySQL:mainfrom
viicslen:feat/chart-max-replication-lag
Open

feat(charts): support maxReplicationLag on mysql backends#88
viicslen wants to merge 2 commits into
ProxySQL:mainfrom
viicslen:feat/chart-max-replication-lag

Conversation

@viicslen

@viicslen viicslen commented Aug 10, 2026

Copy link
Copy Markdown

Context

ProxySQLConfig's MySQLBackend has carried maxReplicationLag since the API was introduced (proxysqlconfig_types.go:120, and it's in the shipped CRD). The two standalone charts drop it — their mysql_servers row renders address/port/hostgroup/max_connections/comment only.

So operator-less users cannot shun a lagging reader at all. A replica that falls behind keeps serving stale reads instead of failing over to another host in the hostgroup, and there is no way to express otherwise through chart values.

This also leaves a gap around #16 / #24. #16 asked for drift, shunned backends and replication lag in status; #24 shipped the first two and deferred lag surfacing ("Replication-lag surfacing from the monitor schema (deferred from #16, see spec note)"). For chart users the deferred half can never show anything useful, because the configuration that produces a lag-shun does not exist in the first place. This PR is the prerequisite for that follow-up being observable on the operator-less path.

Same class of gap as #68 (standalone charts missing --reload for operator parity).

Change

One template line per chart, in files/proxysql.cnf:

max_connections={{ $b.maxConnections | default 1000 }}{{ if $b.maxReplicationLag }}, max_replication_lag={{ $b.maxReplicationLag }}{{ end }}{{ if $b.comment }}...

Both charts' values.yaml document it, and both ci/special-chars-values.yaml gain a reader carrying the field so ct install exercises it against a real ProxySQL rather than only asserting Helm renders something.

Chart versions bumped: proxysql 0.1.0 → 0.2.0, proxysql-cluster 0.2.0 → 0.3.0. Happy to drop those if you batch chart releases.

Verification

  • helm lint green on both charts
  • Renders as expected: { address="...", port=3306, hostgroup=1, max_connections=1000, max_replication_lag=5 }
  • Omitted entirely when unset — confirmed byte-identical output for an unchanged values file
  • Fed the rendered proxysql.cnf to a real proxysql binary: parses cleanly and proceeds to normal startup

Possibly worth a separate issue

While checking how lag-shunning surfaces, RuntimeState.ShunnedCount() (runtime.go:126-135) matches the status string exactly:

if status == "SHUNNED" {

ProxySQL treats lag-shunning as a distinct status. From the strings in a running proxysql binary:

1 - ONLINE, 2 - SHUNNED, 3 - OFFLINE_SOFT, 4 - OFFLINE_HARD, 5 - SHUNNED_REPLICATION_LAG

If that value reaches runtime_mysql_servers.status as written, a backend shunned for replication lag would not be counted, and shunnedBackends would read 0 during exactly the scenario #16 wanted surfaced — including for operator users who already have maxReplicationLag.

I verified the enum in the binary but could not query runtime_mysql_servers directly to observe the literal column value, so please treat this as a lead rather than a confirmed reproduction. Happy to open a separate issue or PR if it holds up.

Not included

users.mysql[] has the same shape of gap — the CRD's MySQLUser has defaultSchema (:142), the charts do not. Left out to keep this reviewable; glad to add it here or in a follow-up, whichever you prefer.


AI disclosure: this change was written with AI assistance (Claude Code). I reviewed the diff and the reasoning before opening it, and I'm accountable for the content.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added optional replication-lag limits for MySQL backends in ProxySQL Helm charts.
    • Backends exceeding configured lag can be temporarily shunned, supporting safer reader traffic and failover behavior.
    • Added configuration examples and guidance for enabling, monitoring, and disabling replication-lag limits.
  • Bug Fixes

    • Updated chart rendering to include replication-lag settings when configured.
  • Tests

    • Added chart validation coverage for backends with replication-lag thresholds.
  • Chores

    • Incremented the ProxySQL chart versions.

The ProxySQLConfig CRD has carried maxReplicationLag on MySQLBackend since the
API was introduced, but the two standalone charts drop it: their mysql_servers
row renders address/port/hostgroup/max_connections/comment only. Operator-less
users therefore cannot shun a lagging reader, and a replica that falls behind
keeps serving stale reads instead of failing over to another host in the
hostgroup.

Renders only when set, so an unchanged values file produces byte-identical
output and no existing release restarts. mysql only — pgsql_servers has no
equivalent column.

Both ci/special-chars-values.yaml files gain a reader carrying the field, so
`ct install` exercises it against a real ProxySQL rather than only asserting
that Helm renders something. Verified separately by feeding the rendered cnf to
a proxysql binary, which parses it and starts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Aug 10, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: eb7af93f-51e8-41b6-9441-02f74ad69716

📥 Commits

Reviewing files that changed from the base of the PR and between fd9c27c and fd719cd.

📒 Files selected for processing (2)
  • charts/proxysql-cluster/values.yaml
  • charts/proxysql/values.yaml
🚧 Files skipped from review as they are similar to previous changes (2)
  • charts/proxysql-cluster/values.yaml
  • charts/proxysql/values.yaml

📝 Walkthrough

Walkthrough

Both ProxySQL Helm charts now support optional maxReplicationLag values for MySQL backends. The templates render max_replication_lag when configured. Values documentation, chart-testing inputs, and chart versions were updated.

Changes

Replication-lag backend support

Layer / File(s) Summary
Configuration examples and chart releases
charts/proxysql-cluster/values.yaml, charts/proxysql/values.yaml, charts/proxysql-cluster/Chart.yaml, charts/proxysql/Chart.yaml
The values examples document maxReplicationLag, its reader-shunning behavior, monitoring requirements, and disablement conditions. Both chart versions were incremented.
Backend rendering and validation
charts/proxysql-cluster/files/proxysql.cnf, charts/proxysql/files/proxysql.cnf, charts/proxysql-cluster/ci/special-chars-values.yaml, charts/proxysql/ci/special-chars-values.yaml
Both templates conditionally render max_replication_lag. Chart-testing values add replica backends with maxReplicationLag: 5.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the addition of maxReplicationLag support for MySQL backends in the affected Helm charts.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@charts/proxysql-cluster/values.yaml`:
- Around line 53-55: The comments in charts/proxysql-cluster/values.yaml lines
53-55 and charts/proxysql/values.yaml lines 55-57 incorrectly describe the
privilege as belonging to a generic backend user. Update both descriptions to
identify ProxySQL’s monitor account and state that REPLICATION CLIENT or SLAVE
MONITOR must be granted to that account on each monitored backend.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 16a51aac-d506-4d6a-8f3c-8996d1b79c13

📥 Commits

Reviewing files that changed from the base of the PR and between ce17a8a and fd9c27c.

📒 Files selected for processing (8)
  • charts/proxysql-cluster/Chart.yaml
  • charts/proxysql-cluster/ci/special-chars-values.yaml
  • charts/proxysql-cluster/files/proxysql.cnf
  • charts/proxysql-cluster/values.yaml
  • charts/proxysql/Chart.yaml
  • charts/proxysql/ci/special-chars-values.yaml
  • charts/proxysql/files/proxysql.cnf
  • charts/proxysql/values.yaml

Comment thread charts/proxysql-cluster/values.yaml Outdated
The maxReplicationLag notes said "the backend user" needs REPLICATION
CLIENT / SLAVE MONITOR. It's ProxySQL's monitor account (monitor_username,
default "monitor") that reads replica status, and the grant is needed on
every monitored backend.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant