Readyset Docs

Readyset supports two MySQL authentication plugins: mysql_native_password and caching_sha2_password. The --mysql-authentication-method flag controls which plugin Readyset advertises to clients during the MySQL handshake phase.

Authentication methods

mysql_native_password

The legacy authentication plugin, used by default in MySQL 5.7 and available in MySQL 8.0. It uses a challenge-response protocol based on SHA-1 hashing. No additional infrastructure (TLS or RSA keys) is required for password exchange.

This was the default in earlier versions of Readyset and remains available for environments that have not migrated to caching_sha2_password.

caching_sha2_password

The default authentication plugin in Readyset (and in MySQL 8.0+). It is the only built-in plugin in MySQL 9.x (which removed mysql_native_password). It uses SHA-256 hashing and supports two authentication paths:

Fast auth (cache hit): If Readyset has already verified a user's password in a previous connection, it caches the password hash. Subsequent connections for the same user skip the full exchange and authenticate using only the cached hash. This is comparable in cost to mysql_native_password.
Full auth (cache miss): On the first connection for a given user (or after a restart, which clears the cache), the client must send the password encrypted with the server's RSA public key or over a TLS connection. This requires either TLS to be enabled or the client to obtain the RSA public key.

The password cache is in-memory and is cleared when Readyset restarts. The first connection after a restart always performs full authentication.

Configuration

Readyset defaults to caching_sha2_password. To use mysql_native_password instead:

readyset --mysql-authentication-method mysql_native_password [other options]

Or using the environment variable:

MYSQL_AUTHENTICATION_METHOD=mysql_native_password readyset [other options]

RSA key management

When caching_sha2_password is enabled, Readyset needs an RSA key pair for full-auth password encryption on non-TLS connections.

Auto-generated keys

By default, Readyset generates a 2048-bit RSA key pair at startup and persists it in the deployment subdirectory under --storage-dir (the storage directory defaults to the current working directory) as two files:

caching_sha2_password_private_key.pem (PKCS#1 PEM, mode 0600)
caching_sha2_password_public_key.pem (PKCS#8 PEM, mode 0644)

On subsequent starts, Readyset loads the existing key from the private key file so that the public key stays stable across restarts.

Supplying your own key

To use your own RSA key pair, place a PKCS#1 PEM-encoded private key at caching_sha2_password_private_key.pem in the deployment subdirectory before starting Readyset. Readyset loads this file at startup instead of generating a new key, and derives the public key in memory.

Retrieving the public key

Clients that connect without TLS need the server's RSA public key to encrypt their password. You can retrieve it with:

SHOW READYSET RSA PUBLIC KEY;

This returns a single row containing the PEM-encoded public key. Most MySQL client libraries request this key automatically during the handshake (for example, the --get-server-public-key option in the mysql CLI).

See the command reference for details.

Migrating from MySQL 8.x to 9.x

MySQL 9.x removed the mysql_native_password plugin entirely. Readyset defaults to caching_sha2_password, so no configuration change is needed. If you were previously overriding the authentication method to mysql_native_password, remove that override:

Remove any --mysql-authentication-method flag set to mysql_native_password (or the corresponding MYSQL_AUTHENTICATION_METHOD environment variable).
Ensure your client drivers support caching_sha2_password. Most modern MySQL connectors (MySQL Connector/J 8.0+, mysql2 for Node.js, Go mysql driver, mysqlclient for Python) support it out of the box.
If you do not use TLS, verify that your client can retrieve the RSA public key. Most drivers do this automatically, but some require an explicit option (e.g., --get-server-public-key for the mysql CLI, or allowPublicKeyRetrieval=true for JDBC).

If you use TLS between clients and Readyset, the RSA key exchange is not needed. The password is sent securely over the encrypted channel, and full auth completes without RSA.

Performance considerations

Fast auth is the common case in steady-state operation. Once a user has authenticated at least once after startup, all subsequent connections for that user use the cached hash. The performance is comparable to mysql_native_password.
Full auth occurs only on the first connection per user after a Readyset restart (or if the cache is otherwise empty for that user). The RSA encryption adds a small amount of overhead to this initial connection.
The password cache is per-process and is not shared across Readyset restarts.

MySQL Authentication