MySQL

This guide walks you through how to run Readyset Cache 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 Cache to operate by following the database reference documentation.

Readyset Cache 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 Cache

Any tables referenced by queries that you would like to cache need to be pulled into Readyset Cache. Before installing Readyset Cache, 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 Cache Docker image

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

docker pull readysettech/readyset

3. Create a Docker volume for persistent cache storage

To persist Readyset Cache's cache data across container restarts, create a Docker volume for storage. This volume will hold the cache files, preventing data loss when the container is recreated.

Run this command to create a volume named readyset_cache:

docker volume create readyset_cache

You will mount this volume into the Readyset Cache container in the next step to enable persistent cache storage.

4. Run Readyset Cache

First, find your primary database's connection string.

It should look something like this:

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

By default, Readyset Cache 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 Cache 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 Cache. 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                  \
-e STORAGE_DIR=/data/cache \
-v readyset_cache:/data/cache \
readysettech/readyset:latest

As you can see above, Readyset Cache is exposing two ports: 3307 and 6034. The Readyset Cache process will listen for query traffic on port 3307 and emits telemetry on port 6034 via a /metrics endpoint. The persistent cache storage volume is mounted at /data/cache using the -v argument, and the -e STORAGE_DIR=/data/cache argument tells Readyset Cache to write to it. 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 Cache 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 Cache 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 Cache is ready to start caching queries.

Alternatively, you can log into the Readyset Cache shell and run

SHOW READYSET STATUS;

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

Now Readyset Cache is ready to start caching queries.

Next Steps

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