Readyset Docs

Clients authenticate to Readyset the same way they authenticate to your upstream database: Readyset plays the server role in the client handshake and verifies the supplied credentials before accepting the connection. Which authentication methods are available depends on the client protocol, PostgreSQL or MySQL.

Allowed users

Readyset authenticates each connection against a set of allowed users. --allowed-users (env ALLOWED_USERS) is a comma-separated list of username:password pairs; the user from --upstream-db-url is accepted as well.

--allowed-users seeds the allowed-users set only on a deployment's first startup. After that the set is persisted, so later edits to --allowed-users are ignored. Manage users at runtime with ALTER READYSET ADD/MODIFY/DROP USER instead. User Management covers the whole lifecycle, from this bootstrap to runtime changes.

To inspect the users that can currently authenticate, read the readyset.users view (passwords are never exposed):

SELECT "user" FROM readyset.users;

To turn authentication off, start Readyset with --allow-unauthenticated-connections. Clients then connect without credentials, the allowed-users list is ignored, and Readyset uses the --upstream-db-url credentials for its own upstream connections. Cache authorization does not apply in this mode, because there are no client identities to authorize.

PostgreSQL

Readyset supports two PostgreSQL authentication methods for client connections. The --postgres-authentication-method flag (env POSTGRES_AUTHENTICATION_METHOD) selects which one Readyset requests during the connection handshake.

scram-sha-256

The default. Readyset requests SASL authentication and verifies the client with the SCRAM-SHA-256 challenge-response exchange, so the password is never sent over the wire. This is the same method modern PostgreSQL servers use by default, and it works with standard PostgreSQL clients and drivers without extra configuration.

Over a TLS connection, Readyset also offers channel binding (SCRAM-SHA-256-PLUS), which ties the authentication exchange to the TLS session. Clients that support channel binding negotiate it automatically.

cleartext

Readyset requests the password in cleartext and compares it directly. Because the password crosses the connection unhashed, use this method only over a TLS connection or on a trusted network.

To select it:

readyset --postgres-authentication-method cleartext [other options]

To require every client to connect over TLS, set --tls-mode to required. Readyset then rejects any non-TLS connection during the handshake.

MySQL

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.

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.

Authentication