Conectar ao Valkey

Use a conexão retornada pelo Console ou pela API. Ela tem o formato valkeys://usuario:senha@host:porta/0 e deve ser fornecida à aplicação pela variável VALKEY_URL.

Regras de segurança

Use sempre TLS e valide o certificado do host.
Mantenha o usuário default e a senha fora do código-fonte.
Nunca use opções que desativem a validação TLS, do certificado ou do hostname.
Abra uma conexão reutilizável por processo; não crie uma conexão nova para cada comando.
Após uma rotação, substitua a variável protegida e reinicie os workers que mantêm conexões antigas.

Algumas bibliotecas aceitam apenas redis:// ou rediss://. Trocar valkeys:// por rediss:// altera somente o esquema compatível com a biblioteca; TLS continua obrigatório.

Node.js e TypeScript

Instale o cliente compatível:

npm install iovalkey

import Redis from 'iovalkey'

const rawUrl = process.env.VALKEY_URL
if (!rawUrl) throw new Error('VALKEY_URL is required')

const parsed = new URL(rawUrl)
if (parsed.protocol !== 'valkeys:') throw new Error('VALKEY_URL must use valkeys://')

const client = new Redis({
  host: parsed.hostname,
  port: Number(parsed.port),
  username: decodeURIComponent(parsed.username),
  password: decodeURIComponent(parsed.password),
  tls: { servername: parsed.hostname },
})

await client.set('healthcheck', 'ok', 'EX', 60)
console.log(await client.get('healthcheck'))
await client.quit()

Python

Instale valkey-py:

python -m pip install valkey

import os
from urllib.parse import urlparse
from valkey import Valkey

raw_url = os.environ["VALKEY_URL"]
parsed = urlparse(raw_url)
if parsed.scheme != "valkeys":
    raise ValueError("VALKEY_URL must use valkeys://")

client = Valkey(
    host=parsed.hostname,
    port=parsed.port,
    username=parsed.username,
    password=parsed.password,
    db=0,
    ssl=True,
    ssl_check_hostname=True,
    decode_responses=True,
)

client.set("healthcheck", "ok", ex=60)
print(client.get("healthcheck"))
client.close()

Outros clientes

Os pacotes abaixo são opções recomendadas ou compatíveis com Valkey. Em todos os casos, extraia host, porta, usuário e senha de VALKEY_URL, habilite TLS e valide o hostname.

Linguagem	Instalação	Cliente
Go	`go get github.com/valkey-io/valkey-go`	`valkey-go`
Java	`io.valkey:valkey-java`	`valkey-java`
PHP	`composer require predis/predis`	Predis
.NET	pacote Valkey GLIDE	Valkey GLIDE C#
Ruby	`gem install redis`	`redis`
Rust	`cargo add redis --features tokio-native-tls-comp`	`redis`

Exemplo mínimo em Go, adaptando o esquema porque valkey-go aceita rediss://:

package main

import (
  "context"
  "log"
  "os"
  "strings"

  valkey "github.com/valkey-io/valkey-go"
)

func main() {
rawURL := strings.Replace(os.Getenv("VALKEY_URL"), "valkeys://", "rediss://", 1)
client, err := valkey.NewClient(valkey.MustParseURL(rawURL))
if err != nil { log.Fatal(err) }
defer client.Close()
if err := client.Do(context.Background(), client.B().Ping().Build()).Error(); err != nil { log.Fatal(err) }
}

Java com valkey-java (Jedis fork):

var uri = java.net.URI.create(System.getenv("VALKEY_URL").replaceFirst("^valkeys", "rediss"));
var credentials = uri.getUserInfo().split(":", 2);
var host = uri.getHost();
var port = uri.getPort();
var username = java.net.URLDecoder.decode(credentials[0], java.nio.charset.StandardCharsets.UTF_8);
var password = java.net.URLDecoder.decode(credentials[1], java.nio.charset.StandardCharsets.UTF_8);
var pool = new io.valkey.JedisPool(
    new io.valkey.JedisPoolConfig(), host, port, 5000, username, password, 0, true);
try (var client = pool.getResource()) {
    client.set("healthcheck", "ok");
    System.out.println(client.get("healthcheck"));
} finally {
    pool.close();
}

PHP com Predis; o esquema tls mantém verificação de certificado e hostname:

<?php
$parts = parse_url(getenv('VALKEY_URL'));
$client = new Predis\Client([
    'scheme' => 'tls',
    'host' => $parts['host'],
    'port' => (int) $parts['port'],
    'username' => rawurldecode($parts['user']),
    'password' => rawurldecode($parts['pass']),
    'ssl' => ['verify_peer' => true, 'verify_peer_name' => true],
]);
$client->set('healthcheck', 'ok');
echo $client->get('healthcheck'), PHP_EOL;
$client->disconnect();

Valkey GLIDE para .NET (não use este cliente em runtimes Alpine):

var rawUrl = Environment.GetEnvironmentVariable("VALKEY_URL")
    ?? throw new InvalidOperationException("VALKEY_URL is required");
var uri = new Uri(rawUrl.Replace("valkeys://", "rediss://", StringComparison.Ordinal));
var credentials = uri.UserInfo.Split(':', 2);
var host = uri.Host;
var port = uri.Port;
var username = Uri.UnescapeDataString(credentials[0]);
var password = Uri.UnescapeDataString(credentials[1]);
var config = new GlideClientConfiguration {
    Addresses = [new NodeAddress(host, port)],
    UseTls = true,
    Credentials = new ServerCredentials(username, password),
};
await using var client = await GlideClient.CreateClientAsync(config);
await client.SetAsync("healthcheck", "ok");
Console.WriteLine(await client.GetAsync("healthcheck"));

Ruby com a gem redis:

require "openssl"
require "redis"

url = ENV.fetch("VALKEY_URL").sub("valkeys://", "rediss://")
client = Redis.new(url: url, ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER })
client.set("healthcheck", "ok")
puts client.get("healthcheck")
client.close

Rust com a crate redis e o recurso tokio-native-tls-comp:

use redis::AsyncCommands;

let url = std::env::var("VALKEY_URL")?.replacen("valkeys://", "rediss://", 1);
let client = redis::Client::open(url)?;
let mut connection = client.get_multiplexed_async_connection().await?;
connection.set::<_, _, ()>("healthcheck", "ok").await?;
println!("{}", connection.get::<_, String>("healthcheck").await?);

Em Java, PHP, .NET, Ruby e Rust, mantenha o certificado padrão do sistema, use o hostname retornado para SNI e faça um PING antes de iniciar o worker. Consulte a documentação da versão do cliente para ajustar nomes de construtores e opções sem desativar a validação TLS.

Testar a conexão

Com valkey-cli, a validação deve ser explícita:

valkey-cli -u "${VALKEY_URL/valkeys:/rediss:}" --tls ping

O retorno esperado é PONG. Não coloque a senha diretamente no histórico do shell; use o mecanismo de secret da sua plataforma ou VALKEYCLI_AUTH em um processo temporário.