Redis

번역일: 2026년 6월 20일

Redis

소개
설정
Redis 사용하기
- 트랜잭션
- 파이프라이닝
Pub / Sub

소개

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

Laravel에서 Redis를 사용하기 전에, PECL을 통해 PhpRedis PHP 확장 모듈을 설치하는 것을 권장합니다. 순수 PHP로 작성된 패키지에 비해 설치가 다소 복잡하지만, Redis를 집중적으로 사용하는 애플리케이션에서 더 나은 성능을 발휘합니다. Laravel Sail을 사용 중이라면 Docker 컨테이너에 이미 설치되어 있습니다.

PhpRedis 확장 모듈을 설치할 수 없는 환경이라면, Composer로 predis/predis 패키지를 설치할 수 있습니다. Predis는 순수 PHP로 작성된 Redis 클라이언트로, 별도의 확장 모듈이 필요하지 않습니다.

composer require predis/predis

설정

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

'redis' => [

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

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

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

],

각 Redis 서버 설정에는 이름, 호스트, 포트가 필요합니다. 단, 아래처럼 URL 하나로 연결 정보를 표현할 수도 있습니다.

'redis' => [

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

    '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 옵션을 추가하세요.

'redis' => [

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

    'default' => [
        'scheme' => 'tls',
        'host' => env('REDIS_HOST', '127.0.0.1'),
        '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'),

    'clusters' => [
        'default' => [
            [
                'host' => env('REDIS_HOST', 'localhost'),
                'password' => env('REDIS_PASSWORD'),
                'port' => env('REDIS_PORT', 6379),
                'database' => 0,
            ],
        ],
    ],

],

기본 설정에서는 클라이언트 사이드 샤딩(client-side sharding)이 적용되어, 여러 노드에 데이터를 분산해 전체 메모리를 효율적으로 활용합니다. 다만 클라이언트 사이드 샤딩은 자동 장애 복구(failover)를 지원하지 않으므로, 주로 다른 데이터 저장소에 원본이 있는 임시 캐시 데이터에 적합합니다.

네이티브 Redis 클러스터링을 사용하려면, options.cluster 값을 redis로 설정하세요.

'redis' => [

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

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
    ],

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

],

Predis

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

'redis' => [

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

    // ...
],

Predis는 기본 옵션(host, port, database, password) 외에 추가적인 연결 파라미터도 지원합니다. 필요한 옵션은 config/database.php의 서버 설정에 추가하면 됩니다.

'default' => [
    'host' => env('REDIS_HOST', 'localhost'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', 6379),
    'database' => 0,
    'read_write_timeout' => 60,
],

Redis 파사드 별칭

config/app.php의 aliases 배열에는 프레임워크가 등록하는 클래스 별칭들이 정의되어 있습니다. 기본적으로 Redis 별칭은 포함되지 않는데, 이는 PhpRedis 확장 모듈이 제공하는 Redis 클래스명과 충돌하기 때문입니다. Predis 클라이언트를 사용하면서 Redis 별칭을 등록하고 싶다면 아래와 같이 추가할 수 있습니다.

'aliases' => Facade::defaultAliases()->merge([
    'Redis' => Illuminate\Support\Facades\Redis::class,
])->toArray(),

PhpRedis

Laravel은 기본적으로 PhpRedis 확장 모듈을 사용하여 Redis와 통신합니다. 사용할 클라이언트는 redis.client 설정 값(주로 REDIS_CLIENT 환경 변수)으로 결정됩니다.

'redis' => [

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

    // 나머지 Redis 설정...
],

PhpRedis는 기본 옵션(scheme, host, port, database, password) 외에 name, persistent, persistent_id, prefix, read_timeout, retry_interval, timeout, context 등의 추가 파라미터를 지원합니다. 필요한 옵션을 config/database.php의 서버 설정에 추가하세요.

'default' => [
    'host' => env('REDIS_HOST', 'localhost'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', 6379),
    'database' => 0,
    'read_timeout' => 60,
    'context' => [
        // 'auth' => ['username', 'secret'],
        // 'stream' => ['verify_peer' => false],
    ],
],

PhpRedis 직렬화 및 압축

PhpRedis는 다양한 직렬화 방식과 압축 알고리즘을 지원합니다. Redis 설정의 options 배열에서 구성할 수 있습니다.

'redis' => [

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

    'options' => [
        'serializer' => Redis::SERIALIZER_MSGPACK,
        'compression' => Redis::COMPRESSION_LZ4,
    ],

    // 나머지 Redis 설정...
],

지원하는 직렬화 방식: 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 서버로 전달됩니다. 아래 예시는 GET 커맨드를 사용하는 방법입니다.

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
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', '홍길동');

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

command 메서드를 사용하면 커맨드명과 인자 배열을 명시적으로 전달할 수도 있습니다.

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

여러 Redis 연결 사용하기

config/database.php에 여러 Redis 연결을 정의한 경우, connection 메서드에 연결 이름을 전달하여 특정 연결 인스턴스를 가져올 수 있습니다.

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

인자 없이 호출하면 기본 연결 인스턴스가 반환됩니다.

$redis = Redis::connection();

트랜잭션

Redis 파사드의 transaction 메서드는 Redis의 MULTI / EXEC 커맨드를 편리하게 감싼 래퍼입니다. 클로저 하나를 인자로 받으며, 클로저 안에서 실행한 모든 Redis 커맨드는 하나의 원자적(atomic) 트랜잭션으로 처리됩니다.

use Redis;
use Illuminate\Support\Facades;

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

WARNING

Redis 트랜잭션 안에서는 값을 읽어올 수 없습니다. 트랜잭션은 클로저의 모든 커맨드가 쌓인 뒤 한 번에 원자적으로 실행되므로, 클로저 실행 중에는 중간 결과를 조회할 수 없습니다.

Lua 스크립트

eval 메서드를 사용하면 Lua 스크립트를 통해 여러 Redis 커맨드를 원자적으로 실행하면서, 실행 도중 키의 값을 읽고 조건 분기도 처리할 수 있습니다. 이는 transaction으로는 불가능한 작업입니다.

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

파이프라이닝은 트랜잭션과 다릅니다. 커맨드를 묶어 전송하여 네트워크 비용을 줄이는 것이 목적이며, 원자성을 보장하지는 않습니다.

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' => '홍길동'
    ]));
});

와일드카드 구독

psubscribe 메서드를 사용하면 와일드카드 패턴으로 여러 채널을 한 번에 구독할 수 있습니다. 클로저의 두 번째 인자로 실제 채널 이름이 전달됩니다.

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

// 'users.'로 시작하는 모든 채널 구독
Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});