Readyset Configuration Options

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

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

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

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.).

The operational mode for this Readyset process.

Possible values:

• standalone: Run an entire deployment of Readyset in this process (Adapter and Server).
• embedded-readers: For a distributed Readyset deployment, store cached query results with this Adapter instead of the Server. To use this option, you must pass --no-readers and --reader-replicas 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

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 (opens in a new tab) for details.

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

Default: "full"

Env variable: LOG_FORMAT

The severity level(s) (opens in a new tab) 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 (opens in a new tab).

This option is ignored unless --prometheus-metrics is passed. Also, when running a distributed Readyset deployment, this option determines the Prometheus endpoint for the Readyset Adapter only. 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

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

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

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

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