Readyset Installation Guide for MySQL

This guide walks you through how to run Readyset using Docker, connecting to an existing primary database.

0. Make sure you can connect to your primary database.

Ensure your database and user are configured for Readyset to operate by following the database reference documentation.

Readyset needs to be installed on a machine that can communicate with your primary database. To check to make sure that it can, you can run the following on that instance:

mysql -u <username> -p -h <database host>

If you are able to successfully make the connection, you are ready to move onto the next steps.

1. Ensure you have sufficient disk space and memory for Readyset

Any tables referenced by queries that you would like to cache need to be pulled into Readyset. Before installing Readyset, ensure that the machine that you are installing it on has sufficient disk space and memory to replicate the base tables and cache queries.

2. Download the Readyset Docker image

To download the Readyset Docker image from DockerHub, run the following command in your terminal:

docker pull readysettech/readyset

3. Run Readyset

First, find your primary database's connection string.

It should look something like this:

mysql://<username>:<password>@<host>:<port>/<db_name>

By default, Readyset will import all tables. If you'd like to import all database tables, you can skip defining a REPLICATION_TABLES environment variable. If, however, you'd only like to import a a subset of your database, then you need to define the list of tables you want to pull into Readyset as a comma-separated list: <schema>.<table>, <schema>.<table2>. Note, this is optional - you can import all tables too by ignoring this command line flag. If you'd like to import all of the tables in a given schema, you can specify everything as follows: <schema name>.*.

Now, you're ready to start Readyset. In your terminal, run the following command:

docker run -d -p 3307:3307 -p 6034:6034         \
--name readyset                                 \
-e UPSTREAM_DB_URL=<database connection string> \
-e REPLICATION_TABLES=<specific tables or omit> \
-e LISTEN_ADDRESS=0.0.0.0:3307                  \
readysettech/readyset:latest

As you can see above, Readyset is exposing two ports: 3307 and 6034. The Readyset process will listen for query traffic on port 3307 and emits telemetry on port 6034 via a /metrics endpoint. All -e environment variables can be placed into a file and referenced via Docker's --env-file flag if you'd rather simply your command line experience.

Readyset will then connect to your database and replicate specified tables (i.e. all or the explictly defined ones). Depending on how large these tables are and the network connection between Readyset and your database, this could take between seconds and hours.

To check whether the tables have been imported, run the following:

docker logs readyset

While the snapshot is ongoing, you will see many log messages related to snapshotting progress.

Once you see:

INFO replicators::noria_adapter: Streaming replication started

Readyset is ready to start caching queries.

Alternatively, you can log into the Readyset shell and run

SHOW READYSET STATUS;

Look at the Snapshot Status column. If snapshotthing successfully completed, it'll report Completed.

Now Readyset is ready to start caching queries.

Next Steps

As a next step, you can connect to Readyset from a database shell or connect from your application.