Readyset Server

The readyset-server command starts the Readyset server.

This command is used only when running the Readyset Server and Adapter as separate processes on separate machines. The default and recommended deployment method of Readyset is to run server and adaptor in a single process via readyset command.

Usage

Start the Readyset Server:

readyset-server [OPTIONS]

Start the Readyset Adapter:

readyset [OPTIONS, excluding --standalone]

View help:

readyset-server --help

Options

`--address`, `-a`

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

Env variable: LISTEN_ADDRESS

`--authority-address`

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

Env variable: AUTHORITY_ADDRESS

`--cannot-become-leader`

When running multiple Readyset Servers, prevent this Server from ever being elected as leader.

`--db-dir`

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

Default: Current working directory

Env variable: DB_DIR

`--deployment`

A unique identifier for the Readyset deployment.

Env variable: DEPLOYMENT

`--disable-telemetry`

Don't sent anonymous telemetry data to Readyset.

Env variable: DISABLE_TELEMETRY

`--external-address`

The IP address/hostname to advertise to Readyset instances running in the same deployment. This also defines the IP address/hostname of the Prometheus endpoint for Readyset metrics (opens in a new tab).

Default: Address from --address

Env variable: EXTERNAL_ADDRESS

`--external-port`, `-p`

The port to advertise to Readyset instances running in the same deployment. This also defines the port of the Prometheus endpoint for Readyset metrics (opens in a new tab).

Default: 6033

`--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, 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.

Default: INFO

Env variable: LOG_LEVEL

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

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

💡

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.

`--no-readers`

If set, this server will never run domains containing reader nodes

Pass this flag to the server instance when running a Readyset deployment in embedded readers mode (eg for high availability)

Env variable: NO_READERS=true

`--prometheus-metrics`

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

Env variable: PROMETHEUS_METRICS

`--quorum`, `-q`

For a distributed Readyset deployment with multiple Readyset Server instances, the number of Readyset Server instances. Readyset will wait until this number is reached before accepting requests.

Default: 1

Env variable: NORIA_QUORUM

`--reader-replicas`

Number of times to replicate domains that contain readers

This flag should be set to the number of adapter instances in the Readyset deployment when running in embbedded readers mode (eg for high availability)

Env variable: READER_REPLICAS

`--replication-tables`

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

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

`--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 as well as the database to snapshot/replicate.

Env variable: UPSTREAM_DB_URL

💡

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

💡

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.

`--version`, `V`

Print Readyset version information.

`--volume-id`

The volume associated with a Readyset Server.

For a distributed Readyset deployment with multiple Readyset Servers, snapshotted tables are scheduled, round-robin, onto volumes associated with Server instances. If a Server restarts, the Server must know which volume contains its portion of the snapshot.

Env variable: VOLUME_ID

Examples

These examples focus on a distributed Readyset deployment (i.e., Readyset Server and Adapter running as distinct processes and separate machines). For running a standard Readyset deployment, see the readyset examples.

Start Readyset

Start an instance of Consul to serve as the external authority for node discovery, leader election, and consensus, and to manage internal state and metrics.

Start the Readyset Server:

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

Start one or more Readyset Adapters:

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

Print version information

readyset-server --version

readyset-server
release-version: string-yyyy-mm-dd
commit_id:       de35883e248180c7e3f2f7913c0d1c2b371e53ec
platform:        aarch64-apple-darwin
rustc_version:   rustc 1.64.0-nightly (fe3342816 2022-08-01)
profile:         release
opt_level:       3

Readyset Telemetry

Readyset Server

Usage

Options

--address, -a

--authority-address

--cannot-become-leader

--db-dir

--deployment

--disable-telemetry

--external-address

--external-port, -p

--help, -h

--log-format

--log-path

--log-rotation

--log-level

--memory-limit, -m

--no-readers

--prometheus-metrics

--quorum, -q

--reader-replicas

--replication-tables

--replication-tables-ignore

--ssl-root-cert

--tracing-host

--tracing-sample-percent

--upstream-db-url

--version, V

--volume-id