Connecting to Heroku Key-Value Store

Last updated July 06, 2026

Heroku Key-Value Store (KVS) is accessible from any language with a Redis or Valkey-compatible driver, including all languages and frameworks supported by Heroku.

Connection Permissions

All Heroku Key-Value Store users are granted access to all commands within Valkey except for:

  • CONFIG
  • SHUTDOWN
  • BGREWRITEAOF
  • BGSAVE
  • SAVE
  • MOVE
  • MODULE
  • MIGRATE
  • SLAVEOF
  • REPLICAOF
  • ACL
  • DEBUG

External Connections

In addition to being available to the Heroku runtime, you can access Heroku Key-Value Store instances on the Mini and Premium tier from clients running on your local computer or elsewhere.

You can’t directly access Heroku Key-Value Store instances on the Private and Shield-tier plans from outside their Private or Shield space. See Heroku Key-Value Store and Private Spaces for external access features and instructions.

Use your instance connection string to connect to your Heroku Key-Value Store instance from any external service. You can retrieve your instance connection string via the CLI or the Heroku dashboard.

Run the heroku redis:credentials CLI command to obtain your instance connection details:

$ heroku redis:credentials redis-circular-12345 -a example-app
rediss://:pe4e08c1a6a…@ec2-18-255-255-255.eu-west-1.compute.amazonaws.com:17749

To obtain your instance’s connection string through the dashboard:

  1. Open a Heroku Key-Value Store instance from the Datastores tab, or your app’s Resources list.
  2. Select the Settings tab.
  3. Click the View Credentials button in the Datastore Credentials section.

Heroku Key-Value Store automatically includes your instance add-on’s connection strings as config vars on your app. You can also check your app’s config vars through the Heroku CLI or the Heroku dashboard to obtain your database’s connection string:

$ heroku config -a example-app | grep rediss
REDIS_URL:     rediss://:pe4e08c1a6a…@ec2-18-255-255-255.eu-west-1.compute.amazonaws.com:17749

All Heroku Key-Value Store plans require TLS connections. You must configure your client to support TLS. This process can require updating and deploying your app before returning the app to normal operation.

Heroku Key-Value Store uses self-signed certificates, which can require you to configure the verify_mode SSL setting of your Redis client.

The values in the connection string of your instance can change at any time. Make sure that your app reads your add-on config var to get the instance’s connection string. Don’t rely on the value inside or outside of your Heroku app.

Connecting in Java

The connection configuration to connect to a Heroku Key-Value Store instance depends on your Java framework. All the connection examples use the REDIS_URL config variable to determine connection information.

Spring Boot

The Heroku JVM buildpack automatically copies REDIS_URL to SPRING_REDIS_URL and SPRING_DATA_REDIS_URL at runtime for compatibility with Spring Boot apps. Define a LettuceClientConfigurationBuilderCustomizer bean to disable TLS peer verification:

@Configuration
class AppConfig {

    @Bean
    public LettuceClientConfigurationBuilderCustomizer lettuceClientConfigurationBuilderCustomizer() {
        return clientConfigurationBuilder -> {
            if (clientConfigurationBuilder.build().isUseSsl()) {
                clientConfigurationBuilder.useSsl().disablePeerVerification();
            }
        };
    }
}

Lettuce

This snippet uses the REDIS_URL environment variable to create a connection to your KVS instance with Lettuce. StatefulRedisConnection is thread-safe and you can safely use it in a multithreaded environment:

public static StatefulRedisConnection<String, String> connect() {
    RedisURI redisURI = RedisURI.create(System.getenv("REDIS_URL"));
    redisURI.setVerifyPeer(false);

    RedisClient redisClient = RedisClient.create(redisURI);
    return redisClient.connect();
}

Jedis

This snippet uses the REDIS_URL config var to create a URI. It uses the new URI to create a connection to the KVS instance with Jedis.

private static Jedis getConnection() {
    try {
        TrustManager bogusTrustManager = new X509TrustManager() {
            public X509Certificate[] getAcceptedIssuers() {
                return null;
            }

            public void checkClientTrusted(X509Certificate[] certs, String authType) {
            }

            public void checkServerTrusted(X509Certificate[] certs, String authType) {
            }
        };

        SSLContext sslContext = SSLContext.getInstance("TLS");
        sslContext.init(null, new TrustManager[]{bogusTrustManager}, new java.security.SecureRandom());

        HostnameVerifier bogusHostnameVerifier = (hostname, session) -> true;

        return new Jedis(URI.create(System.getenv("REDIS_URL")),
                sslContext.getSocketFactory(),
                sslContext.getDefaultSSLParameters(),
                bogusHostnameVerifier);

    } catch (NoSuchAlgorithmException | KeyManagementException e) {
        throw new RuntimeException("Cannot obtain Redis connection!", e);
    }
}

If you run Jedis in a multithreaded environment, such as a web server, don’t use the same Jedis instance to interact with your KVS instance. Instead, create a Jedis Pool so that the app code can check out a connection and return it to the pool when it’s done:

// The assumption with this method is that it's been called when the application
// is booting up so that a static pool has been created for all threads to use.
// e.g. pool = getPool()
public static JedisPool getPool() {
    try {
        TrustManager bogusTrustManager = new X509TrustManager() {
            public X509Certificate[] getAcceptedIssuers() {
                return null;
            }

            public void checkClientTrusted(X509Certificate[] certs, String authType) {
            }

            public void checkServerTrusted(X509Certificate[] certs, String authType) {
            }
        };

        SSLContext sslContext = SSLContext.getInstance("SSL");
        sslContext.init(null, new TrustManager[]{bogusTrustManager}, new java.security.SecureRandom());

        HostnameVerifier bogusHostnameVerifier = (hostname, session) -> true;

        JedisPoolConfig poolConfig = new JedisPoolConfig();
        poolConfig.setMaxTotal(10);
        poolConfig.setMaxIdle(5);
        poolConfig.setMinIdle(1);
        poolConfig.setTestOnBorrow(true);
        poolConfig.setTestOnReturn(true);
        poolConfig.setTestWhileIdle(true);

        return new JedisPool(poolConfig,
                URI.create(System.getenv("REDIS_URL")),
                sslContext.getSocketFactory(),
                sslContext.getDefaultSSLParameters(),
                bogusHostnameVerifier);

    } catch (NoSuchAlgorithmException | KeyManagementException e) {
        throw new RuntimeException("Cannot obtain Redis connection!", e);
    }
}

// In your multithreaded code this is where you'd checkout a connection
// and then return it to the pool
try (Jedis jedis = pool.getResource()){
  jedis.set("foo", "bar");
}

Connecting in Ruby

To use KVS in your Ruby app, you must include the redis gem in your Gemfile:

gem 'redis'

Run bundle install to download and resolve all dependencies.

Connecting in Rails

Create an initializer file named config/initializers/redis.rb containing:

$redis = Redis.new(url: ENV["REDIS_URL"], ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE })

Connecting from Sidekiq

Create an initializer file named config/initializers/sidekiq.rb containing:

Sidekiq.configure_server do |config|
  config.redis = {
    url: ENV["REDIS_URL"],
    ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE }
  }
end

Sidekiq.configure_client do |config|
  config.redis = {
     url: ENV["REDIS_URL"],
     ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE }
  }
end

Connecting in Python

To use KVS in your Python app, use the redis package:

$ pip install redis
$ pip freeze > requirements.txt

Use this package to connect to your KVS instance with TLS, configuring ssl_cert_reqs to disable certificate validation:

import os
import redis

r = redis.from_url(os.environ.get("REDIS_URL"), ssl_cert_reqs=None)

Connecting in Django

To use KVS in your Django app, if you’re running a Django version earlier than 4.0, use django-redis.

If you’re running Django version 4.0 or later, you can use django-redis or the built-in Redis backend support introduced in Django 4.0.

Using django-redis

Install the django-redis module:

$ pip install django-redis
$ pip freeze > requirements.txt

In your settings.py, configure django_redis.cache.RedisCache as the BACKEND for your CACHES and configure ssl_cert_reqs to disable certificate validation:

import os

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": os.environ.get('REDIS_URL'),
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "CONNECTION_POOL_KWARGS": {
                "ssl_cert_reqs": None
            },
        }
    }
}

Using the Built-in Redis Backend Support

Django’s built-in Redis backend support requires redis-py 3.0.0 or higher.

In your settings.py, configure django.core.cache.backends.redis.RedisCache as the BACKEND for your CACHES and configure ssl_cert_reqs to disable certificate validation:

import os

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": os.environ.get('REDIS_URL'),
        "OPTIONS": {
              "ssl_cert_reqs": None
        }
    }
}

Connecting in Node.js

Using the redis Module

Add the redis npm module to your dependencies:

npm install redis

Use the module to connect to REDIS_URL and configure node-redis to use TLS:

const redis = require("redis");

const redis_url = process.env.REDIS_URL;
const client = redis.createClient({
  url: redis_url,
  socket: {
    rejectUnauthorized: false,
  }
});
await client.connect();

Using the ioredis Module

Add the ioredis npm module to your dependencies:

npm install ioredis

Use the module to connect to REDIS_URL and configure ioredis to use TLS:

const Redis = require("ioredis");

const client = new Redis(process.env.REDIS_URL, {
    tls: {
        rejectUnauthorized: false
    }
});

Connecting in PHP

Using the Redis Extension

Add the Redis extension to your requirements:

$ composer require ext-redis:*

Connect to KVS after parsing the REDIS_URL config var from the environment:

$url = parse_url(getenv("REDIS_URL"));
$redis = new Redis();
$redis->connect("tls://".$url["host"], $url["port"], 0, null, 0, 0, [
  "auth" => urldecode($url["pass"]),
  "stream" => ["verify_peer" => false, "verify_peer_name" => false],
]);

Using Predis

Add the Predis package to your requirements:

$ composer require predis/predis

Connect to Redis using the REDIS_URL config var:

$redis = new Predis\Client(getenv('REDIS_URL'), [
  'scheme' => 'tls',
  'ssl'    => ['verify_peer' => false, 'verify_peer_name' => false],
]);

Connecting in Go

Add the go-redis package to your app:

$ go get github.com/redis/go-redis/v9

Import the package:

import (
      log
      os
      "github.com/redis/go-redis/v9"
)

Connect to Redis using the REDIS_URL config var:

opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))
if err != nil {
	log.Fatalf("failed to parse REDIS_URL: %v", err)
}

if opts.TLSConfig != nil {
      opts.TLSConfig.InsecureSkipVerify = true
  }

rdb := redis.NewClient(opts)

Connecting in .NET

To connect your .NET app to Heroku Key-Value Store, you must use a compatible client library, such as StackExchange.Redis.

Using StackExchange.Redis

Add the StackExchange.Redis NuGet package to your app:

$ dotnet add package StackExchange.Redis

Connect using the REDIS_URL config var:

using StackExchange.Redis;
using System;

string redisUrl = Environment.GetEnvironmentVariable("REDIS_URL");
var uri = new Uri(redisUrl);
var userInfoParts = uri.UserInfo.Split(':');
if (userInfoParts.Length != 2)
{
    throw new InvalidOperationException("REDIS_URL is not in the expected format ('redis://user:password@host:port')");
}

var configurationOptions = new ConfigurationOptions
{
    EndPoints = { { uri.Host, uri.Port } },
    Password = userInfoParts[1],
    Ssl = true,
};
configurationOptions.CertificateValidation += (sender, cert, chain, errors) => true;
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(configurationOptions);

This code retrieves the connection string from the REDIS_URL config var and parses it to extract the host, port, and password. Then it configures the StackExchange.Redis client to connect using SSL and skip certificate validation, which is necessary for Heroku Key-Value Store.

You can share and reuse the ConnectionMultiplexer instance throughout your app for optimal performance. For apps using dependency injection, register the IConnectionMultiplexer interface as a singleton to ensure efficient connection reuse.