Upstash Redis

Visão Geral

@upstash/redis é um cliente Redis que se comunica com um banco de dados Upstash Redis via HTTPS em vez de uma conexão TCP. Como cada comando é uma requisição HTTP sem estado, ele funciona em ambientes onde um cliente TCP com pool é complicado ou impossível: funções Vercel e Netlify, Cloudflare Workers, Deno, Bun e middleware Next.js. O cliente serializa e desserializa valores JavaScript automaticamente, portanto números e objetos são convertidos sem necessidade de JSON.parse manual.

Quando Usar Esta Habilidade

• Use quando o usuário precisar de um cache, armazenamento de sessão, contador, ranking ou fila simples de uma função serverless ou edge.
• Use quando o usuário mencionar Upstash Redis, UPSTASH_REDIS_REST_URL ou @upstash/redis.
• Use ao migrar um site de chamada ioredis ou node-redis para um runtime que não pode manter um socket TCP persistente.
• Não use para um servidor Redis auto-hospedado ou não-Upstash; o cliente só fala o protocolo REST do Upstash. Use ioredis ou node-redis para isso.
• Não use para administração ou trabalho de CLI do Redis; veja redis-cli.

Como Funciona

Passo 1: Configurar credenciais

Crie um banco de dados no console Upstash e copie a URL REST e o token para variáveis de ambiente. Nunca as codifique diretamente.

UPSTASH_REDIS_REST_URL=https://<your-db>.upstash.io
UPSTASH_REDIS_REST_TOKEN=<your-rest-token>

Passo 2: Criar um cliente por módulo

import { Redis } from "@upstash/redis";

export const redis = Redis.fromEnv();

No Cloudflare Workers, importe de @upstash/redis/cloudflare e passe o objeto env do worker: Redis.fromEnv(env).

Passo 3: Chamar comandos Redis como métodos

Os nomes dos comandos são métodos em minúsculas (get, set, hset, zadd, incr). Os valores são auto-serializados; passe e receba tipos nativos do JavaScript.

Exemplos

Exemplo 1: Cache-aside com TTL

import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();

export async function getUser(id: string) {
  const cached = await redis.get<{ id: string; name: string }>(`user:${id}`);
  if (cached) return cached;

  const user = await db.users.findById(id);
  await redis.set(`user:${id}`, user, { ex: 3600 }); // expires in 1 hour
  return user;
}

export async function invalidateUser(id: string) {
  await redis.del(`user:${id}`);
}

Exemplo 2: Agrupar comandos em um pipeline

const pipeline = redis.pipeline();
pipeline.hset("user:1", { name: "Alice", plan: "pro" });
pipeline.incr("signups:total");
pipeline.zadd("leaderboard", { score: 120, member: "user:1" });
const [hsetResult, signups, zaddResult] = await pipeline.exec();

pipeline() agrupa comandos independentes em uma única ida e volta. Não é atômico; use redis.multi() para MULTI/EXEC ou um script Lua revisado no lado do servidor quando os comandos precisam ser executados como uma unidade.

Melhores Práticas

• ✅ Leia credenciais com Redis.fromEnv() ou de um gerenciador de segredos.
• ✅ Defina um TTL ({ ex: seconds }) nas entradas do cache para que dados desatualizados expirem.
• ✅ Use namespace nas chaves (user:123, session:abc) para manter o keyspace legível.
• ✅ Use pipeline() ou mget/mset em vez de muitos awaits sequenciais.
• ❌ Não JSON.stringify valores antes de set; o cliente já faz isso.
• ❌ Não chame keys("*") em manipuladores de requisição; use scan para keyspaces grandes.
• ❌ Não armazene segredos ou PII no Redis sem um plano de retenção e TTL.

Limitações

• Requer um banco de dados Upstash Redis; não pode se conectar a outros servidores Redis.
• Cada comando é uma requisição HTTP, então a latência é maior do que uma conexão TCP quente; use pipelines em lote onde for importante.
• Transações (multi()) não revertem em erros de runtime, e WATCH não está disponível via REST; use um script Lua para check-and-set atômico.
• Comandos Pub/Sub de subscribe e bloqueantes (BLPOP, XREAD BLOCK) não são suportados pelo cliente REST.
• Esta habilidade cobre apenas o cliente TypeScript. Python, Go e outros SDKs têm nomes de métodos diferentes.
• Esta habilidade não substitui validação específica do ambiente, testes ou revisão especializada.

Notas de Segurança e Proteção

• O token REST concede acesso total de leitura/escrita ao banco de dados. Mantenha-o em variáveis de ambiente do lado do servidor; nunca o envie para um bundle do navegador.
• Use um token somente leitura do console para cargas de trabalho somente leitura.
• Comandos como flushdb e del são destrutivos; confirme com o usuário antes de executá-los em um banco de dados de produção.

Armadilhas Comuns

…