Redis API reference
The Redis API is how your code finds and authenticates to a linked Redis server. Its binding is the connection details Alien injects into each workload linked to the resource: where the server is and how to authenticate.
Your code connects with its own client: the binding wraps no commands, because every backend speaks the Redis protocol.
A handle comes from these calls, where name is the resource ID from alien.ts:
- TypeScript:
redis(name)from@alienplatform/sdk - Python:
redis(name)fromalienplatform - Rust:
Bindings::from_env()?.redis(name).await?fromalien-sdk
connection
Returns the connection details.
import { redis } from "@alienplatform/sdk"
import { Redis } from "ioredis"
const conn = await redis("cache").connection()
const client = new Redis({
host: conn.host,
port: conn.port,
username: conn.username,
password: conn.password,
tls: conn.tls || undefined,
})On AWS, Google Cloud, and Azure, resolving the binding reads the password from the cloud with the workload's identity. To pick up a rotated password, create a new handle with redis(name) and call connection() again.
RedisConnection
type RedisConnection = {
url: string // redis:// locally, otherwise rediss://user:password@host:port/0
host: string
port: number // 6379 on AWS, Google Cloud, and Local; 10000 on Azure
username: string
password: string
database: 0
tls: false | { ca?: string[]; servername?: string }
}urlpercent-encodes the username and password, so a generated password with URL-special characters can't break it.tlsisfalseon Local. Otherwise it's an object you can pass to ioredis astls, or spread into node-redissocketoptions withtls: true.caholds the provider's PEM certificates when the provider signs with its own CA (Google Cloud). It's absent when the system trust store applies (AWS and Azure).
Python's RedisConnection has url, host, port, username, password, tls, ca_certificates, and database, plus helpers:
| Method | Returns |
|---|---|
ssl_context() | An ssl.SSLContext that trusts ca_certificates. None when tls is false. |
redis_kwargs() | Keyword arguments for redis.asyncio.Redis(...). |
The Python repr hides the password.
Rust returns RedisConnectionParams with host, port, username, password, and tls, plus connection_url(). Its Debug output hides the password.
TLS
| Platform | TLS | Trust |
|---|---|---|
| AWS | On | System trust store. |
| Google Cloud | On | The instance's CA chain, two certificates, carried in the binding. The certificate lists the endpoint's IP, so no server name override is needed. |
| Azure | On | System trust store. |
| Local | Off | None. The server is reachable only from your machine. |
| External | On by default. Off with tls: false. | System trust store. |
The binding
A linked Redis resource injects ALIEN_<NAME>_BINDING, uppercased with hyphens as underscores: cache becomes ALIEN_CACHE_BINDING. The SDKs read it for you. It's JSON tagged by service:
service | Platform | Fields |
|---|---|---|
elasticache | AWS | host, port, username, passwordSecretArn |
memorystore | Google Cloud | host, port, username, serverCaCertificates, instanceName |
azure-managed-redis | Azure | host, port, username, databaseResourceId |
external | Kubernetes, Machines, or your own server | host, port, username, password, tls (default true) |
local-redis | Local | host, port, username, password |
The cloud variants never contain the password, only where to read it: a Secrets Manager ARN, the Memorystore instance whose auth token the workload reads, or the database whose access keys the workload lists. The workload's identity authorizes the read through redis/data-access.
External and Local carry the password inline. Keep it out of logs.
The username is default on AWS, Google Cloud, and Azure for the generated credentials. Read it from the connection instead of hard-coding it.
Errors
| Code | Retryable | When |
|---|---|---|
REDIS_CREDENTIAL_RESOLUTION_FAILED | Follows the cloud error | Reading the password failed, for example because the workload lacks redis/data-access. Throttling stays retryable. |
REDIS_CREDENTIAL_INVALID | No | The secret or key exists but isn't usable as a password. |
BINDING_NOT_CONFIGURED | No | The workload isn't linked to this resource. |
Errors name where the credential was read from, never its value. Errors from the server itself come from your client.
Redis
A managed Redis-compatible store on a private network, on ElastiCache for Valkey, Memorystore for Valkey, Azure Managed Redis, or a local Valkey container.
Behavior and limits
What Redis guarantees on each platform, sizing and tiers, persistence, blocked commands, changes to a running server, deletion, and limits.