Cloudflare Workers KV é um armazenamento global de chave e valor feito para leituras rápidas e muito frequentes. Ele é excelente para cache, preferências, sessões auxiliares, flags simples e resolução de links curtos. Ele não é um banco transacional nem uma fila; usar KV como se fosse um desses produtos cria bugs que aparecem quando o tráfego cresce.
No nosso cenário, namespaces separados atendem autenticação, cache, API e short links. Essa separação evita que uma limpeza de cache atinja sessão e que um contador temporário concorra com a resolução pública de um link.
Quando usar KV — e quando não usar
KV faz sentido quando ler é mais comum que escrever e uma pequena janela de consistência eventual é aceitável. A documentação da Cloudflare descreve propagação global eventual, normalmente em até 60 segundos, e limite de uma escrita por segundo por chave. Isso define a fronteira do produto.
| Necessidade | Escolha mais adequada | Por quê |
|---|---|---|
| cache de artigo ou configuração | KV | leitura global e TTL simples |
| sessão auxiliar ou desafio temporário | KV | acesso rápido e expirável |
| link curto publicado | KV + fonte canônica | resolve rápido; banco reconcilia |
| saldo, estoque ou permissão crítica | banco transacional / Durable Object | não aceite consistência eventual |
| arquivo, imagem ou PDF | R2 | KV não é object storage |
| trabalho para depois | Queue | uma chave não confirma processamento |
Cenário brasileiro: blog, sessão e link curto
Um blog pode guardar uma listagem de artigos em KV por uma hora e servir conteúdo antigo enquanto regenera a resposta. Isso protege o banco de picos quando uma campanha ou uma aula gera muitos acessos. Já uma sessão de autenticação pode usar KV como armazenamento secundário, mas a aplicação ainda precisa validar a identidade e aplicar permissão no servidor.
Para short links, o fluxo saudável é: o Gestor grava a regra de negócio no banco, projeta a versão resolvível no KV_SHORTLINKS e o Worker de links lê apenas o necessário para redirecionar. Se o KV perder uma chave, um processo de reconciliação consegue repovoá-la; se o banco perder a regra, o sistema tem um problema diferente e mais grave.
Preço e como estimar
Na tabela vigente em julho de 2026, Workers Paid inclui 10 milhões de leituras por mês, 1 milhão de escritas, deletes e listagens, além de 1 GB armazenado. Leituras adicionais custam US$ 0,50 por milhão; escritas, deletes e listagens, US$ 5 por milhão; armazenamento adicional, US$ 0,50 por GB-mês. O plano gratuito tem limites diários bem menores.
O custo orienta uma decisão simples: cache com muita leitura costuma ser barato; um desenho que escreve uma chave por clique, por token ou por contador pode ficar caro e sofrer limite de escrita. Prefira agregação, TTL e um contador especializado quando a taxa por chave for alta.
Padrão de chave que permite operar
Use chaves previsíveis, curtas e com domínio explícito:
auth:session:{id}
cache:blog:list:v1
cache:blog:article:{slug}
shortlink:{slug}
rate-limit:{tenant}:{janela}Evite colocar CPF, e-mail ou token em uma chave legível. Além de privacidade, você torna logs, listagens e ferramentas de suporte mais arriscados. Se o dado for sensível, use identificador interno, TTL e menor conjunto possível de metadados.
[ CONTEÚDO_INTEGRAL_DISPONÍVEL ]
Continuar: arquivos e capas no R2, não no KV CLIQUE PARA DESBLOQUEAR A LEITURA
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Prós, contras e armadilhas
Prós: leitura global rápida, binding simples, TTL nativo e preço previsível em cenários read-heavy. Contras: consistência eventual, limite por chave, sem consulta por atributos e sem transação. Você também precisa tratar cache stale e invalidação como parte do produto.
Não use list() como consulta de negócio. Liste chaves para manutenção ou reconciliação; para buscar “todos os artigos de uma categoria” ou “pedidos de um cliente”, use o banco que modela essa relação.
Checklist antes de criar um namespace
- a leitura é muito mais frequente que a escrita;
- até 60 segundos de propagação eventual não quebra a regra;
- existe fonte canônica fora do KV;
- cada ambiente tem namespace físico próprio;
- TTL e prefixo foram definidos;
- a limpeza não pode apagar dados de outro domínio;
- métricas incluem hit, miss, write e falha de reconciliação.
Perguntas frequentes
KV serve para rate limit?
Pode servir para casos tolerantes a aproximação, mas não oferece contador atômico global por padrão. Para bloqueio estrito, avalie o Rate Limiting binding, Durable Objects ou outra solução apropriada.
Posso guardar sessão no KV?
Sim, quando a biblioteca e o modelo de segurança suportarem isso. Separe namespace, use expiração e não confunda a presença de uma chave com autorização para qualquer ação.
O que acontece em um cache miss?
O Worker consulta a fonte de verdade, monta uma resposta validada e grava uma cópia com TTL. O código deve continuar funcionando se a gravação de cache falhar.
