Readyset

The readyset command starts the Readyset server and adapter as a single process on a single machine or starts the Readyset adapter (with the --deployment-mode=adapter option) as a distinct process from the Readyset server (readyset-server).

The default and recommended deployment method of Readyset is to run server and adaptor in a single process.

Usage

Start the Readyset Server and Adapter as a single process:

readyset [OPTIONS]

Start the Readyset Adapter as a distinct process, after starting the Readyset Server:

readyset-server [OPTIONS]
readyset --deployment-mode=adapter [OPTIONS]

View help:

readyset --help

Options

`--address`, `-a`

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

Default: 3307 for MySQL deployments and 5433 for PostgreSQL deployments.

Env variable: LISTEN_ADDRESS

`--authority-address`

The IP address/hostname and port of the external authority. Readyset clusters support Consul as the external authority.

This option is ignored when --deployment-mode with value other than standalone (the default) is passed. In that case, the Readyset Server and Adapter are run as a single process, and no external authority is required.

Env variable: AUTHORITY_ADDRESS

`--cdc-db-url`

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

💡

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

Env variable: CDC_DB_URL

`--deployment`

A unique identifier for the Readyset deployment.

Default: tmp-readyset

Env variable: DEPLOYMENT

`--deployment-mode`

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-telemetry`

Don't sent anonymous telemetry data to Readyset.

Env variable: DISABLE_TELEMETRY

`--help`, `-h`

Print help information.

`--log-format`

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

`--log-path`

Default: None Optional path to write logs to. If set, logs will rollover based on the chosen log_rotation policy, which defaults to daily. Readyset must have write permissions to the provided path. Logs will be written to readyset.log-<suffix> within this path, with suffix depending on the rotation policy.

Env variable: LOG_PATH

`--log-rotation`

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

`--log-level`

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.

The TRACE level is not available for official releases of Readyset (opens in a new tab), or for binaries built with the --release flag. Also, --log-level can be set to a comma-separated list of directives for debugging during development. For the directive syntax, see the docs for the tracing library (opens in a new tab).

Default: INFO

Env variable: LOG_LEVEL

`--memory-limit`, `-m`

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

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

💡

For production deployments, start by setting this to 60-80% of the machine's total memory. Then run the system under load, observe, and increase or decrease as needed.

`--metrics-address`

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

`--password`

The password for authenticating connections to Readyset. This can differ from the password in the database connections string in --upstream-db-url.

This option is ignored when --allow-unauthenticated-connections is passed.

Default: The username for the upstream database in --upstream-db-url.

Env variable: ALLOWED_PASSWORD

`--prometheus-metrics`

Output Readyset metrics to the Prometheus endpoint at <metrics address>/metrics. The metrics address is defined by --metrics-address.

Env variable: PROMETHEUS_METRICS

`--query-log`

Include query-specific execution details in Prometheus metrics. Enabled by default if PROMETHEUS_METRICS is set.

To use this option, you must pass `--prometheus-metrics as well.

Env variable: QUERY_LOG

`--query-log-ad-hoc`

Include execution details for ad-hoc queries in Prometheus metrics. Ad-hoc queries are those that do not use parameters. Enabled by default if PROMETHEUS_METRICS is set.

To use this option, you must pass `--query-log as well.

Env variable: QUERY_LOG_AD_HOC

`--replication-tables`

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

`--replication-tables-ignore`

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

`--ssl-root-cert`

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

Default: System root store

Env variable: SSL_ROOT_CERT

`--storage-dir`

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

Default: Current working directory

Env variable: STORAGE_DIR

`--tracing-host`

When using open telemetry, the IP address/hostname and port of the telemetry server to send traces/spans to.

Env variable: TRACING_HOST

`--tracing-sample-percent`

The percent of traces to send to the open telemetry server.

To use this option, you must set --tracing-host.

Possible values: Between 0.0 and 100.0

Default: 0.01

Env variable: TRACING_SAMPLE_PERCENT

`--upstream-db-url`

The URL for connecting Readyset to to the upstream database. This connection URL includes the username and password for Readyset to authenticate with and will be used by your application to connect to Readyset and proxy queries back to upstream database

Env variable: UPSTREAM_DB_URL

💡

Special characters that may be interpreted as dividers of the connection string (e.g. @, :, /, #) must be percent-encoded, including in passwords. For example, password# should be password%23.

`--username`, `-u`

The username for authenticating connections to Readyset. This can differ from the username in the database connections string in --upstream-db-url.

This option is ignored when --allow-unauthenticated-connections is passed.

Default: The username for the upstream database in --upstream-db-url.

Env variable: ALLOWED_USERNAME

`--version`, `V`

Print Readyset version information. See the example below.

💡

You can also use the custom SHOW READYSET VERSION SQL command to print Readyset version information.

Examples

These examples focus on running a standard Readyset deployment (i.e., Readyset Server and Adapter running as a single process on a single machine). For running a distributed Readyset deployment, see the readyset-server examples.

Start Readyset

readyset \
--upstream-db-url="postgresql://<db user>:<db password>@<db address>:5432/<database>" \
--database-type=postgresql \
--username=<readyset user> \
--password=<readyset password> \
>> logs/readyset.log 2>&1 &

Output metrics to Prometheus

To output Readyset metrics to Prometheus, pass --metrics-address and --prometheus-metrics. To include query-specific execution details, pass --query-log and --query-log-ad-hoc as well.

readyset \
--upstream-db-url="postgresql://<db user>:<db password>@<db address>:5432/<database>" \
--username=<readyset user> \
--password=<readyset password> \
--prometheus-metrics \
--metrics-address=<prometheus address> \
>> logs/readyset.log 2>&1 &

Print version information

To print Readyset version information, pass the --version flag:

readyset --version

readyset
release-version: beta-2023-02-15
commit_id:       0f40cee0b4583d559d247077b7c140dce6977f00
platform:        x86_64-unknown-linux-gnu
rustc_version:   rustc 1.64.0-nightly (fe3342816 2022-08-01)
profile:         release
opt_level:       3

Alternatively, you can connect a SQL shell to Readyset and run the following custom SQL command:

SHOW READYSET VERSION;

Readyset      |             Version Information
--------------------+---------------------------------------------
release version    | beta-2023-02-15
commit id          | 0f40cee0b4583d559d247077b7c140dce6977f00
platform           | x86_64-unknown-linux-gnu
rustc version      | rustc 1.64.0-nightly (fe3342816 2022-08-01)
profile            | release
optimization level | 3
(6 rows)

Overview Readyset Server

Readyset

Usage

Options

--address, -a

--authority-address

--cdc-db-url

--deployment

--deployment-mode

--disable-telemetry

--help, -h

--log-format

--log-path

--log-rotation

--log-level

--memory-limit, -m

--metrics-address

--password

--prometheus-metrics

--query-log

--query-log-ad-hoc

--replication-tables

--replication-tables-ignore

--ssl-root-cert

--storage-dir

--tracing-host

--tracing-sample-percent

--upstream-db-url

--username, -u

--version, V