Redis CLI

Redis CLI (Redis CLI)

Redis에는 명령줄 인터페이스인 redis-cli가 딸려 있어요. 이 도구 하나로 서버에 연결해 명령을 하나씩 실행할 수도 있고, 스크립트에서 쓸 수 있도록 한 줄짜리 명령을 만들어 낼 수도 있으며, 인터랙티브하게 주고받으며 놀 수도 있어요. 이 문서에서는 redis-cli의 설치 방법부터 특수 모드까지, 실제로 자주 쓰는 부분을 중심으로 하나씩 따라가 볼게요.

출처: 공식문서

redis-cli 설치하기 (Install redis-cli)

redis-cli를 설치하거나 사용하는 방법은 여러 가지가 있는데요, 가장 쉬운 방법은 Linux나 macOS용 단독 redis-cli 바이너리를 설치하는 거예요. 그 밖에 이런 방법들도 있어요:

  • Redis Open Source를 설치하면 각 설치 방법에 redis-cli 유틸리티가 함께 딸려 옵니다.
  • 소스에서 Redis를 빌드하는 대신, 아래 명령 하나만 실행해도 돼요:
$ make redis-cli

redis-cli 유틸리티는 /path/to/redis-source/src 디렉터리에 /path/to/redis-source/src/redis-cli로 빌드됩니다.

Redis를 설치하고 싶지 않다면, Docker에서 redis-cli를 실행할 수도 있어요.

명령줄 사용법 (Command line usage)

터미널에 표준 출력을 내보내면서 Redis 명령 하나를 실행하려면, redis-cli의 별도 인자로 실행할 명령을 넣으면 돼요:

$ redis-cli INCR mycounter
(integer) 7

(integer)가 출력에서 빠지는데, 이는 redis-cli가 출력이 더 이상 터미널로 쓰이지 않는다는 걸 감지하기 때문이에요. 터미널에서도 원시 출력(raw output)을 강제로 보고 싶다면 --raw 옵션을 쓰면 돼요:

$ redis-cli --raw INCR mycounter
9

문자열 인용과 이스케이프 (String quoting and escaping)

redis-cli가 명령을 파싱할 때 공백 문자는 인자를 구분하는 역할을 해요. 인터랙티브 모드에서는 줄바꿈(새 줄)이 명령을 파싱·실행하게 만듭니다.

공백이나 출력 불가능 문자(non-printable characters)가 포함된 문자열 값을 넣으려면 따옴표와 이스케이프된 문자열을 사용할 수 있어요. 작은따옴표(')는 문자열이 리터럴이라고 간주하며, 다음의 이스케이프 시퀀스만 허용합니다:

  • \' - 작은따옴표
  • \\ - 백슬래시

예를 들어 Hello World를 두 줄로 돌려받으려면:

127.0.0.1:6379> SET mykey "Hello\nWorld"
OK
127.0.0.1:6379> GET mykey
Hello
World

호스트, 포트, 비밀번호, 데이터베이스 (Host, port, password, and database)

$ redis-cli -h redis15.localnet.org -p 6390 PING
PONG

인스턴스에 비밀번호가 설정되어 있다면, -a <password> 옵션으로 인증을 수행해 AUTH 명령을 직접 쓰지 않아도 됩니다:

$ redis-cli -a myUnguessablePazzzzzword123 PING
PONG

NOTE: 보안을 위해 REDISCLI_AUTH 환경 변수를 통해 redis-cli에 비밀번호를 자동으로 제공하세요.

기본 번호인 0이 아닌 다른 데이터베이스 번호에서 동작하는 명령을 보내려면 -n <dbnum> 옵션을 쓰면 돼요:

$ redis-cli FLUSHALL
OK
$ redis-cli -n 1 INCR a
(integer) 1
$ redis-cli -n 1 INCR a
(integer) 2
$ redis-cli -n 2 INCR a
(integer) 1

이 정보의 일부 또는 전체는 -u <uri> 옵션과 redis://user:password@host:port/dbnum URI 패턴으로도 제공할 수 있어요:

$ redis-cli -u redis://LJenkins:p%[email protected]:16379/0 PING
PONG

NOTE: 사용자(user), 비밀번호, dbnum은 선택 사항이에요. 사용자명 없이 인증하려면 사용자명 default를 쓰세요. TLS를 쓰려면 스킴 rediss를 사용합니다. DNS 조회에서 IPv4 또는 IPv6를 선호하도록 -4나 -6 인자를 쓸 수도 있어요.

SSL/TLS

기본적으로 redis-cli는 평문 TCP 연결로 Redis에 접속해요. --tls 옵션과 함께 --cacert 또는 --cacertdir을 사용해 신뢰할 루트 인증서 번들(bundle)이나 디렉터리를 구성하면 SSL/TLS를 활성화할 수 있습니다.

다른 프로그램에서 입력 받기 (Get input from other programs)

표준 입력(stdin)으로 다른 명령의 입력을 받는 방법은 두 가지예요. 그중 하나는 대상 페이로드를 stdin 의 마지막 인자로 쓰는 겁니다. 예를 들어 로컬 파일 시스템의 /etc/services 파일 내용으로 Redis 키 net_services를 설정하려면 -x 옵션을 씁니다:

$ redis-cli -x SET net_services < /etc/services
OK
$ redis-cli GETRANGE net_services 0 50
"#\n# Network services, Internet style\n#\n# Note that "

위 세션의 첫 줄에서 redis-cli는 -x 옵션으로 실행됐고, 파일이 표준 입력으로 리다이렉트되어 SET net_services 명령의 값이 됐어요. 스크립트 작업에 유용한 방식이죠.

commands.txt 안의 모든 명령은 사용자가 인터랙티브 모드에서 입력한 것처럼 redis-cli가 차례로 실행해요. 파일 안에서 필요한 경우 문자열을 따옴표로 감쌀 수 있고, 그렇게 하면 공백·줄바꿈·기타 특수 문자가 들어간 단일 인자도 만들 수 있습니다.

CSV 출력 (CSV output)

redis-cli에는 Redis 데이터를 외부 프로그램으로 내보내기 위한 CSV(Comma Separated Values) 출력 기능이 있어요.

$ redis-cli LPUSH mylist a b c d
(integer) 4
$ redis-cli --csv LRANGE mylist 0 -1
"d","c","b","a"

--csv 플래그는 단일 명령에만 동작하며 DB 전체를 내보내는 용도는 아니라는 점 기억해 두세요.

Lua 스크립트 실행 (Run Lua scripts)

redis-cli는 Redis 3.2부터 제공되는 Lua 스크립팅 디버깅 기능을 폭넓게 지원해요. 이 기능은 Redis Lua 디버거 문서를 참고하세요. 디버거를 쓰지 않더라도 redis-cli로 파일에 있는 스크립트를 인자로 실행할 수 있습니다.

인터랙티브 모드 (Interactive mode)

지금까지 redis-cli를 명령줄 프로그램으로 쓰는 법을 봤어요. 이 방식은 스크립트나 특정 테스트에 유용하지만, 대부분의 사람들은 redis-cli의 인터랙티브 모드에서 대부분의 시간을 보냅니다.

인터랙티브 모드에서는 프롬프트에 Redis 명령을 입력해요. 명령이 서버로 보내지고, 처리된 뒤 응답이 파싱되어 읽기 쉬운 형태로 렌더링됩니다. 인터랙티브 모드를 실행하는 데 필요한 특별한 설정은 없어요. 그냥 인자 없이 실행하면 됩니다:

$ redis-cli
127.0.0.1:6379> PING
PONG

127.0.0.1:6379> 문자열이 프롬프트예요. 연결된 Redis 서버 인스턴스의 호스트명과 포트를 보여줍니다. 연결된 서버가 바뀌거나, 데이터베이스 번호 0이 아닌 다른 DB에서 동작할 때 프롬프트는 갱신돼요:

127.0.0.1:6379> SELECT 2
OK
127.0.0.1:6379[2]> DBSIZE
(integer) 1
127.0.0.1:6379[2]> SELECT 0
OK
127.0.0.1:6379> DBSIZE
(integer) 503

연결과 재연결 처리 (Handle connections and reconnections)

인터랙티브 모드에서 CONNECT 명령을 쓰면, 연결하고 싶은 호스트명 과 포트 를 지정해 다른 인스턴스로 접속할 수 있어요:

127.0.0.1:6379> CONNECT metal 6379
metal:6379> PING
PONG

다른 서버 인스턴스로 연결하면 그에 맞게 프롬프트가 바뀌는 걸 볼 수 있어요. 도달할 수 없는 인스턴스에 연결을 시도하면 redis-cli는 연결 끊김(disconnected) 모드로 들어가고, 새 명령을 받을 때마다 재연결을 시도합니다:

127.0.0.1:6379> CONNECT 127.0.0.1 9999
Could not connect to Redis at 127.0.0.1:9999: Connection refused
not connected> PING
Could not connect to Redis at 127.0.0.1:9999: Connection refused
not connected> PING
Could not connect to Redis at 127.0.0.1:9999: Connection refused

일반적으로 연결 끊김이 감지되면 redis-cli는 항상 투명하게 재연결을 시도해요. 시도가 실패하면 에러를 보여주고 연결 끊김 상태로 들어갑니다. 다음은 연결 끊김과 재연결의 예시예요:

127.0.0.1:6379> INFO SERVER
Could not connect to Redis at 127.0.0.1:6379: Connection refused
not connected> PING
PONG
127.0.0.1:6379> 
(now we are connected again)

재연결이 이뤄지면 redis-cli는 자동으로 마지막으로 선택했던 데이터베이스 번호를 다시 선택해요. 다만 MULTI/EXEC 트랜잭션 내부 상태 같은 다른 연결 상태는 모두 사라집니다:

$ redis-cli
127.0.0.1:6379> MULTI
OK
127.0.0.1:6379> PING
QUEUED

( here the server is manually restarted )

127.0.0.1:6379> EXEC
(error) ERR EXEC without MULTI

인터랙티브 모드를 테스트 용도로 쓸 때는 대개 문제가 되지 않지만, 이 제약은 알아 두는 게 좋아요. 서버 타임아웃을 초 단위로 지정하려면 -t <timeout> 옵션을 쓰세요.

편집, 히스토리, 자동완성, 힌트 (Editing, history, completion and hints)

redis-cli는 linenoise 라인 편집 라이브러리를 사용하기 때문에, libreadline이나 다른 선택적 라이브러리 없이도 항상 라인 편집 기능을 갖고 있어요.

redis-cli 클라이언트는 TAB 키를 눌러 명령어 이름 자동완성도 지원해요. 다음 예시처럼요:

127.0.0.1:6379> Z<TAB>
127.0.0.1:6379> ZADD<TAB>
127.0.0.1:6379> ZCARD<TAB>

프롬프트에 Redis 명령 이름을 입력하면 redis-cli는 문법 힌트(syntax hints)를 보여줘요. 명령 히스토리처럼 이 동작도 redis-cli 환경설정으로 켜고 끌 수 있습니다. 터미널의 CTRL-R 같은 역방향 히스토리 검색도 지원해요. Redis 8.8부터 redis-cli는 단어 단위 이동(워드 점프) 탐색(Alt/Option + ←/→, Ctrl + ←/→)을 지원해 긴 명령을 훨씬 효율적으로 편집할 수 있게 됐습니다.

환경설정 (Preferences)

redis-cli 동작을 커스터마이즈하는 방법은 두 가지예요. 홈 디렉터리의 .redisclirc 파일은 CLI가 시작할 때 읽습니다. REDISCLI_RCFILE 환경 변수를 다른 경로로 설정하면 기본 위치를 재정의할 수 있어요. 환경설정은 CLI 세션 중에도 설정할 수 있습니다.

환경설정을 하려면 특수 :set 명령을 쓰세요. 다음 환경설정은 CLI에 타이핑하거나 .redisclirc 파일에 추가해 설정할 수 있어요:

  • :set hints - 문법 힌트 활성화
  • :set nohints - 문법 힌트 비활성화

같은 명령을 N번 실행하기 (Run the same command N times)

인터랙티브 모드에서 명령 이름 앞에 숫자를 붙이면 같은 명령을 여러 번 실행할 수 있어요:

127.0.0.1:6379> 5 INCR mycounter
(integer) 1
(integer) 2
(integer) 3
(integer) 4
(integer) 5

Redis 명령 온라인 도움말 보기 (Show online help for Redis commands)

redis-cli는 HELP 명령으로 대부분의 Redis 명령에 대한 온라인 도움말을 제공해요. 이 명령은 두 가지 형태로 쓸 수 있습니다:

  • HELP @<category>는 주어진 카테고리에 관한 모든 명령을 보여줘요. 카테고리는 다음과 같습니다:
    • @generic
    • @string
    • @list
    • @set
    • @sorted_set
    • @hash
    • @pubsub
    • @transactions
    • @connection
    • @server
    • @scripting
    • @hyperloglog
    • @cluster
    • @geo
    • @stream
  • HELP <commandname>은 인자로 준 명령에 대한 구체적인 도움말을 보여줘요.

예를 들어 PFADD 명령의 도움말을 보려면:

127.0.0.1:6379> HELP PFADD

PFADD key element [element ...]
summary: Adds the specified elements to the specified HyperLogLog.
since: 2.8.9

HELP도 TAB 자동완성을 지원한다는 점 참고하세요.

특수 동작 모드 (Special modes of operation)

지금까지 redis-cli의 두 가지 주요 모드를 봤어요:

  • Redis 명령의 명령줄 실행.
  • 인터랙티브 "REPL" 사용.

CLI는 Redis와 관련된 다른 보조 작업도 수행하는데, 다음 절에서 다룰게요.

연속 통계 모드 (Continuous stats mode)

연속 통계 모드는 redis-cli의 잘 알려지지 않았지만 매우 유용한 기능 중 하나로, Redis 인스턴스를 실시간으로 모니터링해요. 이 모드를 활성화하려면 --stat 옵션을 씁니다.

$ redis-cli --stat
------- data ------ --------------------- load -------------------- - child -
keys       mem      clients blocked requests            connections
506        1015.00K 1       0       24 (+0)             7
506        1015.00K 1       0       25 (+1)             7

빅 키와 메모리 사용량 스캔 (Scan for big keys and memory usage)

$ redis-cli --keystats

# Scanning the entire keyspace to find the biggest keys and distribution information.
# Use -i 0.1 to sleep 0.1 sec per 100 SCAN commands (not usually needed).
# Use --cursor <n> to start the scan at the cursor <n> (usually after a Ctrl-C).

키 목록 가져오기 (Get a list of keys)

KEYS * 같은 명령을 쓸 때처럼 Redis 서버를 블로킹하지 않고 키 스페이스를 스캔해, 모든 키 이름을 출력하거나 특정 패턴으로 걸러낼 수도 있어요. --bigkeys 옵션처럼 이 모드도 SCAN 명령을 사용합니다.

Pub/sub 모드 (Pub/sub mode)

CLI는 PUBLISH 명령으로 Redis Pub/Sub 채널에 메시지를 발행할 수 있어요. 메시지를 받으려고 채널을 구독하는 것은 달라요. 터미널이 블로킹되어 메시지를 기다리기 때문에, 이는 redis-cli의 특수 모드로 구현되어 있습니다. 다른 특수 모드와 달리 특수 옵션으로 활성화되지 않고, 인터랙티브 또는 명령 모드에서 사용 가능한 SUBSCRIBE나 PSUBSCRIBE 명령을 쓰기만 하면 됩니다:

$ redis-cli PSUBSCRIBE '*'
Reading messages... (press Ctrl-C to quit)
1) "PSUBSCRIBE"
2) "*"
3) (integer) 1

Redis에서 실행되는 명령 모니터링 (Monitor commands executed in Redis)

Pub/Sub 모드와 비슷하게, 모니터링 모드는 MONITOR 명령을 쓰면 자동으로 진입합니다. 활성 Redis 인스턴스가 받은 모든 명령이 표준 출력으로 출력됩니다:

$ redis-cli MONITOR
OK
1460100081.165665 [0 127.0.0.1:51706] "set" "shipment:8000736522714:status" "sorting"
1460100083.053365 [0 127.0.0.1:51707] "get" "shipment:8000736522714:status"

Redis 인스턴스의 지연 시간 모니터링 (Monitor the latency of Redis instances)

--latency 옵션은 연속적으로 지연 시간을 샘플링하는 특수 모드로 들어가요. 통계(min/max/avg)는 서브 밀리초 정밀도로 밀리초 단위로 보고됩니다. 인터랙티브 세션에서 이 모드를 쓰면 실시간 통계를 표시하며 계속 실행됩니다.

RDB 파일의 원격 백업 (Remote backups of RDB files)

$ redis-cli --rdb /tmp/dump.rdb
SYNC with master failed: -ERR Can't SYNC while not connected with my master
$ echo $?
1

레플리카 모드 (Replica mode)

$ redis-cli --replica
SYNC with master, discarding 13256 bytes of bulk transfer...
SYNC done. Logging commands from master.
"PING"
"SELECT","0"
"SET","last_name","Enigk"
"PING"
"INCR","mycounter"

LRU 시뮬레이션 수행 (Perform an LRU simulation)

redis-cli에는 요청 패턴에서 80-20% 파워 법칙 분포를 사용해 GET과 SET 연산을 시뮬레이션하는 특수 모드가 있어요. 이는 키의 20%가 80%의 요청을 받는다는 뜻이고, 캐싱 시나리오에서 흔한 분포입니다.

사용법 (Usage)

Usage: redis-cli [OPTIONS] [cmd [arg [arg ...]]]

옵션 중 일부:

  • -2 : RESP2 프로토콜 모드로 세션 시작.
  • -3 : RESP3 프로토콜 모드로 세션 시작.
  • -x : 마지막 인자를 STDIN에서 읽음 (아래 예시 참고).
  • -X : <tag> 인자를 STDIN에서 읽음 (아래 예시 참고).
  • -d <delimiter> : 원시 포맷팅에서 응답 블록 사이의 구분자 (기본값: \n).
  • --stat : 서버에 대한 롤링 통계 출력: mem, clients, ...
  • --latency : 연속적으로 지연 시간을 샘플링하는 특수 모드 진입.
  • --functions-rdb <filename> : --rdb와 같지만 RDB 덤프 파일을 얻을 때 키가 아닌 함수(functions)만 가져옴.
  • --pipe : 표준 입력에서 서버로 원시 Redis 프로토콜 전송.
  • --pipe-timeout <n> : --pipe 모드에서 모든 데이터를 보낸 후 <n>초 안에 응답이 없으면 에러와 함께 중단. 기본 타임아웃: 30.
  • --cursor <n> : 커서 <n>에서 스캔 시작 (보통 Ctrl-C 이후). --keystats와 --keystats-samples와 함께 선택적으로 사용.
  • --top <n> : 상위 <n>개의 키 크기를 표시 (기본값: 10). --keystats와 --keystats-samples와 함께 선택적으로 사용.
  • --hotkeys : 핫 키를 찾기 위해 Redis 키를 샘플링.

Cluster Manager 명령 (Cluster Manager Commands)

예시:

  • redis-cli -u redis://default:PASSWORD@localhost:6379/0
  • cat /etc/passwd | redis-cli -x set mypasswd
  • redis-cli -D &;&; --raw dump key > key.dump &amp;&amp; redis-cli -X dump_tag restore key2 0 dump_tag replace < key.dump
  • redis-cli -r 100 lpush mylist x
  • redis-cli -r 100 -i 1 info | grep used_memory_human:
  • redis-cli --quoted-input set &;&;null-\x00-separated&;&; value
  • redis-cli --eval myscript.lua key1 key2 , arg1 arg2 arg3
  • redis-cli --scan --pattern &;*:12345*&;
  • redis-cli --scan --pattern &;*:12345*&; --count 100

(--eval을 쓸 때 쉼표가 KEYS[] 항목과 ARGV[] 항목을 구분한다는 점에 유의하세요)

명령 없이 실행하면 redis-cli는 인터랙티브 모드로 시작합니다. 인터랙티브 모드에서 "help"를 입력하면 사용 가능한 명령과 설정에 대한 정보를 볼 수 있어요.

더 알아보기 (Learn more)