Introduction

Boost.Redis is a high-level Redis and Valkey client library offering APIs for Boost.Asio and Corosio. It implements the Redis protocol RESP3.

Requirements

The requirements for using Boost.Redis are:

Boost 1.84 or higher. Boost.Redis is included in Boost installations since Boost 1.84.
For the Boost.Asio API, C++17 or higher. Supported compilers include gcc 11 and later, clang 11 and later, and MSVC 14.20 and later.
For the Corosio API, C++20 or higher. Supported compilers include gcc 12 and later, clang 17 and later, MSVC 14.34 and later.
Redis 6 or higher, or Valkey (any version). The database server must support RESP3. We intend to maintain compatibility with both Redis and Valkey in the long-run.
OpenSSL.

The documentation assumes basic-level knowledge about Redis and either Boost.Asio or Corosio.

Building the library

To use the library it is necessary to include the following:

Asio
Corosio

#include <boost/redis/src.hpp>

#include <boost/redis/src/proto.hpp>
#include <boost/redis/src/corosio.hpp>

in exactly one source file in your applications. Otherwise, the library is header-only.

Boost.Redis unconditionally requires OpenSSL. Targets using Boost.Redis need to link to the OpenSSL libraries.

Tutorial

The code below uses a short-lived connection to ping a Redis server:

Asio
Corosio

#include <boost/redis/connection.hpp>
#include <boost/asio/co_spawn.hpp>
#include <boost/asio/consign.hpp>
#include <boost/asio/detached.hpp>
#include <iostream>

namespace net = boost::asio;
using boost::redis::request;
using boost::redis::response;
using boost::redis::config;
using boost::redis::connection;

auto co_main(config const& cfg) -> net::awaitable<void>
{
   auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
   conn->async_run(cfg, {}, net::consign(net::detached, conn));

   // A request containing only a ping command.
   request req;
   req.push("PING", "Hello world");

   // Response object.
   response<std::string> resp;

   // Executes the request.
   co_await conn->async_exec(req, resp);
   conn->cancel();

   std::cout << "PING: " << std::get<0>(resp).value() << std::endl;
}

#include <boost/redis/co_connection.hpp>
#include <boost/redis/config.hpp>

#include <boost/capy/ex/run_async.hpp>
#include <boost/capy/io_task.hpp>
#include <boost/capy/task.hpp>
#include <boost/capy/when_any.hpp>
#include <boost/corosio/io_context.hpp>

#include <exception>
#include <iostream>

namespace capy = boost::capy;
using namespace boost::redis;
namespace corosio = boost::corosio;

capy::io_task<> run_request(co_connection& conn)
{
   // A request containing only a ping command.
   request req;
   req.push("PING", "Hello world");

   // Response where the PONG response will be stored.
   response<std::string> resp;

   // Executes the request.
   auto [ec] = co_await conn.exec(req, resp);
   if (ec) {
      std::cout << "Error executing PING: " << ec << std::endl;
   } else {
      std::cout << "PING value: " << std::get<0>(resp).value() << std::endl;
   }

   co_return {};
}

capy::task<void> co_main()
{
   // Create a connection
   co_connection conn{co_await capy::this_coro::executor};

   // Run the connection and the PING request, in parallel
   co_await capy::when_any(run_request(conn), conn.run(config{}));
}

The roles played by the run and exec functions are:

connection::async_exec / co_connection::exec: executes the commands contained in the request and stores the individual responses in the response object. Can be called from multiple places in your code concurrently.
connection::async_run / co_connection::run: keeps the connection healthy. It takes care of hostname resolution, session establishment, health-checks, reconnection and coordination of low-level read and write operations. It should be called only once per connection, regardless of the number of requests to execute.

Introduction

Requirements

Building the library

Tutorial

Further reading