Skip to content

Connect over a Unix socket - #264

Merged
quinnj-bot[bot] merged 3 commits into
mainfrom
claude/mysql-unix-socket
Nov 16, 2026
Merged

quinnj-bot[bot] merged 3 commits into
mainfrom
claude/mysql-unix-socket

Conversation

@quinnj-bot

@quinnj-bot quinnj-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Why

MySQL.jl 2.x connects only over TCP. A local server that listens only on a Unix socket can't be reached. Today unix_socket and socket= in an option file are accepted but ignored, and protocol=:socket raises "not supported yet". Reseau has had a Unix socket client since 1.6.0 (Reseau.Unix.connect).

Change

Transport selection follows Connector/C, with one difference noted below.

Request Transport
protocol=:socket with host localhost Unix socket at unix_socket, or /tmp/mysql.sock
protocol=:socket with any other host ArgumentError (libmysqlclient: error 2047)
host localhost with a socket path (unix_socket, socket in an option file, or MYSQL_UNIX_PORT with read_env=true) that Unix socket; TCP on Windows
host localhost without a path TCP (Connector/C used /tmp/mysql.sock)
any other host, or protocol=:tcp TCP
  • TLS runs over TCP only in Reseau. Over a socket, the default ssl_mode=:preferred connects without TLS, as Connector/C does for local sockets. A setting that requires TLS raises an ArgumentError before connecting: :required, the verify modes, or ssl_ca/ssl_capath. So does bind.
  • For caching_sha2_password, a local socket counts as secure, as it does in the server and in libmysqlclient. So full authentication sends the password directly instead of using RSA. The new AuthPolicy.local_socket carries this. sha256_password still uses RSA over a socket, because the server accepts its cleartext password only over TLS. mysql_clear_password still requires :verify_identity or insecure_cleartext_auth=true.
  • Reseau.Unix.Conn joins the Transport union. To keep the union at four concrete types, which keeps transport calls statically dispatched, the test-only FaultTransport is no longer parametric. Its inner is Union{IOBuffer, Reseau.TCP.Conn}.
  • Named pipes stay unavailable, with the same clear error.
  • Reseau compat stays 1.7 (from Support passphrase and ssl_ca with ssl_capath #263); the Unix client needs 1.6.

Behavior change. An option file with socket= and host localhost, such as a stock my.cnf, used to connect over TCP. It now uses that socket, as Connector/C does. Pass protocol=:tcp to keep TCP.

Verification

  • test/protocol/unix_socket_tests.jl serves the fake peer on a real Unix socket (Sockets.listen(path)). It connects with host localhost and unix_socket, with and without protocol=:socket. The peer asks for full authentication and requires the cleartext password, and the client's trace records :full_auth_cleartext. A missing socket path raises SystemError. A policy test checks that sha256_password still requests the RSA key over a socket.
  • test/protocol/native_tests.jl covers selection: the keyword, the option file, MYSQL_UNIX_PORT, protocol, a non-localhost host, the TLS and bind errors, and Windows.
  • Live lanes on Linux share the server's socket directory with the host. They create a fresh caching_sha2_password user and log in over the socket, with :full_auth_cleartext checked on MySQL 8.4. Docker Desktop can't pass a socket through to macOS, so this check runs only on Linux CI.
  • Behavior manifest rows 168 and 209 are updated: a missing socket path is now a SystemError, and the deferred-transport row uses protocol=:pipe.

🤖 Generated with Claude Code

quinnj and others added 2 commits November 16, 2026 13:33
protocol=:socket, and host localhost with a unix_socket path (keyword,
option file, or MYSQL_UNIX_PORT with read_env), connect through
Reseau.Unix. TLS stays TCP-only; a local socket counts as a secure
transport for authentication, as in Connector/C.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
protocol=:socket needs host localhost, as in libmysqlclient. On Windows
a socket path leaves localhost on TCP. A Unix socket counts as secure for
caching_sha2_password only: the server accepts a cleartext
sha256_password only over TLS. The protocol kind is narrowed to a Symbol
before socket_path, which keeps ConnectOptions trim-safe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@quinnj-bot
quinnj-bot Bot force-pushed the claude/mysql-unix-socket branch from b5a7735 to ba204a7 Compare November 16, 2026 20:34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@quinnj quinnj left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approving. MySQL.jl can now connect through a local server's Unix socket: use unix_socket with host localhost, or protocol=:socket. TLS stays TCP-only.

A socket counts as secure for caching_sha2_password only, matching the server. sha256_password still uses RSA over a socket.

An independent review found two bugs at b5a7735: a trim failure, and sha256_password logins rejected over a socket. It also flagged two selection gaps: non-localhost hosts with protocol=:socket, and the Windows default. The fix round addressed all four, and a re-review passed at ba204a7.

Verification:

  • The live socket logins pass on Linux CI against mysql:8.4 and mariadb:11.4.
  • The full suite passed locally on 1.12, 1916/1916, with a clean trim build.
  • CI is green at 08cb272.

[review generated via AI]

@quinnj-bot
quinnj-bot Bot merged commit 27a669f into main Nov 16, 2026
17 checks passed
@quinnj-bot
quinnj-bot Bot deleted the claude/mysql-unix-socket branch November 16, 2026 21:01
@quinnj-bot quinnj-bot Bot mentioned this pull request Nov 17, 2026
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