> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Redis na Square Cloud: conexão, memória e persistência

> Redis gerenciado na Square Cloud: conexão TLS com rediss://, timeout por inatividade, comandos bloqueados, módulos integrados (Search, JSON, TimeSeries), política de memória noeviction, persistência e erros comuns.

Um servidor Redis gerenciado acessado por TLS, com os módulos Search, JSON, TimeSeries, probabilísticos e vector sets integrados. O que vale para todos os engines (limites, snapshots, Insights) está na [visão geral de Bancos de dados](https://docs.squarecloud.app/pt-br/services/databases.md).

## Conectar

Copie a URL de conexão da página do banco de dados no dashboard:

```
rediss://default:PASSWORD@HOST:PORT
```

O esquema é **`rediss://`** (dois s): o servidor só aceita TLS, e não existe porta sem criptografia. Não é preciso certificado do cliente; para verificar o servidor, use o `.pem` de **Conexão** → **Certificado SSL/TLS** como CA. Uma URL salva de um banco criado antes de 29 de setembro de 2026 ainda pode estar com `redis://`: troque para `rediss://`.

> [tab] node-redis
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import { createClient } from "redis";
>
> // One client for the whole process, created once and reused.
> export const redis = createClient({
>   url: process.env.REDIS_URL,
>   socket: { tls: true, ca: fs.readFileSync("certificate.pem", "utf8") },
>   pingInterval: 60_000, // keeps the connection from being closed as idle
> });
>
> redis.on("error", (err) => console.error("Redis error", err));
> await redis.connect();
> ```

> [tab] ioredis
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import Redis from "ioredis";
>
> export const redis = new Redis(process.env.REDIS_URL, {
>   tls: { ca: fs.readFileSync("certificate.pem", "utf8") },
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> import redis
>
> r = redis.from_url(
>     os.environ["REDIS_URL"],
>     ssl_ca_certs="certificate.pem",
>     health_check_interval=60,
> )
> ```

> [tab] redis-cli
>
> ```bash theme={"system"}
> redis-cli -u "rediss://default:PASSWORD@HOST:PORT" --tls --cacert certificate.pem
> ```

## Comportamento da conexão

* **Clientes inativos são desconectados depois de 300 segundos.** Use um cliente que reconecta sozinho (node-redis, ioredis e redis-py fazem isso) ou envie um `PING` periódico, como nos exemplos acima.
* **Um único banco lógico (0).** `SELECT 1` ou maior responde `ERR DB index is out of range`: separe os dados com prefixos de chave (`cache:`, `session:`).
* Até 256 clientes simultâneos; passando disso, os novos recebem `max number of clients reached`. Crie um cliente por processo e reutilize-o.
* A autenticação é a senha do usuário `default`. Não é possível criar outros usuários de ACL.

## Comandos

Todos os comandos de dados funcionam, assim como scripts Lua e Functions, pub/sub, `MULTI`/`EXEC`, `SCAN` e `SLOWLOG`. Estes estão bloqueados e respondem `NOPERM`: `FLUSHALL`, `FLUSHDB`, `SHUTDOWN`, `CONFIG`, `DEBUG`, `ACL`, `REPLICAOF`/`SLAVEOF` e `FAILOVER`.

Sem o `CONFIG`, a política de eviction e as notificações de keyspace não podem ser mudadas. Para esvaziar o banco, apague as chaves em lotes com `SCAN` e `UNLINK`:

```bash theme={"system"}
URL="rediss://default:PASSWORD@HOST:PORT"
redis-cli -u "$URL" --tls --cacert certificate.pem --scan --pattern 'cache:*' \
  | xargs -n 100 redis-cli -u "$URL" --tls --cacert certificate.pem UNLINK
```

## Módulos integrados

| Módulo | Comandos |
| :- | :- |
| Search and Query | `FT.*` (texto completo, índices secundários, busca vetorial) |
| JSON | `JSON.*` |
| TimeSeries | `TS.*` |
| Probabilísticos | `BF.*`, `CF.*`, `CMS.*`, `TOPK.*`, `TDIGEST.*` |
| Vector sets | `VADD`, `VSIM` e os outros comandos `V*` |

As queries de busca rodam em tantas threads quantas forem as vCPUs do banco.

## Memória

* O Redis pode guardar dados até **90% da RAM do banco de dados**. Os outros 10% cobrem o overhead dele, os buffers dos clientes e o espaço de que um save precisa.
* A política é **`noeviction`**: quando a memória enche, nada é removido. As escritas falham com `OOM command not allowed when used memory > 'maxmemory'`, enquanto as leituras continuam funcionando e o servidor continua de pé.
* Por isso, **defina uma expiração nas chaves de cache** (`SET key value EX 3600`, `EXPIRE`) e dimensione a RAM para os dados que não expiram.
* Mudar a RAM do banco o reinicia.

## Respostas grandes

Um cliente cujas respostas não lidas passam de 32 MB (ou ficam acima de 16 MB por 60 segundos) é desconectado; para assinantes de pub/sub, os limites são 32 MB e 8 MB por 60 segundos. Comandos que devolvem respostas enormes, como `KEYS *` ou `HGETALL`/`SMEMBERS` em chaves gigantes, e assinantes que leem devagar demais são cortados. Itere com `SCAN`, `HSCAN` e `SSCAN` no lugar.

## Persistência

* O Redis salva os dados em disco **a cada 60 segundos quando houve pelo menos uma escrita**. Não há append-only file, então uma queda ou uma parada por falta de memória perde até os últimos \~60 segundos de escritas. Mantenha os dados que você não pode perder também em um banco de dados principal.
* Se um save falha (armazenamento cheio, ou memória insuficiente para salvar), as escritas respondem `MISCONF` até um save dar certo, e os snapshots falham enquanto isso. Um save precisa de armazenamento livre ao lado do arquivo de dados atual, mais ou menos do tamanho dos dados.

## Redefinição de senha

Redefinir a senha reinicia o Redis, que só lê a senha quando inicia: ele fica offline por alguns segundos e todas as conexões são fechadas. Atualize a URL nas suas aplicações e deixe que elas reconectem.

## Snapshots

Um snapshot do Redis é o arquivo de dados salvo. Restaurar um traz os dados de volta e mantém a senha atual do banco. Veja [snapshots e restauração](https://docs.squarecloud.app/pt-br/services/databases.md#snapshots-e-restauração).

## Erros comuns

| Mensagem | O que significa | O que fazer |
| :- | :- | :- |
| A conexão fecha na hora, `ECONNRESET` ou timeout | A URL usa `redis://`, sem TLS. | Use `rediss://`. |
| `OOM command not allowed when used memory > 'maxmemory'` | A memória está cheia, e nada é removido. | Defina expiração nas chaves de cache, apague dados ou aumente a RAM. |
| `MISCONF Redis is configured to save RDB snapshots, but it's currently unable to persist to disk` | O último save falhou. | Libere armazenamento e memória; as escritas voltam depois que um save der certo. |
| `ERR DB index is out of range` | Só existe o banco 0. | Use prefixos de chave em vez de `SELECT`. |
| `NOPERM ... has no permissions to run the '...' command` | O comando está bloqueado. | Use `SCAN` + `UNLINK` em vez de `FLUSHALL`/`FLUSHDB`. |
| `max number of clients reached` | As 256 conexões estão em uso. | Reutilize um cliente por processo. |

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.