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

# Redis

> Laravel 애플리케이션에서 Redis를 사용한 캐시·세션·큐·Pub/Sub의 설정과 조작 방법

Redis는 인메모리 키·밸류 스토어로, Laravel의 많은 기능의 백엔드로서 사용됩니다.
설정부터 조작·Pub/Sub까지, Laravel에서의 Redis 사용법을 설명합니다.

<CardGroup cols={3}>
  <Card title="캐시" icon="database" href="/ko/cache">
    Redis를 캐시 드라이버로서 사용
  </Card>

  <Card title="큐" icon="list" href="/ko/queues">
    Redis를 큐 드라이버로서 사용
  </Card>

  <Card title="브로드캐스트" icon="radio" href="/ko/broadcasting">
    Pub/Sub로 실시간 통신
  </Card>
</CardGroup>

## Redis란

[Redis](https://redis.io)는 오픈소스의 고속 키·밸류 스토어입니다.
문자열·해시·리스트·셋·소트된 셋 등 다양한 데이터 구조를 지원하여, 데이터 구조 서버라고도 불립니다.

Laravel에서는 아래의 용도로 Redis가 사용됩니다.

```mermaid theme={null}
flowchart LR
    A["Laravel<br>애플리케이션"] --> B["Redis"]

    subgraph uses ["주요 용도"]
        C["캐시<br>Cache"]
        D["세션<br>Session"]
        E["큐<br>Queue"]
        F["브로드캐스트<br>Broadcasting"]
    end

    B --> C
    B --> D
    B --> E
    B --> F
```

## 클라이언트 선택

Laravel은 **PhpRedis**(PHP 확장)와 **Predis**(PHP 패키지)의 2개의 클라이언트를 지원합니다.

| 항목           | PhpRedis        | Predis                 |
| ------------ | --------------- | ---------------------- |
| 구현           | C 언어에 의한 PHP 확장 | 순수한 PHP 패키지            |
| 설치           | PECL 확장이 필요     | `composer require`로 완결 |
| 성능           | 고속              | PhpRedis보다 약간 저속       |
| Laravel Sail | 기본으로 도입 완료      | 별도 설치가 필요              |
| 권장 환경        | 프로덕션 환경         | 개발 환경·설치가 어려운 환경       |

<Info>
  Laravel 13에서는 기본 클라이언트가 PhpRedis입니다. 프로덕션 환경에서는 PhpRedis의 사용을 권장합니다.
  Laravel Sail을 사용하고 있는 경우는 PhpRedis가 이미 설치되어 있습니다.
</Info>

## 설정

### config/database.php

Redis의 설정은 `config/database.php`의 `redis` 배열에서 관리합니다.

```php theme={null}
'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'default' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],

    'cache' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_CACHE_DB', '1'),
    ],

],
```

### 환경 변수

`.env`에서 접속처를 설정합니다.

```ini theme={null}
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1
```

URL 형식으로 지정하는 것도 가능합니다.

```php theme={null}
'default' => [
    'url' => 'tcp://127.0.0.1:6379?database=0',
],

'cache' => [
    'url' => 'tls://user:password@127.0.0.1:6380?database=1',
],
```

### TLS / SSL 접속

TLS 암호화를 사용하는 경우는 `scheme` 옵션을 지정합니다.

```php theme={null}
'default' => [
    'scheme' => 'tls',
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
],
```

### 클러스터링

여러 Redis 서버를 클러스터로서 사용하는 경우는 `clusters` 키를 사용합니다.

```php theme={null}
'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'clusters' => [
        'default' => [
            [
                'url' => env('REDIS_URL'),
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'username' => env('REDIS_USERNAME'),
                'password' => env('REDIS_PASSWORD'),
                'port' => env('REDIS_PORT', '6379'),
                'database' => env('REDIS_DB', '0'),
            ],
        ],
    ],

],
```

기본적으로 `options.cluster`가 `redis`로 설정되어 있어 네이티브 Redis 클러스터링이 사용됩니다.
페일오버를 자동으로 처리하기 때문에, 프로덕션 환경에서 권장하는 설정입니다.

Predis에서 클라이언트 사이드 샤딩을 사용하는 경우는 `options.cluster`를 삭제합니다.
단, 클라이언트 사이드 샤딩은 페일오버를 처리하지 않기 때문에, 캐시 등 일시적인 데이터에만 적합합니다.

### Predis 설정

Predis를 사용하려면 `predis/predis` 패키지를 설치하고, `REDIS_CLIENT`를 `predis`로 변경합니다.

```shell theme={null}
composer require predis/predis
```

```ini theme={null}
REDIS_CLIENT=predis
```

Predis 고유의 [접속 파라미터](https://github.com/nrk/predis/wiki/Connection-Parameters)를 추가할 수 있습니다.

```php theme={null}
'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_write_timeout' => 60,
],
```

#### Predis의 리트라이 설정

Predis 3.4.0 이후에서는 조립된 리트라이·백오프 설정을 이용할 수 있습니다. `max_retries` 옵션으로 리트라이 횟수를, `retry` 옵션으로 백오프 전략을 설정합니다. `retry` 옵션에는 `NoBackoff`, `EqualBackoff`, `ExponentialBackoff` 중 어느 하나의 클래스명을 키로 한 배열을 지정합니다.

```php theme={null}
use Predis\Retry\Strategy\ExponentialBackoff;

'default' => [
    'url' => env('REDIS_URL'),
    // ...
    'retry' => [
        ExponentialBackoff::class => [
            env('REDIS_BACKOFF_BASE', 100),
            env('REDIS_BACKOFF_CAP', 1000),
            true, // 지터를 활성화
        ],
    ],
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
],
```

Redis 클러스터에서 Predis를 사용하는 경우는, 클러스터 설정의 `parameters` 옵션에서 리트라이를 설정합니다.

```php theme={null}
use Predis\Retry\Strategy\NoBackoff;

'clusters' => [
    'default' => [
        // ...
    ],
],

'options' => [
    'cluster' => env('REDIS_CLUSTER', 'redis'),
    'parameters' => [
        'retry' => [
            NoBackoff::class => [],
        ],
        'max_retries' => env('REDIS_MAX_RETRIES', 3),
    ],
],
```

### PhpRedis 설정

PhpRedis는 PECL을 경유해 설치합니다(Laravel Sail에서는 도입 완료).
PhpRedis는 이하의 추가 옵션을 지원합니다:
`name`, `persistent`, `persistent_id`, `prefix`, `read_timeout`, `retry_interval`,
`max_retries`, `backoff_algorithm`, `backoff_base`, `backoff_cap`, `timeout`, `context`

```php theme={null}
'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_timeout' => 60,
    'context' => [
        // 'auth' => ['username', 'secret'],
        // 'stream' => ['verify_peer' => false],
    ],
],
```

#### 리트라이와 백오프 설정

접속 실패 시의 리트라이 동작을 설정합니다.
지원되는 백오프 알고리즘: `default`, `decorrelated_jitter`, `equal_jitter`, `exponential`, `uniform`, `constant`

```php theme={null}
'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
    'backoff_algorithm' => env('REDIS_BACKOFF_ALGORITHM', 'decorrelated_jitter'),
    'backoff_base' => env('REDIS_BACKOFF_BASE', 100),
    'backoff_cap' => env('REDIS_BACKOFF_CAP', 1000),
],
```

#### Unix 소켓 접속

동일 서버 위의 Redis에 접속하는 경우, Unix 소켓을 사용하면 TCP 오버헤드를 삭감할 수 있습니다.

```ini theme={null}
REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0
```

#### 시리얼라이즈와 압축

PhpRedis에서는 보존 데이터의 시리얼라이즈와 압축 알고리즘을 설정할 수 있습니다.

```php theme={null}
'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
        'serializer' => Redis::SERIALIZER_MSGPACK,
        'compression' => Redis::COMPRESSION_LZ4,
    ],

],
```

지원되는 시리얼라이저:

| 상수                           | 설명              |
| ---------------------------- | --------------- |
| `Redis::SERIALIZER_NONE`     | 시리얼라이즈 없음 (기본값) |
| `Redis::SERIALIZER_PHP`      | PHP의 시리얼라이즈     |
| `Redis::SERIALIZER_JSON`     | JSON            |
| `Redis::SERIALIZER_IGBINARY` | igbinary        |
| `Redis::SERIALIZER_MSGPACK`  | MessagePack     |

지원되는 압축 알고리즘:

| 상수                        | 설명          |
| ------------------------- | ----------- |
| `Redis::COMPRESSION_NONE` | 압축 없음 (기본값) |
| `Redis::COMPRESSION_LZF`  | LZF         |
| `Redis::COMPRESSION_ZSTD` | Zstandard   |
| `Redis::COMPRESSION_LZ4`  | LZ4         |

## Redis와의 조작

### Redis 파사드

`Redis` 파사드를 사용해 모든 Redis 명령을 실행할 수 있습니다.
파사드는 매직 메서드로 명령을 Redis 서버에 전송합니다.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Redis;
use Illuminate\View\View;

class UserController extends Controller
{
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => Redis::get('user:profile:'.$id)
        ]);
    }
}
```

인수를 받는 명령은 그대로 메서드의 인수로 전달합니다.

```php theme={null}
use Illuminate\Support\Facades\Redis;

Redis::set('name', 'Taylor');

$values = Redis::lrange('names', 5, 10);
```

`command` 메서드를 사용해 명령명과 인수를 명시적으로 지정할 수도 있습니다.

```php theme={null}
$values = Redis::command('lrange', ['name', 5, 10]);
```

### 여러 접속의 구분 사용

`config/database.php`에서 여러 Redis 접속을 정의하고, `connection()` 메서드로 전환할 수 있습니다.

```php theme={null}
// 이름 붙은 접속을 취득
$redis = Redis::connection('connection-name');

// 기본 접속을 취득
$redis = Redis::connection();
```

### 트랜잭션

`transaction()` 메서드는 Redis의 `MULTI`/`EXEC` 명령을 래핑합니다.
클로저 내의 모든 명령이 아토믹하게 실행됩니다.

```php theme={null}
use Redis;
use Illuminate\Support\Facades;

Facades\Redis::transaction(function (Redis $redis) {
    $redis->incr('user_visits', 1);
    $redis->incr('total_visits', 1);
});
```

<Warning>
  트랜잭션 내에서는 Redis로부터 값을 취득할 수 없습니다.
  클로저 전체가 실행되고 나서 `EXEC`로 통째로 실행되기 때문입니다.
</Warning>

### Lua 스크립트

`eval()` 메서드로 Lua 스크립트를 아토믹하게 실행할 수 있습니다.
스크립트 내에서 Redis의 값을 참조·업데이트할 수 있는 점에서 트랜잭션보다 유연합니다.

```php theme={null}
$value = Redis::eval(<<<'LUA'
    local counter = redis.call("incr", KEYS[1])

    if counter > 5 then
        redis.call("incr", KEYS[2])
    end

    return counter
LUA, 2, 'first-counter', 'second-counter');
```

인수의 순서: Lua 스크립트 → 키 수 → 키명... → 추가 인수...

`KEYS[1]`, `KEYS[2]`가 키명, `ARGV[1]` 이후가 추가 인수로서 전달됩니다.

### 파이프라인

대량의 명령을 한 번에 송신해 네트워크의 왕복을 삭감할 수 있습니다.

```php theme={null}
use Redis;
use Illuminate\Support\Facades;

Facades\Redis::pipeline(function (Redis $pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", $i);
    }
});
```

```mermaid theme={null}
sequenceDiagram
    participant App as Laravel<br>앱
    participant Redis

    Note over App,Redis: 통상 (명령마다 왕복)
    App->>Redis: SET key:0 0
    Redis-->>App: OK
    App->>Redis: SET key:1 1
    Redis-->>App: OK

    Note over App,Redis: 파이프라인 (한꺼번에 송신)
    App->>Redis: SET key:0 0 / SET key:1 1 / ...
    Redis-->>App: OK / OK / ...
```

<Tip>
  파이프라인은 명령을 한꺼번에 송신할 뿐, 아토믹하지 않습니다.
  아토믹한 조작이 필요한 경우는 트랜잭션 또는 Lua 스크립트를 사용해 주세요.
</Tip>

## Pub / Sub

Redis의 `publish` / `subscribe` 명령을 사용해 채널 경유로 메시지를 주고받을 수 있습니다.

### 서브스크라이버

`subscribe()`는 오랜 시간 동작하는 프로세스이므로, Artisan 명령 내에서 호출합니다.

```php theme={null}
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Redis;

class RedisSubscribe extends Command
{
    protected $signature = 'redis:subscribe';

    protected $description = 'Subscribe to a Redis channel';

    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}
```

### 퍼블리셔

다른 리퀘스트나 프로세스에서 메시지를 송신합니다.

```php theme={null}
use Illuminate\Support\Facades\Redis;

Route::get('/publish', function () {
    Redis::publish('test-channel', json_encode([
        'name' => 'Adam Wathan'
    ]));
});
```

### 와일드카드 서브스크립션

`psubscribe()`로 패턴 매칭 서브스크립션을 할 수 있습니다.

```php theme={null}
// 모든 채널을 구독
Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

// users.* 패턴의 채널을 구독
Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});
```

## 정리

<AccordionGroup>
  <Accordion title="클라이언트 선택">
    * **프로덕션 환경**: PhpRedis (PECL 확장, 고성능)
    * **개발 환경·설치가 어려운 경우**: Predis (Composer 패키지)
    * **Laravel Sail**: PhpRedis가 기본으로 도입 완료
  </Accordion>

  <Accordion title="접속 설정의 포인트">
    * 여러 Redis 접속은 `config/database.php`에서 정의하고, 용도별로 구분 사용 (`default` / `cache` 등)
    * 클러스터 환경에서는 `clusters` 키를 사용
    * 프로덕션 환경에서는 TLS 접속과 인증 정보의 설정을 검토
  </Accordion>

  <Accordion title="조작의 구분 사용">
    | 조작                          | 용도                         |
    | --------------------------- | -------------------------- |
    | 파사드 메서드                     | 통상의 Redis 명령               |
    | `transaction()`             | 여러 명령의 아토믹 실행 (값의 읽기는 불가)  |
    | `eval()`                    | Lua 스크립트 (읽기를 수반하는 아토믹 조작) |
    | `pipeline()`                | 대량 명령의 고속 송신 (비아토믹)        |
    | `subscribe()` / `publish()` | 채널 메시징 (Pub/Sub)           |
  </Accordion>
</AccordionGroup>


## Related topics

- [Laravel Sail](/ko/sail.md)
- [캐시](/ko/cache.md)
- [레이트 리밋 커스터마이즈](/ko/advanced/rate-limiting.md)
- [큐와 잡](/ko/queues.md)
- [Laravel Pulse](/ko/pulse.md)