Skip to content

docs: document automatic MySQL port detection - #894

Open
slayerjain wants to merge 1 commit into
mainfrom
docs/mysql-auto-port-detection
Open

docs: document automatic MySQL port detection#894
slayerjain wants to merge 1 commit into
mainfrom
docs/mysql-auto-port-detection

Conversation

@slayerjain

Copy link
Copy Markdown
Member

What has changed?

Documents automatic MySQL port detection, shipped in keploy/keploy#4389.

Keploy used to route MySQL to its parser purely by destination port — 3306 and 4000 by default, plus whatever mysqlPorts listed. MySQL on any other port (a second instance on 3307, ProxySQL on 6033, MaxScale on 4006, StarRocks on 9030, a Cloud SQL Auth Proxy) could not complete its handshake, and the application failed to connect.

Two documentation gaps made that worse than it needed to be:

  1. mysqlPorts was never documented anywhere. It existed only in the source. A user hitting the problem had no discoverable fix.
  2. Nothing described the symptom. The error users actually search for is Lost connection to server at 'handshake: reading initial communication packet', and it appeared nowhere in the docs.

Changes

running-keploy/configuration-file.md

  • Adds mysqlPorts and disableMysqlAutoDetect to the sample config block, matching what keploy config --generate now emits.
  • Adds a MySQL port detection section explaining how detection works in each mode — Keploy reads the server's handshake during Record, and recovers the port from recorded Mocks during Test (no database is running then, so the port cannot come from anywhere else).
  • Documents when either field is worth setting, and warns that disabling detection means listing every MySQL port your application uses.

keploy-explained/common-errors.md

  • Adds troubleshooting entry 12 for the stuck-handshake symptom, with the exact error string, both causes, and the fix. Cross-links to the section above.

This is a documentation-only change — no behaviour is described that isn't already merged or in review upstream.

This PR Resolves #(issue) — NA

Type of change

  • Documentation update (if none of the other choices apply).

How Has This Been Tested?

Both commands run clean locally:

  • npm run build → exits 0, [SUCCESS] Generated static files in "build", 205 documents processed, no broken-link warnings (the new relative link from the troubleshooting entry into the config reference anchor resolves).
  • npx prettier@2.8.8 --check on both files → All matched files use Prettier code style!
  • vale 3.0.3 --config=.vale.ini on both files → the only remaining alerts are on pre-existing lines I did not touch (matchType, hardcoding, xml, json, traceroute); CI runs with filter_mode: diff_context, so none of them apply to this diff. No alerts on any added line.

No screenshots attached — the change is prose and a config snippet with no new visual elements. Happy to add one of the rendered MySQL port detection section if you'd like it in the PR.

Checklist:

  • My code follows the style guidelines of this project.
  • I have performed a self-review of my own code.

Keploy now identifies MySQL on any port rather than only 3306/4000 plus
whatever mysqlPorts listed (keploy/keploy#4389). Nothing described that,
and mysqlPorts itself was never documented at all — a user whose MySQL
ran on 3307, behind ProxySQL, or on a Cloud SQL Auth Proxy hit a stuck
handshake with no discoverable fix.

Adds a "MySQL port detection" section to the configuration reference
covering how detection works in each mode (reading the server handshake
during Record, recovering the port from Mocks during Test), documents
mysqlPorts and the new disableMysqlAutoDetect field, and explains when
either is worth setting.

Adds a troubleshooting entry for the symptom users actually search for —
"Lost connection to server at 'handshake: reading initial communication
packet'" — since that error is what surfaces when detection is disabled
or the Keploy version predates it.

Signed-off-by: slayerjain <shubhamkjain@outlook.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