Configuration Options

The IP address/hostname and port that Readyset listens on.

This option accepts a list of addresses. Specify --address multiple times, or pass a comma-separated list via the LISTEN_ADDRESS environment variable, to bind several sockets at once (for example, to listen on both an IPv4 and an IPv6 interface).

If not set, Readyset follows the upstream database's own listening convention:

• MySQL adapter: [::]:3307, a dual-stack IPv6 wildcard socket, which accepts both IPv4 and IPv6 clients on Linux. Matches MySQL 8.0's bind_address = '*' default.
• PostgreSQL adapter: 127.0.0.1:5433 and [::1]:5433, separate IPv4 and IPv6 loopback sockets. Matches PostgreSQL's listen_addresses = 'localhost' default.

To listen only on IPv6, pass an IPv6 address explicitly. For example, use --address '[::1]:5433' for loopback, or --address '[::]:5433' for all interfaces. To listen on a specific pair of IPv4 and IPv6 interfaces, pass --address twice:

readyset --address 10.0.0.5:5433 --address '[2001:db8::1]:5433'

Or, via the environment:

LISTEN_ADDRESS='10.0.0.5:5433,[2001:db8::1]:5433' readyset

Env variable: LISTEN_ADDRESS

Comma list of allowed username:password pairs to authenticate database connections with. If not set, the username and password in --upstream-db-url will be used. If --allow-unauthenticated-connections is passed, this will be ignored.

Env variable: ALLOWED_USERS

Enables Readyset's automatic shallow caching mode: every previously-unseen SELECT becomes a candidate for an automatically-created shallow cache, with no CREATE CACHE statement or /*rs+ ... */ hint required.

This flag is shorthand for setting --cache-mode to shallow and --query-caching to inrequestpath. It is mutually exclusive with both of those flags; pass them explicitly only when you need finer-grained control than this convenience flag provides.

Bootstrap and introspection traffic (system-schema queries, session/user variables, non-deterministic functions like NOW() or RAND()) is filtered out by an eligibility filter and routed straight to the upstream database without creating a cache.

Default: off

Env variable: AUTO_CACHE

The URL for Snapshotting and Replication from Readyset to the upstream database. If omitted, --upstream-db-url will be used.

Env variable: CDC_DB_URL

Sets up a separate listener address dedicated to cache DDL statements (like CREATE CACHE, DROP CACHE, DROP ALL CACHES, and hint-based cache creation).

• Not set (default): Cache DDL statements are allowed from any connection on the main listening address.
• Set: Readyset opens a second listener on the specified address. Only connections arriving on that address are allowed to run cache DDL statements. Connections on the main --address listener will have cache DDL rejected.

This is an access control mechanism — it lets you expose the main proxy address to application traffic while restricting cache management operations to a separate, potentially internal-only, address.

Env variable: CACHE_DDL_ADDRESS

Controls how CREATE CACHE (without an explicit DEEP or SHALLOW modifier) behaves.

Possible values:

• deep: Always attempt a streaming dataflow (deep) cache. Queries unsupported by the dataflow engine return an error.
• shallow: Always create a TTL-based shallow cache.
• deep-then-shallow: Attempt a deep cache first; if the query is unsupported by the dataflow engine, fall back to a shallow cache automatically.

Default: shallow

Env variable: CACHE_MODE

If supplied, clean up assets for the supplied deployment. If an upstream URL is supplied, also clean up various assets related to upstream (replication slot, etc.).

Default coalescing window (in milliseconds) for shallow caches when no COALESCE clause is specified in CREATE SHALLOW CACHE. During this window, concurrent requests for the same query and parameter values are coalesced on a cache miss: only the first request goes to upstream, and the rest wait for its result.

Set to 0 to disable coalescing by default.

Default: 5000

Env variable: DEFAULT_COALESCE_MS

Default TTL (in milliseconds) for shallow cache entries when no POLICY TTL clause is specified in CREATE SHALLOW CACHE. Each cache entry is considered stale after this duration since its last access.

Default: 10000

Env variable: DEFAULT_TTL_MS

The operational mode for this Readyset process.

Possible values:

• standalone: Run an entire deployment of Readyset in this process (Adapter and Server).
• embedded-readers: Store cached query results with this Adapter instead of the Server. To use this option, you must pass --no-readers when starting readyset-server.
• adapter: Run this process as an Adapter with no locally cached data (requires a Server to be run separately).

Default: standalone

Env variable: DEPLOYMENT_MODE

Disable running CREATE PUBLICATION for PostgreSQL. If this flag is set a publication named readyset for all tables should be added manually on the primary server before streaming replication will start.

Env variable: DISABLE_CREATE_PUBLICATION

Disable running DDL Streaming Replication setup for PostgreSQL. If this flag is set the DDL setup SQL queries will need to be manually run on the primary server before streaming replication will start.

Env variable: DISABLE_SETUP_DDL_REPLICATION

Don't sent anonymous telemetry data to Readyset.

Env variable: DISABLE_TELEMETRY

Disable verification of SSL certificates supplied by the upstream database (PostgreSQL only; ignored for MySQL). Ignored if --upstream-db-url is not passed.

Env variable: DISABLE_UPSTREAM_SSL_VERIFICATION

Require GTID-based replication for MySQL. When set, Readyset uses Global Transaction Identifiers (GTIDs) instead of traditional binlog file/position tracking for replication. If the upstream MySQL server does not have gtid_mode=ON, replication fails rather than falling back to binlog file/position.

This flag is opt-in because many MySQL servers have gtid_mode=ON without requiring GTID-based replication. By defaulting to binlog file/position, existing deployments are unaffected and operators can choose when to switch.

When not set, Readyset uses binlog file/position regardless of the server's gtid_mode setting.

Default: false

Env variable: REQUIRE_GTID

Maximum number of row events to skip during GTID crash recovery within a single transaction. When Readyset restarts after a crash mid-transaction, it replays from the pending GTID and skips row events that were already applied. If the pending event index exceeds this limit, replication fails assuming the persisted state is corrupt. Increase this value if the upstream database has transactions with more than 10,000 row events.

Default: 10000

Env variable: MAX_GTID_ROWS_TO_SKIP

Allow fully materialized nodes to be persisted to disk. Fully materialized nodes are populated during startup and stored in memory by default. They can use significant amount of memory and are not candidate for evictions. This feature stores them on disk instead. Full materialized nodes are removed during shutdown.

Default: false

Possible values: true, false

Env variable: FEATURE_MATERIALIZATION_PERSISTENCE

Enable support for mixing equality and range comparisons on query parameters.

Default: false

Possible values: true, false

Env variable: FEATURE_MIXED_COMPARISONS

Enable support for Pagination in dataflow.

Default: false

Possible values: true, false

Env variable: FEATURE_PAGINATION

Enable support for Post-Lookup (queries which do extra work after the lookup into the reader). If the Top K feature is disabled, Post-Lookup can still provide support for some queries supported by Top K, albeit with lower performance.

Default: false

Possible values: true, false

Env variable: FEATURE_POST_LOOKUP

Enable support for straddled joins (joins with partial keys traced to both parents).

Default: false

Possible values: true, false

Env variable: FEATURE_STRADDLED_JOINS

Enable support for Top K in dataflow.

Default: false

Possible values: true, false

Env variable: FEATURE_TOPK

Print help information.

Allow Readyset to start even if the file descriptor limit (ulimit -n) is below the minimum requirement. If set, Readyset still raises the soft limit to min(our requirement, hard limit). It just doesn't treat (our requirement > hard limit) as a fatal error.

Env variable: IGNORE_ULIMIT_CHECK

Optional path to a directory where log files will be placed. Logs will be written to readyset.log within this directory. If set, logs will rollover based on the chosen log_rotation policy, which defaults to daily. Readyset must have write permissions.

Env variable: LOG_DIR

Optional full log filename where logs will be appended. Incompatible with log rotation.

Env variable: LOG_FILE

Format to use when emitting log events. See the docs for the tracing library for details.

Possible values: "compact", "full", "pretty", "json"

Default: "full"

Env variable: LOG_FORMAT

The severity level(s) to include in Readyset logs. Messages at the specified and more severe levels are included. For example, when set to INFO, messages at the INFO, WARN, and ERROR levels are included.

Possible values, from most to least severe:

• ERROR: Used for hazardous situations that require special handling, where normal operation cannot proceed as expected.
• WARN: Used for potentially hazardous situations that may require special handling.
• INFO: Used for information messages that do not require action.
• DEBUG: Used for lower priority information.
• TRACE: Used for very low priority, often extremely verbose information.

Default: INFO

Env variable: LOG_LEVEL

Log Rotation policy to use if a log file is set. Defaults to daily. Does nothing if no log file is set.

Possible values: "daily", "hourly", "minutely", "never"

Default: "daily"

Env variable: LOG_ROTATION

The maximum number of relations that will be snapshotted in parallel from the upstream.

Default: Number of available cores - 1.

Env variable: MAX_PARALLEL_SNAPSHOT_TABLES

The amount of memory, in bytes, available to the Readyset Server.

This memory limit accounts for all memory use, including partial materializations (i.e., queries for which Readyset stores only part of the result set), full materializations (i.e., queries for which Readyset stores the entire result set), and other parts of the Readyset process (e.g., RocksDB).

Once memory usage surpasses this limit, Readyset starts evicting cache entries from partial materializations based on the --eviction-policy.

Default: 0 (unlimited)

Env variable: READYSET_MEMORY_LIMIT

The IP address/hostname and port of the Prometheus endpoint for Readyset metrics.

This option is ignored unless --prometheus-metrics is passed. It determines the Prometheus endpoint for the Readyset adapter; the --external-address option for the readyset-server command determines the Prometheus endpoint for the Readyset server.

Default: 0.0.0.0:6034

Env variable: METRICS_ADDRESS

Authentication method to use for MySQL client connections. This controls which authentication plugin Readyset advertises during the MySQL handshake.

Possible values: mysql_native_password, caching_sha2_password

Default: caching_sha2_password

Env variable: MYSQL_AUTHENTICATION_METHOD

See MySQL Authentication for details on each method and migration guidance.

Disable colors in all log output.

Env variable: NO_COLOR

Authentication method to use for PostgreSQL clients.

Possible values: cleartext, scram-sha-256

Default: scram-sha-256

Env variable: POSTGRES_AUTHENTICATION_METHOD

Controls when Readyset migrates a query (compiles it into a cache) relative to the request that uses it.

Possible values:

• explicit: Caches are only created in response to an explicit CREATE CACHE statement or a /*rs+ CREATE SHALLOW CACHE */ hint. Queries that have not been explicitly cached are proxied to the upstream database. This is the default and the only non-experimental value.
• inrequestpath: Every previously-unseen SELECT becomes a candidate for cache creation as it is executed. Combined with --cache-mode shallow, this produces Readyset's automatic shallow caching mode; the --auto-cache flag is shorthand for that combination.
• async: Experimental.

Mutually exclusive with --auto-cache.

Default: explicit

Env variable: QUERY_CACHING

The PKCS#12 identity file (certificate and key) used by Readyset for establishing TLS connections as the server. Readyset will not accept TLS connections if there is no identity file specified.

Env variable: READYSET_IDENTITY_FILE

Password for the PKCS#12 identity file used by Readyset for establishing TLS connections as the server. If not provided, Readyset will try using an empty string to unlock the identity file.

Env variable: READYSET_IDENTITY_FILE_PASSWORD

Hostname to report when registering as a replica with the upstream database (MySQL only). If not set, no hostname will be reported

Env variable: REPORT_HOST

Password to report when registering as a replica with the upstream database (MySQL only). If not set, no password will be reported

Env variable: REPORT_PASSWORD

Port to report when registering as a replica with the upstream database (MySQL only). If not set, no port will be reported

Env variable: REPORT_PORT

Username to report when registering as a replica with the upstream database (MySQL only). If not set, no username will be reported

Env variable: REPORT_USER

Server ID to use when registering as a replication follower with the upstream database.

This can be used to differentiate different Readyset deployments connected to the same upstream DB.

For Postgres, this ends up being a suffix of the replication slot or resnapshot replication slot, which have prefixes of readyset_ and readyset_resnapshot_, respectively. Since a replication slot is limited by Postgres to a length of 63 bytes, this server id must be 43 bytes or fewer.

For MySQL, this must be parseable as a u32 that is unique across the replication topology.

Env variable: REPLICATION_SERVER_ID

By default, Readyset attempts to snapshot and replicate all tables in the database specified in --upstream-db-url. However, if the queries you want to cache in Readyset access only a subset of tables in the database, you can use this option to limit the tables Readyset snapshots and replicates. Filtering out tables that will not be used in caches will speed up the snapshotting process.

This option accepts a comma-separated list of <schema>.<table> (specific table in a schema) or <schema>.* (all tables in a schema) for Postgres and <database>.<table> for MySQL.

Only tables specified in the list will be eligible to be used by caches.

Env variable: REPLICATION_TABLES

By default, Readyset attempts to snapshot and replicate all tables in the database specified in --upstream-db-url. However, if you know the queries you want to cache in Readyset won't access a subset of tables in the database, you can use this option to limit the tables Readyset snapshots and replicates. Filtering out tables that will not be used in caches will speed up the snapshotting process.

This option accepts a comma-separated list of <schema>.<table> (specific table in a schema) or <schema>.* (all tables in a schema) for Postgres and <database>.<table> for MySQL.

Tables specified in the list will not be eligible to be used by caches.

Env variable: REPLICATION_TABLES_IGNORE

Polling interval, in seconds, for the replication-lag reporter. Controls how often Readyset queries the upstream's current replication position and, if --replication-heartbeat is enabled, writes a heartbeat timestamp to the upstream.

The value is surfaced through readyset.replication_status and the Prometheus gauge readyset_replicator.replication_lag.

Default: 1

Possible values: integer in the range 1–30

Env variable: REPLICATION_LAG_INTERVAL

Enable pt-heartbeat-style time-based replication lag measurement. When enabled, Readyset maintains a small heartbeat table on the upstream and measures the round-trip time for a written timestamp to appear back through the replication stream. The result is exposed as heartbeat_staleness_seconds in readyset.replication_status and as the Prometheus gauge readyset_replicator.replication_staleness_seconds.

Requires write access to the upstream so Readyset can create and update the heartbeat table (readyset._heartbeat on Postgres, _readyset_heartbeat on MySQL). If write access is not granted, a warning is logged, heartbeat is disabled, and byte/transaction lag reporting is unaffected.

The poll cadence is shared with --replication-lag-interval.

Default: false

Possible values: true, false

Env variable: REPLICATION_HEARTBEAT

Opportunistic read-your-writes window (in milliseconds). Applies only outside transactions: after any write on a session, reads on that same session bypass every cache for this many milliseconds. In-transaction routing is unaffected and is governed by the per-cache transaction policy (NEVER (default), ALWAYS, or UNTIL WRITE). See Read-your-writes for how the two layers fit together.

Pick a window long enough to cover the gap between a write completing on the upstream and Readyset's cache reflecting it. Too short and a freshly-written row may still be served stale; too long and reads that could safely hit the cache go upstream instead.

Unset (the default) disables the feature; the read path then never pays the clock comparison. A value of 0 also disables it.

Default: unset (disabled)

Env variable: OPPORTUNISTIC_RYW_MS

Specifies the maximum number of queries to sample per second.

Default: 100

Env variable: SAMPLER_MAX_QUERIES_PER_SECOND

Specifies the maximum number of retries for a mismatched query.

Default: 6

Env variable: SAMPLER_MAX_RETRIES

Specifies the maximum queue size for the background query sampler. Exceeding this size will cause the adapter to not add new queries to the sampler queue.

Default: 1024

Env variable: SAMPLER_QUEUE_CAPACITY

Specifies the delay between retries for a mismatched query.

Default: 10000

Env variable: SAMPLER_RETRY_DELAY_MS

Specifies the sample rate for the background query sampler.

Default: 0.001

Env variable: SAMPLER_SAMPLE_RATE

A string to be included as a comment in snapshot queries for MySQL. The provided value is automatically enclosed within the delimiters /* and */. Provide only the raw comment text without any comment markers.

Default: ""

Env variable: SNAPSHOT_QUERY_COMMENT

Maximum number of concurrent background refresh queries allowed across all shallow caches. This value acts as a guardrail to prevent shallow cache refreshes from overwhelming your upstream database. It also determines the upper bound on the number of database connections used for refreshes.

Even with this limit in place, choose REFRESH EVERY intervals carefully on individual caches. High-cardinality caches with many distinct parameter values can generate significant query volume even at modest per-key refresh rates.

Default: 100

Env variable: SHALLOW_REFRESH_WORKERS

Path to the PEM or DER root certificate that the upstream database connection will trust.

Default: System root store

Env variable: SSL_ROOT_CERT

The path to the directory where Readyset stores replicated table data.

Default: Current working directory

Env variable: STORAGE_DIR

Specifies the types of client connections permitted to connect to Readyset.

Possible values:

• optional: Client can use either plain or TLS connections
• disabled: TLS connections are disabled
• required: Only TLS connections are allowed

Default: optional

Env variable: TLS_MODE

The URL for connecting Readyset to to the upstream database. This connection URL includes the username and password for Readyset to authenticate with as well as the database to snapshot/replicate.

Env variable: UPSTREAM_DB_URL

Run startup verification checks and exit, without starting the Readyset adapter.

• On success: prints a confirmation message to stdout and exits with code 0.
• On failure: prints the error(s) to stderr and exits with a non-zero code.

Use this flag in CI/CD pipelines or deployment scripts to validate your Readyset configuration before the adapter goes live.

By default (when neither --verify nor --verify-skip is set), Readyset still runs the same checks at startup. A failure will stop the process, but output goes to the log rather than stdout/stderr.

Cannot be used together with --verify-skip.

Env variable: VERIFY

Skip all startup verification checks and proceed directly to starting the Readyset adapter.

Cannot be used together with --verify.

Env variable: VERIFY_SKIP