Quick start

Valkey GLIDE is the open-source client library for Valkey. Designed for performance and consistency between supported languages. This guide will show how to quickly install and set up a simple development environment for Valkey GLIDE.

Understanding GLIDE Clients

GLIDE provides two main client types:

• GlideClient: For standalone Valkey instances.
• GlideClusterClient: For cluster deployments.

For this guide, we will use a standalone client to connect to a Valkey Docker instance.

Setting Up

1. Follow the instructions on the Docker website to install Docker for your operating system.

2. Start a local Valkey server:

   # Pull and run Valkey server
   docker run -d --name valkey-server -p 6379:6379 valkey/valkey:latest
   
   # Verify it's running
   docker ps

3. Verify connection with Valkey server:

   docker exec valkey-server valkey-cli ping
   # Expected output: PONG

System Requirements

Linux

• Ubuntu 20 (x86_64/amd64 and arm64/aarch64)
• Amazon Linux 2 (AL2) and 2023 (AL2023) (x86_64). The Node.js client does not support AL2; see Known Issues.
• Alpine Linux are not supported for Python and C# clients. See Installation Guide for more details.

MacOS

• macOS 14.7 (Apple silicon/aarch_64)
• macOS 13.7 (x86_64/amd64)

Windows

Windows support is currently available for Valkey GLIDE Java and C#.

• Windows (x86_64)
• Windows (arm64) — C# only

Install Valkey GLIDE

Java

Requirements: JDK 8+ (JDK 11+ recommended)

Add the following to your build tool. Make sure to specify your classifier for your OS.

Uber Jar Available

Starting from version 2.3.0, Java users can choose between the uber jar (no classifier needed) or a platform-specific jar with a classifier. The uber jar bundles all platform binaries, so it is larger in size. If you prefer a smaller dependency, use the classifier-based jar for your specific OS.

Gradle

dependencies {
    implementation group: 'io.valkey', name: 'valkey-glide', version: '2.+'
}

Maven

<!-- with os-maven-plugin -->
<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
        </extension>
    </extensions>
</build>
<dependencies>
    <dependency>
        <groupId>io.valkey</groupId>
        <artifactId>valkey-glide</artifactId>
        <classifier>${os.detected.classifier}</classifier>
        <version>[2.0.0,)</version>
    </dependency>
</dependencies>

SBT

// Specify the OS classifier for your system.
libraryDependencies += "io.valkey" % "valkey-glide" % "2.+" classifier "<your-classifier>"

Python

Requirements: Python 3.9 to 3.14.

# Install the latest version
pip3 install valkey-glide

Node

Requirements: Node.js 20+

npm install @valkey/valkey-glide

Go

Requirements: Go 1.22+

# Initialize a new Go module (if needed)
go mod init your-project-name

# Install GLIDE
go get github.com/valkey-io/valkey-glide/go/v2
go mod tidy

PHP

Requirements: PHP 8.1+

pie install valkey-io/valkey-glide-php

# Install via Composer:
composer require valkey-io/valkey-glide-php

# Install from PECL:
curl -L https://github.com/valkey-io/valkey-glide-php/releases/download/v<version>/valkey_glide-<version>.tgz -o valkey_glide-<version>.tgz
pecl install valkey_glide-<version>.tgz

# After installation, enable the extension:
extension=valkey_glide

C#

Requirements: .NET 8.0+

dotnet add package Valkey.Glide

Ruby

Requirements: Ruby 3.0+

gem install valkey-glide-rb

Or add it to your Gemfile:

gem "valkey-glide-rb"

Installation Guides

For more detailed instructions, refer to our installation guides.

A Simple Ping

The following code snippet performs a simple “ping” command to our docker Valkey instance. This will tell us that GLIDE was able to send and receive commands from Valkey. For testing against a live instance, update the GlideClient configurations.

Java

import glide.api.GlideClient;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;

public class ConnectionTest {
    public static void main(String[] args) {
        // Create client configuration
        GlideClientConfiguration config = GlideClientConfiguration.builder()
            .address(NodeAddress.builder()
                .host("localhost")
                .port(6379)
                .build())
            .build();

        try (GlideClient client = GlideClient.createClient(config).get()) {
            // Test the connection
            String response = client.ping().get();

            // Valkey responds with PONG
            System.out.println("Connected! Server responded: " + response);

        } catch (Exception e) {
            System.err.println("Connection failed: " + e.getMessage());
        }
    }
}

Python

import asyncio
from glide import GlideClient, GlideClientConfiguration, NodeAddress

async def main():
    # Create client configuration
    config = GlideClientConfiguration(
        addresses=[NodeAddress("localhost", 6379)]
    )
    client = None

    try:
        client = await GlideClient.create(config)

        # Test the connection
        response = await client.ping()

        # Valkey responds with PONG
        print(f"Connected! Server responded: {response.decode()}")

    except Exception as e:
        print(f"Connection failed: {e}")

    finally:
        if client is not None:
            await client.close()

# Run the async function
if __name__ == "__main__":
    asyncio.run(main())

Node

const { GlideClient } = require('@valkey/valkey-glide');

async function main() {
    let client;

    try {
        // Create client configuration
        client = await GlideClient.createClient({
            addresses: [{ host: 'localhost', port: 6379 }]
        });

        // Test the connection
        const response = await client.ping();

        // Valkey responds with PONG
        console.log(`Connected! Server responded: ${response}`);

    } catch (error) {
        console.error(`Connection failed: ${error.message}`);
    } finally {
        if (client) {
            client.close();
        }
    }
}

// Run the function
main().catch(console.error);

Go

package main
import (
    "context"
    "fmt"
    glide "github.com/valkey-io/valkey-glide/go/v2"
    "github.com/valkey-io/valkey-glide/go/v2/config"
)

func main() {
    host := "localhost"
    port := 6379

    cfg := config.NewClientConfiguration().
        WithAddress(&config.NodeAddress{Host: host, Port: port})

    client, err := glide.NewClient(cfg)
    if err != nil {
        fmt.Println("There was an error: ", err)
        return
    }
    defer client.Close()

    res, err := client.Ping(context.Background())
    if err != nil {
        fmt.Println("There was an error: ", err)
        return
    }
    // Valkey responds with PONG
    fmt.Printf("Connected! Server responded: %s\n", res)
}

PHP

// Create ValkeyGlide client
$client = new ValkeyGlide();

try {
    // Connect to Valkey server
    $client->connect(
        addresses: [['host' => 'localhost', 'port' => 6379]]
    );

    // Test the connection
    $response = $client->ping();

    // Valkey responds with PONG
    echo "Connected! Server responded: {$response}\n";

} catch (ValkeyGlideException $e) {
    echo "Connection failed: {$e->getMessage()}\n";
} finally {
    // Always close the client
    $client->close();
}

C#

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

// Create client configuration
var config = new StandaloneClientConfigurationBuilder()
    .WithAddress("localhost", 6379)
    .Build();

try
{
    await using var client = await GlideClient.CreateClient(config);

    // Test the connection
    var result = await client.PingAsync();

    // Valkey responds with PONG
    Console.WriteLine($"Connected! Server responded: {result}");
}
catch (Exception e)
{
    Console.WriteLine($"Connection failed: {e.Message}");
}

Ruby

require "valkey"

begin
  # Create the client
  client = Valkey.new(host: "localhost", port: 6379)

  # Test the connection
  response = client.ping

  # Valkey responds with PONG
  puts "Connected! Server responded: #{response}"
rescue StandardError => e
  puts "Connection failed: #{e.message}"
ensure
  client&.close
end

Running the above snippet should give you this response.

Connected! Server responded: PONG

Caution

Always close/dispose GLIDE clients to cleanup resources when the instance is no longer needed.

Connection Configuration

GLIDE offers many configuration options to connect to Valkey through its configuration objects. These options, and other interfaces, stay consistent between languages.

Java

// Setting up connection configuration
GlideClientConfiguration config = GlideClientConfiguration.builder()
    .address(NodeAddress.builder()
        .host("localhost")
        .port(6379)
        .build())
    // Request timeout (milliseconds)
    .requestTimeout(5000)
    // TLS configuration (if needed)
    .useTLS(false)
    // Database selection
    .databaseId(0)
    .build();

Python

# Setting up connection configuration
config = GlideClientConfiguration(
    addresses=[NodeAddress("localhost", 6379)],
    # Request timeout (milliseconds)
    request_timeout=5000,
    # TLS configuration (if needed)
    use_tls=False,
    # Database selection
    database_id=0
)

Node

// Setting up connection configuration
const configs = {
    addresses: [{ host: 'localhost', port: 6379 }],
    // Request timeout (milliseconds)
    requestTimeout: 5000,
    // TLS configuration (if needed)
    useTLS: false,
    // Database selection
    databaseId: 0
}

Go

// Setting up connection configuration
host := "localhost"
port := 6379

cfg := config.NewClientConfiguration().
    WithAddress(&config.NodeAddress{Host: host, Port: port}).
    WithRequestTimeout(5 * time.Second).
    WithUseTLS(false).
    WithDatabaseId(0)

client, err := glide.NewClient(cfg)
if err != nil {
    fmt.Println("There was an error: ", err)
    return
}
defer client.Close()

PHP

// Setting up connection configuration
$client = new ValkeyGlide();
$client->connect(
    addresses: [['host' => 'localhost', 'port' => 6379]],
    // Request timeout (milliseconds)
    request_timeout: 5000,
    // TLS configuration (if needed)
    use_tls: false,
    // Database selection
    database_id: 0
);

C#

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

// Setting up connection configuration
var config = new StandaloneClientConfigurationBuilder()
    .WithAddress("localhost", 6379)
    .WithRequestTimeout(TimeSpan.FromMilliseconds(5000))
    .WithDatabaseId(0)
    .Build();

await using var client = await GlideClient.CreateClient(config);

Ruby

# Setting up connection configuration
client = Valkey.new(
  host: "localhost",
  port: 6379,
  # Request timeout (seconds)
  timeout: 5.0,
  # TLS configuration (if needed)
  ssl: false,
  # Database selection (0-15 for Redis/Valkey)
  db: 0
)

Tip

For a full list of connection options, take a look at the connection options guides.

Next Steps

Congratulations, you are now connected to Valkey using GLIDE! To see how to make basic operations take a look at the our guide.