How to use KV Store with Redis-compatible SDK

Learn how to use the Azion KV SDK with a Redis-like interface for seamless integration with your applications.

View as Markdown

The Azion KV SDK provides a Redis-like client interface for interacting with KV Store. This makes it easier to migrate existing applications that use Redis patterns and provides a familiar developer experience.

Go to KV Store reference

Requirements

Before you begin, make sure you have:

  • An Azion account.
  • A KV Store namespace created via Console or API.
  • Node.js 18+ or a compatible JavaScript runtime.

Installing the SDK

Install the Azion SDK using npm:

npm install azion

Creating a client

The SDK uses a Redis-like client pattern with chainable methods:

import { createClient } from 'azion/kv';
// Create and connect a client
const client = await createClient()
.on('error', (err) => console.error('KV Client Error:', err))
.connect();

Client options

You can customize the client with options:

const client = await createClient({
namespace: 'my-namespace',
apiToken: 'my-token',
})
.on('error', (err) => console.error('KV Error:', err))
.connect();
OptionTypeDescription
namespacestringThe KV Store namespace to use
apiTokenstringYour Azion API token (required for API provider)

Storing data

Use the set method to store values:

// Simple set
await client.set('user:123', 'John Doe');
// Set with expiration (10 seconds)
await client.set('session:abc', 'session-data', {
expiration: {
type: 'EX',
value: 10,
},
});
// Set with metadata
await client.set('config:theme', 'dark', {
metadata: {
updatedBy: 'admin',
version: 1
},
});
// Set with both expiration and metadata
await client.set('cache:api-response', JSON.stringify(data), {
expiration: {
type: 'EX',
value: 300, // 5 minutes
},
metadata: {
source: 'external-api',
cached_at: Date.now()
},
});

Expiration types

TypeDescription
EXExpiration time in seconds
PXExpiration time in milliseconds
EXATUnix timestamp in seconds
PXATUnix timestamp in milliseconds

Retrieving data

Use the get method to retrieve values:

// Simple get
const value = await client.get('user:123');
console.log(value); // 'John Doe'
// Returns null if key doesn't exist
const missing = await client.get('non-existent');
console.log(missing); // null

Retrieving with metadata

Use getWithMetadata to get both the value and its metadata:

const result = await client.getWithMetadata('config:theme');
console.log(result.value); // 'dark'
console.log(result.metadata); // { updatedBy: 'admin', version: 1 }

Deleting data

Use delete or del to remove keys:

await client.delete('user:123');
// or
await client.del('user:123');

Hash operations

The SDK provides Redis-compatible hash operations for working with field-value pairs:

hSet / HSET

Store a field-value pair:

await client.hSet('user:profile:123', 'name', 'John Doe');
await client.hSet('user:profile:123', 'email', 'john@example.com');
await client.hSet('user:profile:123', 'role', 'admin');
// Uppercase alias also available
await client.HSET('user:profile:123', 'status', 'active');

hGetAll / HGETALL

Get all fields and values:

const profile = await client.hGetAll('user:profile:123');
console.log(profile);
// { name: 'John Doe', email: 'john@example.com', role: 'admin', status: 'active' }
// Uppercase alias
const data = await client.HGETALL('user:profile:123');

hVals / HVALS

Get all values (without field names):

const values = await client.hVals('user:profile:123');
console.log(values);
// ['John Doe', 'john@example.com', 'admin', 'active']
// Uppercase alias
const vals = await client.HVALS('user:profile:123');

Provider detection

The SDK automatically detects the runtime environment and selects the appropriate provider:

  • Native provider: Used when running inside Azion Functions runtime
  • API provider: Used when running outside Azion (local development, external servers)

You can check which provider is being used:

const providerType = client.getProviderType();
console.log(providerType); // 'native' or 'api'

Error handling

The SDK uses an event-based error handling pattern:

const client = await createClient()
.on('error', (err) => {
console.error('KV Error:', err.message);
// Handle error (retry, fallback, etc.)
})
.connect();

You can also use try-catch for individual operations:

try {
await client.set('key', 'value');
} catch (error) {
console.error('Failed to set value:', error);
}

Disconnecting

Always disconnect when you’re done:

await client.disconnect();
// or
await client.quit();

Complete example

Here’s a complete example showing common operations:

import { createClient } from 'azion/kv';
async function main() {
// Create and connect client
const client = await createClient({
namespace: 'my-app',
})
.on('error', (err) => console.error('KV Error:', err))
.connect();
try {
// Store user data
await client.set('user:1', JSON.stringify({ name: 'Alice', age: 30 }), {
expiration: { type: 'EX', value: 3600 }, // 1 hour
metadata: { created: Date.now() },
});
// Store user profile using hash operations
await client.hSet('profile:1', 'theme', 'dark');
await client.hSet('profile:1', 'language', 'en');
await client.hSet('profile:1', 'notifications', 'true');
// Retrieve user data
const userData = await client.get('user:1');
console.log('User:', JSON.parse(userData));
// Retrieve with metadata
const result = await client.getWithMetadata('user:1');
console.log('Created at:', result.metadata.created);
// Get all profile settings
const profile = await client.hGetAll('profile:1');
console.log('Profile:', profile);
// Clean up
await client.delete('user:1');
} finally {
await client.disconnect();
}
}
main().catch(console.error);

Redis method mapping

Redis CommandSDK MethodDescription
GETget(key)Get a value
SETset(key, value, options?)Set a value
DELdelete(key) / del(key)Delete a key
HSEThSet(key, field, value) / HSET(...)Set hash field
HGETALLhGetAll(key) / HGETALL(key)Get all hash fields
HVALShVals(key) / HVALS(key)Get all hash values

Next steps