Redis

업데이트됨

번역일: 2026년 8월 19일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 8월 19일
번역 갱신: 2026년 8월 19일

Redis

소개
설정
Redis와 상호작용하기
- 트랜잭션
- 명령어 파이프라이닝
Pub / Sub

소개

Redis는 오픈 소스 고성능 키-값 저장소입니다. 키에 문자열, 해시, 리스트, 셋, 정렬된 셋 등 다양한 자료구조를 저장할 수 있어 "데이터 구조 서버"라고도 불립니다.

Laravel에서 Redis를 사용하기 전에, PECL을 통해 PhpRedis PHP 확장을 설치하고 사용하는 것을 권장합니다. 순수 PHP로 작성된 패키지보다 설치 과정이 다소 복잡하지만, Redis를 많이 활용하는 애플리케이션에서는 더 나은 성능을 기대할 수 있습니다. Laravel Sail을 사용한다면 이 확장이 Docker 컨테이너에 이미 설치되어 있습니다.

PhpRedis 확장을 설치하기 어렵다면, Composer를 통해 predis/predis 패키지를 대신 사용할 수 있습니다. Predis는 순수 PHP로 작성된 Redis 클라이언트로, 별도의 PHP 확장이 필요하지 않습니다.

composer require predis/predis

설정

Redis 설정은 config/database.php 파일에서 관리합니다. 이 파일 안에 redis 배열이 있으며, 여기서 애플리케이션이 사용할 Redis 서버를 정의합니다.

'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'),
    ],

],

각 Redis 서버 설정에는 name, host, port가 필요합니다. 단, 아래처럼 단일 URL로 연결 정보를 표현하는 경우에는 예외입니다.

'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' => 'tcp://127.0.0.1:6379?database=0',
    ],

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

],

연결 스킴 설정

기본적으로 Redis 클라이언트는 tcp 스킴으로 서버에 연결합니다. TLS/SSL 암호화 연결이 필요하다면, 서버 설정 배열에 scheme 옵션을 추가하세요.

'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 서버를 클러스터로 운영하는 경우, config/database.php의 redis 설정 안에 clusters 키를 추가하여 정의합니다. 이 키는 기본적으로 존재하지 않으므로 직접 추가해야 합니다.

'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로 설정되어 있으면 Laravel은 기본적으로 Redis 네이티브 클러스터링을 사용합니다. 네이티브 클러스터링은 페일오버를 자동으로 처리하므로 일반적인 상황에서 권장하는 방식입니다.

Predis를 사용하는 경우, 클라이언트 사이드 샤딩도 지원합니다. 다만 클라이언트 사이드 샤딩은 페일오버를 처리하지 않으므로, 다른 주요 데이터 저장소에서도 조회 가능한 임시 캐시 데이터에 적합합니다.

네이티브 클러스터링 대신 클라이언트 사이드 샤딩을 사용하려면, config/database.php에서 options.cluster 값을 제거하면 됩니다.

'redis' => [

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

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

    // ...
],

Predis

Predis 패키지를 통해 Redis를 사용하려면 REDIS_CLIENT 환경 변수를 predis로 설정하세요.

'redis' => [

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

    // ...
],

Predis는 기본 설정 옵션 외에도 서버별로 추가적인 연결 파라미터를 지정할 수 있습니다. 필요한 옵션은 config/database.php의 해당 서버 설정에 추가하세요.

'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,
],

PhpRedis

Laravel은 기본적으로 PhpRedis 확장을 사용하여 Redis와 통신합니다. 사용할 클라이언트는 redis.client 설정 옵션으로 결정되며, 일반적으로 REDIS_CLIENT 환경 변수 값을 반영합니다.

'redis' => [

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

    // ...
],

PhpRedis는 기본 옵션 외에도 다음 연결 파라미터를 추가로 지원합니다: name, persistent, persistent_id, prefix, read_timeout, retry_interval, max_retries, backoff_algorithm, backoff_base, backoff_cap, timeout, context. 필요한 옵션을 config/database.php의 서버 설정에 추가하세요.

'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],
    ],
],

재시도 및 백오프 설정

retry_interval, max_retries, backoff_algorithm, backoff_base, backoff_cap 옵션을 사용하면 PhpRedis 클라이언트가 Redis 서버에 재연결을 시도하는 방식을 제어할 수 있습니다. 지원하는 백오프 알고리즘은 default, decorrelated_jitter, equal_jitter, exponential, uniform, constant입니다.

'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),
],

Laravel은 일시적인 연결 오류가 발생할 경우 안전한 읽기 명령을 자동으로 한 번 재시도합니다. 모든 Redis 명령에 대한 재시도 횟수를 직접 지정하려면 command_retries 옵션을 사용하세요.

'default' => [
    // ...
    'command_retries' => env('REDIS_COMMAND_RETRIES', 0),
],

Predis 3.4.0 이상에서는 Retry 클래스를 통한 내장 재시도 및 백오프 설정을 지원합니다. max_retries 옵션으로 재시도 횟수를, retry 옵션으로 백오프 전략을 설정할 수 있습니다. retry 옵션의 키는 NoBackoff, EqualBackoff, ExponentialBackoff 중 하나의 전략 클래스여야 합니다.

use Predis\Retry\Strategy\ExponentialBackoff;

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

Predis와 Redis 클러스터를 함께 사용하는 경우, 클러스터 설정의 parameters 옵션에서 재시도 설정을 정의할 수 있습니다.

use Predis\Retry\Strategy\NoBackoff;

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

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

Unix 소켓 연결

Redis 연결을 TCP 대신 Unix 소켓으로 구성할 수도 있습니다. Redis 서버와 애플리케이션이 같은 서버에 있다면 TCP 오버헤드를 줄여 성능을 개선할 수 있습니다. Unix 소켓을 사용하려면 REDIS_HOST 환경 변수에 소켓 파일 경로를, REDIS_PORT에 0을 설정하세요.

REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0

PhpRedis 직렬화 및 압축

PhpRedis 확장은 다양한 직렬화 방식과 압축 알고리즘을 지원합니다. Redis 설정의 options 배열을 통해 설정할 수 있습니다.

'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, Redis::SERIALIZER_JSON, Redis::SERIALIZER_IGBINARY, Redis::SERIALIZER_MSGPACK

지원하는 압축 알고리즘: Redis::COMPRESSION_NONE (기본값), Redis::COMPRESSION_LZF, Redis::COMPRESSION_ZSTD, Redis::COMPRESSION_LZ4

Redis와 상호작용하기

Redis 파사드의 다양한 메서드를 호출하여 Redis와 상호작용할 수 있습니다. Redis 파사드는 동적 메서드를 지원하므로, Redis 공식 명령어를 파사드에서 그대로 호출하면 해당 명령이 Redis 서버로 전달됩니다. 아래 예시는 Redis 파사드의 get 메서드로 Redis GET 명령을 실행합니다.

<?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)
        ]);
    }
}

위에서 설명한 것처럼, Redis 명령어라면 무엇이든 Redis 파사드에서 호출할 수 있습니다. 인수가 필요한 명령어는 파사드 메서드에 그대로 전달하면 됩니다.

use Illuminate\Support\Facades\Redis;

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

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

command 메서드를 사용하면 명령어 이름과 인수 배열을 직접 전달하는 방식으로도 실행할 수 있습니다.

$values = Redis::command('lrange', ['name', 5, 10]);

여러 Redis 연결 사용하기

config/database.php에서 여러 Redis 연결/서버를 정의했다면, Redis 파사드의 connection 메서드로 특정 연결 인스턴스를 가져올 수 있습니다.

$redis = Redis::connection('connection-name');

인수 없이 호출하면 기본 Redis 연결 인스턴스를 반환합니다.

$redis = Redis::connection();

트랜잭션

Redis 파사드의 transaction 메서드는 Redis의 MULTI와 EXEC 명령을 편리하게 감싼 래퍼입니다. 클로저 하나를 인수로 받으며, 클로저 안에서 Redis 연결 인스턴스를 통해 명령을 실행합니다. 클로저 내의 모든 Redis 명령은 단일 원자적 트랜잭션으로 실행됩니다.

use Redis;
use Illuminate\Support\Facades;

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

WARNING

Redis 트랜잭션 내에서는 Redis 연결로부터 값을 읽어올 수 없습니다. 트랜잭션은 클로저의 모든 명령이 쌓인 후 하나의 원자적 작업으로 한 번에 실행되기 때문입니다.

Lua 스크립트

eval 메서드를 사용하면 Lua 스크립트를 통해 여러 Redis 명령을 단일 원자적 작업으로 실행할 수 있습니다. transaction과의 차이점은, 실행 도중 Redis 키 값을 읽고 조건 분기하는 등 더 복잡한 로직을 처리할 수 있다는 점입니다. Redis 스크립트는 Lua 프로그래밍 언어로 작성합니다.

eval 메서드의 인수 순서는 다음과 같습니다.

Lua 스크립트 (문자열)
스크립트가 다루는 키의 개수 (정수)
키 이름들
스크립트 내에서 사용할 추가 인수

아래 예시는 카운터를 증가시키고, 값이 5를 초과하면 두 번째 카운터도 증가시킨 뒤 첫 번째 카운터 값을 반환합니다.

$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');

WARNING

Redis 스크립팅에 대한 더 자세한 내용은 Redis 공식 문서를 참고하세요.

명령어 파이프라이닝

수십 개의 Redis 명령을 실행해야 할 때, 명령마다 네트워크 왕복이 발생하면 성능이 저하될 수 있습니다. pipeline 메서드를 사용하면 모든 명령을 한 번에 서버로 전송하여 네트워크 왕복 횟수를 줄일 수 있습니다. 명령은 작성한 순서대로 실행됩니다.

use Redis;
use Illuminate\Support\Facades;

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

NOTE

파이프라이닝과 트랜잭션의 차이: 파이프라이닝은 네트워크 효율을 위해 명령을 일괄 전송하는 것이고, 트랜잭션은 원자성(atomicity) 보장을 위해 MULTI/EXEC로 묶는 것입니다. 필요에 따라 적절히 선택하세요.

Pub / Sub

Laravel은 Redis의 publish와 subscribe 명령을 편리하게 사용할 수 있는 인터페이스를 제공합니다. 이를 통해 특정 "채널"에서 메시지를 수신하거나 발행할 수 있으며, 다른 애플리케이션이나 다른 언어로 작성된 프로세스와도 손쉽게 통신할 수 있습니다.

먼저 subscribe 메서드로 채널 리스너를 설정합니다. subscribe는 장시간 실행되는 프로세스를 시작하므로, Artisan 커맨드 안에서 호출하는 것이 적합합니다.

<?php

namespace App\Console\Commands;

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

class RedisSubscribe extends Command
{
    /**
     * 콘솔 커맨드의 이름 및 시그니처.
     *
     * @var string
     */
    protected $signature = 'redis:subscribe';

    /**
     * 콘솔 커맨드 설명.
     *
     * @var string
     */
    protected $description = 'Redis 채널을 구독합니다';

    /**
     * 콘솔 커맨드 실행.
     */
    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}

이제 publish 메서드로 채널에 메시지를 발행할 수 있습니다.

use Illuminate\Support\Facades\Redis;

Route::get('/publish', function () {
    // ...

    Redis::publish('test-channel', json_encode([
        'name' => 'Adam Wathan'
    ]));
});

와일드카드 구독

psubscribe 메서드를 사용하면 와일드카드 패턴으로 채널을 구독할 수 있습니다. 모든 채널의 메시지를 한 번에 처리할 때 유용합니다. 채널 이름은 클로저의 두 번째 인수로 전달됩니다.

Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});