Readyset Installation Guide for PostgreSQL

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.

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:

psql -h <ip address> -p <port> -d <database name which you want to connect> -U <username of the database server>

If you are able to successfully make the connection, you should be all set.

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:

postgres://<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 5433:5433 -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:5433                  \
readysettech/readyset:latest

As you can see above, Readyset is exposing two ports: 5433 and 6034. The Readyset process will listen for query traffic on port 5433 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.

Connecting to a locally running docker Postgres and importing all tables in the locution database, for instance, would look like this:

docker run -d -p 5433:5433 -p 6034:6034 --name readyset                            \
-e UPSTREAM_DB_URL=postgres://postgres:locution@host.docker.internal:5432/locution \
-e LISTEN_ADDRESS=0.0.0.0:5433                                                     \
readysettech/readyset:latest

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

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.