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

# Redis

> Connect Redis to CloudThinker for cache performance monitoring across self-hosted, Upstash, or Redis Cloud deployments

Connect your Redis databases to enable [Tony](/guide/agents/tony) (Database Engineer) to inspect keyspace usage, analyze command patterns, and monitor database health.

## Supported platforms

| Platform              | Support                            |
| --------------------- | ---------------------------------- |
| **Self-hosted Redis** | 6.x, 7.x (vanilla and Redis Stack) |
| **Upstash Redis**     | All plan tiers                     |
| **Redis Cloud**       | All plan tiers                     |

## Prerequisites

* A Redis instance reachable from CloudThinker over the network.
* Admin access to create an ACL user (self-hosted) or RBAC user (Upstash/Redis Cloud).
* A `REDIS_URL` connection string with credentials.

## Setup

Select your Redis platform for specific connection instructions.

<Tabs>
  <Tab title="Self-hosted Redis">
    Two common deployment shapes are supported:

    * **Vanilla Redis** — minimal image, no modules. Use when you only need core Redis commands.
    * **Redis Stack** — bundles RediSearch, RedisJSON, RedisTimeSeries, and Bloom. Use when Tony needs `FT.*`, `JSON.*`, `TS.*`, or `BF.*` commands. Vanilla soft-fails those.

    <Steps>
      <Step title="Start Redis">
        **Vanilla Redis (no modules):**

        ```bash theme={null}
        docker run -d --name redis-min \
          -p 6379:6379 \
          redis:7-alpine \
          redis-server --requirepass <admin-password> --appendonly yes
        ```

        The admin password is set via the `--requirepass` server flag. `--appendonly yes` enables AOF for durability across restarts.

        **Redis Stack (with modules and RedisInsight UI on port 8001):**

        ```bash theme={null}
        docker run -d --name redis-stack \
          -p 6379:6379 -p 8001:8001 \
          -e REDIS_ARGS="--requirepass <admin-password>" \
          redis/redis-stack:latest
        ```

        Verify the instance:

        ```bash theme={null}
        redis-cli -a <admin-password> ping
        # PONG
        ```
      </Step>

      <Step title="Create a read-only ACL user">
        Create a dedicated user for CloudThinker. Redis ACL usernames allow `[A-Za-z0-9_-]`; use `cloudthinker-readonly`.

        ```bash theme={null}
        redis-cli -a <admin-password> ACL SETUSER cloudthinker-readonly on \
          '><readonly-password>' \
          '~*' \
          '+@read' '-@write' '-@dangerous' '-@admin'
        ```

        * `on` — enable the user
        * `><readonly-password>` — set the password (the `>` prefix is ACL syntax)
        * `~*` — match all keys; narrow to `~app:*` for stricter scoping
        * `+@read -@write -@dangerous -@admin` — reads only; blocks writes, `FLUSHALL`/`CONFIG`/`DEBUG`/`SHUTDOWN`, and replication
        * Optional: append `-@slow` to block `KEYS`, `SMEMBERS`, `HGETALL` on large collections
      </Step>

      <Step title="Persist ACLs across restart">
        Mount a `users.acl` file so ACLs survive container restarts:

        ```text theme={null}
        user default on ><admin-password> ~* &* +@all
        user cloudthinker-readonly on ><readonly-password> ~* +@read -@write -@dangerous -@admin
        ```

        Start Redis with the file mounted:

        ```bash theme={null}
        -v $PWD/users.acl:/data/users.acl
        ```

        and add `--aclfile /data/users.acl` to the server command.
      </Step>

      <Step title="Verify the read-only user">
        ```bash theme={null}
        redis-cli -u redis://cloudthinker-readonly:<readonly-password>@localhost:6379 SET foo bar
        # (error) NOPERM ... has no permissions to run the 'set' command

        redis-cli -u redis://cloudthinker-readonly:<readonly-password>@localhost:6379 GET foo
        # works
        ```
      </Step>

      <Step title="Configure network access">
        Ensure CloudThinker can reach your database:

        * Add CloudThinker IPs to your firewall or security group
        * Ensure Redis is bound to an accessible interface (avoid `bind 127.0.0.1` only)
      </Step>

      <Step title="Add the connection in CloudThinker">
        Navigate to **Connections → Redis** and enter your connection string as **REDIS\_URL**:

        ```
        redis://cloudthinker-readonly:<readonly-password>@<your-host>:6379
        ```

        Use `rediss://` (note the second `s`) if your deployment terminates TLS. Click **Connect**. CloudThinker shows a **Connected** status once it succeeds.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Upstash Redis">
    <Steps>
      <Step title="Create a database">
        Open the [Upstash Redis console](https://console.upstash.com/redis) and click **Create Database**. In the modal:

        * Enter a **Database Name**
        * Pick a **Primary Region** and **Cloud Provider**
        * Enable **Eviction** (recommended)
        * Click **Next**, choose your plan, and confirm
      </Step>

      <Step title="Copy the TCP connection URL">
        On the database page, scroll to the **Connection** section. The default tab is **REST** — switch to the **TCP** tab and copy the URL:

        ```
        rediss://<username>:<password>@<hash>.upstash.io:<port>
        ```

        `<hash>` is unique to your database; `<port>` is typically `6379`. Upstash enforces TLS, so the scheme is `rediss://`.
      </Step>

      <Step title="Create a read-only user (optional)">
        Upstash supports RBAC under the **RBAC** tab on the database page. Activate RBAC, then create an account named `cloudthinker-readonly` with read-only permissions. The ACL model is the same as the self-hosted setup — grant `+@read` and deny `-@write`, `-@dangerous`, `-@admin`.

        See the [Upstash RBAC documentation](https://upstash.com/docs/redis/overall/enterprise#rbac) for the exact UI flow.
      </Step>

      <Step title="Add the connection in CloudThinker">
        Navigate to **Connections → Redis** and paste the URL as **REDIS\_URL**. Click **Connect**. CloudThinker shows a **Connected** status once it succeeds.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Redis Cloud">
    <Steps>
      <Step title="Create a database">
        Open the [Redis Cloud databases page](https://cloud.redis.io/#/databases) and click **New database**. Pick your plan, **Database Name**, **Database Version**, **Cloud Vendor**, and **Region**, then click **Create Database**.

        Return to the databases page — your new database appears in the list.
      </Step>

      <Step title="Copy the connection URL">
        On the database tile, find the **Connection to database** card and click **Connect**. In the side panel:

        * Close the default **Redis SDK clients** dropdown
        * Select **Redis CLI**
        * Copy the URL

        The URL follows this format:

        ```
        redis://<username>:<password>@<hash>.cloud.redislabs.com:<port>
        ```

        Redis Cloud ports are typically in the `13xxx` range rather than `6379`.
      </Step>

      <Step title="Create a read-only role and user">
        Open the [Data Access Control roles page](https://cloud.redis.io/#/data-access-control/roles):

        * Click **New role** and name it `cloudthinker-readonly`
        * Set **ACL Rules** to **Read-Only**
        * Pick the databases this role can access
        * Click **Save role**

        Then create or assign a user bound to this role and use that user's credentials in the connection URL.
      </Step>

      <Step title="Add the connection in CloudThinker">
        Navigate to **Connections → Redis** and paste the URL as **REDIS\_URL**. Click **Connect**. CloudThinker shows a **Connected** status once it succeeds.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connection details

| Field              | Description                                | Example                                              |
| ------------------ | ------------------------------------------ | ---------------------------------------------------- |
| **REDIS\_URL**     | Redis connection URI including credentials | `redis://cloudthinker-readonly:pass@host:6379`       |
| **TLS/SSL**        | Use `rediss://` scheme to require TLS      | `rediss://` for Upstash; optional elsewhere          |
| **Port**           | Redis port                                 | `6379` (self-hosted, Upstash); `13xxx` (Redis Cloud) |
| **Database index** | Logical DB index                           | `0`                                                  |

## Required permissions

Recommended ACL categories for the CloudThinker user:

| Category              | Setting | Why                                                          |
| --------------------- | ------- | ------------------------------------------------------------ |
| `+@read`              | Allow   | Read keys, run `INFO`, `CLIENT LIST`, etc.                   |
| `-@write`             | Deny    | Block `SET`, `DEL`, and other mutating commands              |
| `-@dangerous`         | Deny    | Block `FLUSHALL`, `CONFIG`, `DEBUG`, `SHUTDOWN`, replication |
| `-@admin`             | Deny    | Block administrative commands                                |
| `-@slow` *(optional)* | Deny    | Block `KEYS`, `SMEMBERS`, `HGETALL` on large collections     |

<Tip>
  Key scoping (`~*` for all keys, or `~app:*` for a prefix) narrows what the CloudThinker user can access. Start with `~*` and tighten as needed.
</Tip>

## Agent capabilities

Once connected, Tony can:

| Capability              | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| **Keyspace analysis**   | Inspect key patterns, sizes, and TTL distributions                                 |
| **Command stats**       | Review command latency and throughput via `INFO commandstats`                      |
| **Performance metrics** | Monitor memory, connections, eviction, and replication lag                         |
| **Module insights**     | Inspect RediSearch indexes, RedisJSON documents, and TimeSeries (Redis Stack only) |

### Verify the connection

```text theme={null}
@tony #report run Redis INFO and summarize memory usage, connected clients, and keyspace stats
```

### Example prompts

```text theme={null}
@tony #report analyze hot keys and memory distribution on the production Redis instance
@tony #report check memory fragmentation ratio and eviction stats
@tony #report review replication lag on the Redis replica
```

## Troubleshooting

<Accordion title="Authentication failed (NOAUTH / WRONGPASS)">
  * Verify the username and password in the connection URL
  * For self-hosted, confirm the user is enabled with `ACL WHOAMI` and `ACL LIST`
  * For Upstash and Redis Cloud, make sure you copied the TCP/Redis CLI URL, not the REST or SDK URL
</Accordion>

<Accordion title="NOPERM — no permissions to run the command">
  * The read-only user is working as intended for write commands
  * If reads are also blocked, re-check the ACL rules — `+@read` must be granted
</Accordion>

<Accordion title="Connection refused or timeout">
  * Verify host and port are reachable from CloudThinker
  * For self-hosted, ensure Redis is not bound only to `127.0.0.1`
  * Add CloudThinker IPs to your firewall or cloud provider allowlist
</Accordion>

<Accordion title="Module commands fail (FT.*, JSON.*, TS.*, BF.*)">
  * Vanilla Redis does not include modules. Run Redis Stack (`redis/redis-stack`) or a managed equivalent that bundles the required modules.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use rediss\:// for TLS** — use the `rediss://` scheme whenever your deployment supports TLS to encrypt data in transit.
- **Persist ACLs** — use `aclfile` for self-hosted deployments so the read-only user survives restarts.

## Related

<CardGroup cols={2}>
  <Card title="Tony Agent" icon="database" href="/guide/agents/tony">
    Database-focused optimization agent
  </Card>

  <Card title="MongoDB Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/mongodb.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=6ba4577251f89473df297fbc739af375" href="/guide/connections/mongodb" width="24" height="24" data-path="images/icons/mongodb.svg">
    Setup instructions for MongoDB databases
  </Card>
</CardGroup>