DB & AWS Knowledge

고가용성 (HA) 수준에 따른 장애 허용시간

`O` — Thu, 10 Jul 2025 02:52:07 +0900

이 페이지에서는 고가용성 (HA) 수준에 따른 장애 허용시간에 대하여 다룬다.

또한 이 페이지는 이전 게시글과 연관된 내용이다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

또한, 출처 또한 동시에 표기한다.

[HA 가용성에 따른 가용허용시간에 대해서 알려줘]

HA(High Availability) 가용성에 따른 가용허용시간

1. HA(고가용성)의 의미

**고가용성(HA, High Availability)**는 시스템, 네트워크, 서비스가 장시간 동안 장애 없이 정상적으로 운영될 수 있는 능력을 의미합니다.
가용성은 **정상 운영 시간(Uptime) / 전체 시간(Uptime + Downtime)**으로 계산하며, 퍼센트(%)로 표현합니다.
산업 현장에서는 99%, 99.9%, 99.99%, 99.999% 등으로 SLA(서비스 수준 협약)를 명시합니다1 23.

2. 가용성 등급별 허용 장애(다운타임) 시간

아래 표는 가용성 퍼센트별 1년, 1개월, 1주, 1일 기준 허용 장애 시간을 정리한 것입니다.

가용성(%)	1년 허용 다운타임	1개월	1주	1일(24시간)
90.0	36.53일	73.05시간	16.80시간	2.40시간
95.0	18.26일	36.53시간	8.40시간	1.20시간
99.0	3.65일	7.31시간	1.68시간	14.4분
99.5	1.83일	3.65시간	50.4분	7.2분
99.9	8.77시간	43.8분	10.1분	1.44분
99.99	52.6분	4.38분	1.01분	8.64초
99.999	5.26분	26.3초	6.05초	0.864초

예시
- 99.9%: 1년에 약 8.77시간, 1개월에 43.8분, 1일에 1.44분까지 장애 허용
- 99.99%: 1년에 52.6분, 1개월에 4.38분, 1일에 8.64초 허용
- 99.999%(파이브 나인스): 1년에 5분 15초, 1개월에 26.3초, 1일에 0.864초 허용2 3 4 5

3. 실무 적용 및 참고사항

SLA 설계: 서비스 중요도에 따라 목표 가용성(예: 99.9% 이상)을 설정하고, 이에 맞는 장애 허용시간을 SLA에 명시합니다.
HA 시스템 설계: 허용 장애시간이 짧을수록(가용성 수치가 높을수록) 더 많은 이중화, 클러스터, 자동 복구 설계가 필요합니다.
비용과 트레이드오프: 99.999% 이상을 달성하려면 비용과 기술적 복잡성이 크게 증가하므로, 비즈니스 중요도에 따라 적정 수준을 선택합니다6 78.

4. 요약

HA 가용성 수치가 높을수록 허용 장애시간은 극단적으로 짧아집니다.
99.9%: 1년에 약 9시간, 99.99%: 1년에 약 1시간, 99.999%: 1년에 5분 이내만 장애 허용.
SLA, HA 설계 시 반드시 목표 가용성에 따른 허용 장애시간을 명확히 산정해야 합니다.

참고:

실제 허용시간 산정은 시스템 전체 운영시간(365일 24시간) 기준입니다.
계획된 점검(정기 점검 등)은 별도 산정할 수 있으니 SLA 세부 기준을 확인하세요2 35.

※ 업계마다 목표로 삼는 가용성은 각기 다르지만, 일반적으로 99.99% (Four Nine) 이상의 가용성을 갖는것을 목표로 삼는다.

Kafka server.property (config 설정) 관련 옵션들 - 2

`O` — Wed, 9 Jul 2025 23:30:36 +0900

이 페이지에서는 Kafka broker 들을 구성할 때, 튜닝을 고려 할 수 있는 server.property 옵션들에 대하여 다룬다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

또한, 출처 또한 동시에 표기한다.

[Kafka 에서 auto.leader.rebalance.enable 에 대해서 알려줘]

Kafka의 auto.leader.rebalance.enable 옵션은 카프카 클러스터 내에서 파티션 리더(Leader)의 분포가 특정 브로커에 치우치는 불균형(leader skew)을 자동으로 해소하는 기능입니다. 이 옵션의 주요 목적과 동작 방식은 다음과 같습니다.

주요 역할 및 필요성

리더 분포 불균형(Leader Skew) 해소
카프카의 각 파티션은 여러 브로커에 복제(replica)되지만, 실제로 데이터를 읽고 쓰는 역할(리더)은 한 브로커에만 집중됩니다.
클러스터 운영 중 브로커 추가/삭제, 장애 복구 등으로 인해 특정 브로커에 리더가 몰리면, 해당 브로커에 과부하가 발생할 수 있습니다1 25.
자동 리더 재분배
auto.leader.rebalance.enable=true로 설정하면, 백그라운드 스레드가 주기적으로 리더 분포 상태를 체크하고, 불균형이 감지되면 파티션 리더를 선호 리더(preferred leader)로 자동 재조정합니다1 2 5 6 8 910.

동작 방식

주기적 체크
리더 분포 상태는 leader.imbalance.check.interval.seconds 설정(기본 300초, 환경에 따라 다름)마다 확인됩니다2 5 68.
불균형 기준
특정 브로커에 리더가 전체 파티션의 leader.imbalance.per.broker.percentage(기본 10%) 이상 몰리면 리밸런싱이 트리거됩니다2 58.
선호 리더(Preferred Leader) 복귀
파티션의 첫 번째 replica가 "선호 리더"이며, 리밸런싱 시 이 preferred leader로 리더를 재선출합니다1 36.

설정 예시

auto.leader.rebalance.enable=true 
leader.imbalance.check.interval.seconds=300
leader.imbalance.per.broker.percentage=10

기타 참고사항

운영 편의성
자동 리밸런싱을 통해 관리자의 수고를 줄일 수 있지만, 대규모 브로커 추가 등 특정 상황에서는 수동 리밸런싱(kafka-leader-election.sh 등)도 고려해야 합니다12.
비활성화 가능
필요 시 이 옵션을 false로 두고, 리더 재분배를 수동으로 관리할 수도 있습니다4.

요약:
auto.leader.rebalance.enable은 카프카 클러스터의 리더 역할이 특정 브로커에 몰리는 현상을 자동으로 감지·해결하여, 클러스터의 부하를 균등하게 분산하고 성능 저하 및 장애 위험을 줄이는 중요한 설정입니다1 2 5 6 8 910.

[delete.topic.enable 에 대해서 알려줘]

delete.topic.enable은 Kafka에서 토픽(topic) 삭제 기능의 활성화 여부를 제어하는 브로커 설정 옵션입니다.

주요 내용

기능
이 옵션이 true로 설정되어 있어야만, kafka-topics.sh --delete 명령을 통해 토픽을 실제로 삭제할 수 있습니다2 5 6 810.
기본값
최신 Kafka 버전에서는 기본값이 true이지만, 일부 환경이나 과거 버전에서는 기본값이 false일 수 있습니다5.
설정 위치
브로커 설정 파일(server.properties)에 아래와 같이 추가합니다

delete.topic.enable=true

동작 방식
- true : 토픽 삭제 명령 실행 시, 해당 토픽의 데이터와 메타데이터가 실제로 삭제됩니다.
- false : 삭제 명령을 내려도 토픽은 "marked for deletion(삭제 예약)" 상태로만 남고 실제로 삭제되지 않습니다. 이 상태에서는 토픽에 접근할 수 없지만, 디스크 공간은 회수되지 않고, 동일 이름의 토픽 재생성 등에도 문제가 발생할 수 있습니다2 4 6 78.
주의 사항
- 설정 변경 후에는 Kafka 브로커를 재시작해야 적용됩니다7 89.
- 토픽을 바라보는 커넥터나 컨슈머가 있을 경우, 삭제가 지연되거나 제대로 삭제되지 않을 수 있습니다1.
- 완전히 삭제되지 않은 경우, Zookeeper 쉘을 이용해 /brokers/topics/토픽이름 경로를 직접 삭제해야 할 수도 있습니다2 4 89.

요약

delete.topic.enable=true여야 토픽 삭제가 정상적으로 동작합니다.
이 옵션이 false면 삭제 명령은 "예약"만 하고 실제 삭제는 이루어지지 않습니다.
설정 변경 후 브로커 재시작이 필요하며, 토픽 삭제가 안 될 때는 Zookeeper에서 직접 정리해야 할 수도 있습니다.

Kafka에서 토픽 삭제를 원한다면, 반드시 delete.topic.enable=true를 확인하고 사용하세요.

[num.partitions 에 대해서 알려주고 이에 따른 주의점과 파티션 개수 결정 기준에 도움이 되는 사항들을 알려줘]

Kafka의 num.partitions란?

**num.partitions**는 Kafka에서 토픽을 생성할 때 기본적으로 생성되는 파티션의 개수를 의미합니다.
파티션은 Kafka의 토픽 데이터를 물리적으로 분산 저장하는 단위로, 병렬 처리, 확장성, 메시지 순서 보장 등에 중요한 역할을 합니다.

토픽 생성 시 별도 지정이 없으면 브로커 설정의 num.partitions 값이 적용됩니다12.
각 파티션은 클러스터 내 여러 브로커에 분산되어 저장·관리됩니다.

주의점 및 파티션 개수 결정 시 고려사항

1. 파티션 개수와 병렬성

병렬 소비의 한계: 한 컨슈머 그룹 내에서 동시에 병렬로 메시지를 처리할 수 있는 컨슈머 수는 파티션 개수와 동일합니다. 예를 들어, 10개의 파티션이 있으면 최대 10개의 컨슈머가 병렬로 처리할 수 있습니다34.
프로듀서·컨슈머 처리량: 파티션이 많을수록 프로듀서와 컨슈머가 더 높은 처리량을 달성할 수 있습니다.

2. 파티션 개수 결정 공식

기본 공식
- 필요한 파티션 수 = max(총 목표 처리량 ÷ 단일 파티션 처리량(프로듀서), 총 목표 처리량 ÷ 단일 파티션 처리량(컨슈머))
- 예시: 컨슈머 1개가 초당 50MB를 처리할 수 있고, 전체 처리량이 1000MB/sec라면 최소 20개 파티션 필요5 67.

3. 적절한 파티션 개수 산정 가이드

병렬성: 컨슈머 그룹 내 동시 처리 수요에 맞게 파티션 수를 산정.
브로커 수와 배수: 파티션 개수를 브로커 수의 배수로 설정하면 리더 분산이 고르게 이루어져 부하가 균등해집니다8.
향후 확장성: 미래 데이터 증가와 컨슈머 확장 가능성을 고려해 다소 넉넉하게 설정하는 것이 좋습니다.
메시지 순서 보장: 파티션 내에서는 메시지 순서가 보장되지만, 파티션을 늘리면 키 기반 메시지의 순서가 깨질 수 있으므로 주의해야 합니다64.

4. 주의해야 할 점

과도한 파티션 수의 부작용
- 각 파티션은 별도의 파일 핸들, 메모리, 네트워크 리소스를 사용하므로, 너무 많은 파티션은 클러스터의 성능 저하, 메타데이터 관리 부담, 장애 발생 시 복구 시간 증가 등의 문제를 유발할 수 있습니다9 410.
- 일반적으로 브로커당 100개 내외, 클러스터 전체 10,000~200,000개 이내로 관리하는 것이 권장됩니다9 6 410.
파티션 수 변경의 제약
- 파티션 수는 늘릴 수 있지만, 줄일 수는 없습니다.
- 파티션을 늘리면 키 기반 메시지의 분산 방식이 바뀌어 기존 순서 보장이 깨질 수 있습니다64.

5. 실무적 권장사항

작게 시작해서 점진적 확장: 처음에는 3~12개 정도로 시작하고, 필요에 따라 늘리는 것이 일반적입니다119.
파티션 키 설계: 데이터가 특정 파티션에 몰리지 않도록 키 설계를 신중하게 해야 합니다.
모니터링 필수: 파티션별 크기, 소비 지연, 처리량 등을 지속적으로 모니터링하고 조정합니다.

파티션 개수 결정 체크리스트

고려 항목설명 및 권장사항

컨슈머 병렬성	필요한 동시 컨슈머 수 이상으로 설정
브로커 수	브로커 수의 배수로 맞추면 리더 분산에 유리
처리량/성능	단일 파티션 처리량을 측정해 공식 적용
순서 보장	키 기반 메시지라면 파티션 수 변경에 신중
리소스 한계	브로커당 100~200개, 클러스터 10,000~200,000개 권장
미래 확장성	데이터 증가, 컨슈머 확장 고려해 여유 있게 설정

요약
Kafka의 num.partitions는 토픽의 병렬성, 처리량, 확장성에 직접적인 영향을 미치는 핵심 설정입니다.
너무 적으면 성능이 제한되고, 너무 많으면 클러스터 리소스와 관리에 부담이 커지니
처리량, 컨슈머 수, 브로커 수, 메시지 순서 보장, 향후 확장성 등을 종합적으로 고려해 신중히 결정해야 합니다9 12 5 6 4 8 10 713.

※ 위에 게시된 데로 한번 늘린 토픽수는 줄일 수 없으니 신중하게 결정해야 한다.

[default.replication.factor 에 대해서 알려줘]

**default.replication.factor**는 Kafka 브로커의 설정 옵션 중 하나로, 자동 생성되는 토픽의 파티션 복제본(Replication) 개수의 기본값을 지정합니다.
즉, 토픽을 명시적으로 만들 때 replication-factor를 지정하지 않거나, auto.create.topics.enable=true 상태에서 토픽이 자동 생성될 때 적용되는 복제본 개수입니다6 7 910.

주요 설명

Replication Factor란?
각 파티션 데이터를 여러 브로커에 복제해 저장하는 개수입니다.
예를 들어 replication factor가 3이라면, 각 파티션 데이터가 3개의 브로커에 저장됩니다1 45.
default.replication.factor의 기본값
보통 1(복제 없음)이나 2~3(복제본 2~3개)로 설정됩니다.
운영 환경에서는 장애 대비와 데이터 내구성을 위해 2 이상, 일반적으로 3을 권장합니다4 57.
설정 위치
server.properties 파일에 아래와 같이 설정합니다.

default.replication.factor=3

동작 예시
- 명령어로 토픽 생성 시 replication-factor를 지정하지 않으면 이 값이 적용됩니다.
- auto.create.topics.enable=true 상태에서 존재하지 않는 토픽에 메시지를 보내면, 이 값이 자동 적용되어 토픽이 생성됩니다610.

주의점

브로커 수 제한
replication factor는 반드시 클러스터 내 브로커 수 이하로만 설정해야 합니다.
예: 브로커가 2대뿐인데 replication factor를 3으로 하면 토픽 생성이 실패합니다46.
디스크 사용량 증가
복제본 수가 늘어나면 데이터가 여러 번 저장되므로 디스크 사용량이 배로 증가합니다.
또한, 브로커 간 복제 트래픽과 리소스 사용도 늘어납니다1 45.
복제본 관리
복제본이 많을수록 장애 시 데이터 손실 위험이 줄어들지만, 리소스 부담도 커집니다.
데이터 중요도에 따라 적절한 값을 선택하는 것이 중요합니다1 45.

복제본 개수 결정 기준 및 팁

데이터 중요도
- 중요 데이터: 3 이상 권장(장애 시 데이터 손실 최소화)
- 비중요 데이터: 1~2도 가능
클러스터 브로커 수
- replication factor는 브로커 수 이하로만 설정 가능
운영 환경 표준
- 일반적으로 3을 가장 많이 사용(1개는 leader, 2개는 follower)
내부 토픽 별도 설정
- offsets.topic.replication.factor 등 내부 토픽 복제본도 별도 설정 필요
리소스 고려
- 복제본이 많을수록 디스크/네트워크/CPU 사용량이 증가함에 유의

요약 표

설정 값설명권장값/주의점

default.replication.factor	자동 생성 토픽의 기본 복제본 개수	3(운영), 1(테스트)
브로커 수	replication factor ≤ 브로커 수	브로커 수 미만 불가
디스크/리소스 사용량	복제본 수만큼 배로 증가	리소스 한계 고려
데이터 중요도	중요할수록 높은 replication factor 권장	3 이상 권장

정리:
default.replication.factor는 Kafka에서 토픽 복제본의 기본값을 정하는 옵션으로,
**데이터 내구성과 장애 대비를 위해 2~3 이상을 권장**하지만,
**브로커 수와 리소스 한계를 반드시 고려**해 설정해야 합니다1 4 5 67.

[log.retension.ms, log.retension.bytes, log.segment.bytes, log.roll.ms 에 대해서 알려줘]

Kafka 로그 및 세그먼트 관련 주요 설정 설명

1. log.retention.ms

의미: 메시지(로그)를 최소한으로 보관할 시간을 밀리초(ms) 단위로 지정합니다.
기본값: 7일(604800000ms)
동작: 해당 시간이 지나면 로그 세그먼트가 삭제 대상이 됩니다.
활용 예시:
text

log.retention.ms=86400000 # 1일 보관
주의: -1로 설정하면 시간 제한 없이 무한 보관합니다. 시간 단위로는 log.retention.minutes, log.retention.hours도 사용 가능1 23.

2. log.retention.bytes

의미: 파티션별로 보관할 로그의 최대 크기(바이트 단위)를 지정합니다.
기본값: -1(무제한)
동작: 파티션의 로그 크기가 이 값을 초과하면 오래된 세그먼트부터 삭제됩니다.
활용 예시:
text

log.retention.bytes=1073741824 # 1GB 보관
주의: 파티션별로 적용되므로, 전체 토픽 보관 용량은 파티션 개수 × log.retention.bytes로 계산해야 합니다45.

3. log.segment.bytes

의미: 하나의 로그 세그먼트(파일) 최대 크기를 지정합니다.
기본값: 1GB(1073741824 bytes)
동작: 세그먼트 파일이 이 크기에 도달하면 닫히고, 새로운 세그먼트가 생성됩니다.
활용 예시:
text

log.segment.bytes=536870912 # 512MB
주의: 세그먼트가 많아지면 파일 핸들, 메타데이터 관리 부담이 커질 수 있습니다. 너무 작게 설정하면 오픈 파일 수가 급증할 수 있습니다6 78.

4. log.roll.ms

의미: 활성 세그먼트가 지정된 시간(ms) 이상 유지되면, 강제로 세그먼트를 닫고 새 세그먼트를 생성합니다.
기본값: 7일(604800000ms)
동작: 메시지 유입이 적어도, 이 시간이 지나면 세그먼트가 롤링(교체)됩니다.
활용 예시:
text

log.roll.ms=3600000 # 1시간마다 세그먼트 롤링
주의: log.segment.bytes와 함께 세그먼트 롤링 조건을 결정합니다. 둘 중 하나라도 조건을 만족하면 롤링이 발생합니다6 79.

요약 표

설정명기본값의미/용도주의사항 및 팁

log.retention.ms	604800000(7일)	메시지 보관 최소 시간	-1: 무제한, 시간 단위별 옵션 존재
log.retention.bytes	-1(무제한)	파티션별 보관 최대 크기	파티션 수에 따라 전체 용량 산정
log.segment.bytes	1073741824(1GB)	세그먼트 파일 최대 크기	파일 핸들, OS 한계 고려
log.roll.ms	604800000(7일)	세그먼트 최대 유지 시간(롤링 주기)	log.segment.bytes와 병행 적용

실무 적용 팁

retention 설정: 데이터 보존 정책, 디스크 용량, 처리량에 따라 적절히 조합해 사용.
segment 설정: 파일 핸들 제한, 장애 복구 속도, 운영 환경에 맞게 조정.
모니터링 필수: 세그먼트 수, 디스크 사용량, 메시지 보관 기간 등 지속적 체크 필요.

이 네 가지 옵션을 적절히 조합하면 Kafka의 데이터 보관 정책과 성능을 효과적으로 관리할 수 있습니다.

[log segment 에 대해서 알려줘]

Kafka에서 **log segment(로그 세그먼트)**란, 파티션 데이터를 실제로 저장하는 파일 단위를 의미합니다.
Kafka의 저장 구조는 "토픽 → 파티션 → 세그먼트" 계층으로 이루어지며, 각 파티션의 데이터는 여러 개의 세그먼트 파일로 쪼개어 브로커의 로컬 디스크에 저장됩니다2 4 57.

핵심 특징 및 구조

세그먼트란?
- 각 파티션에 저장되는 메시지들은 순차적으로 세그먼트 파일에 기록됩니다.
- 세그먼트 파일에는 메시지의 키, 값, 오프셋, 메시지 크기 등 부가 정보까지 함께 저장됩니다2 5 67.
- 세그먼트 파일의 이름은 해당 세그먼트에서 시작하는 첫 번째 메시지의 오프셋으로 정해집니다7.
세그먼트 파일 종류
- .log: 실제 메시지 데이터 저장
- .index: 오프셋과 물리적 위치 매핑 정보
- .timeindex: 오프셋과 타임스탬프 매핑 정보7
- 기타: 리더 에포크 정보 등 관리 파일

세그먼트 관리 방식

롤링(Rolling)
- 세그먼트 파일은 설정된 최대 크기(log.segment.bytes, 기본 1GB) 또는 **최대 시간(log.roll.ms 등)**에 도달하면 닫히고, 새로운 세그먼트 파일이 생성됩니다1 3 57.
- 이 방식을 통해 파일 크기가 너무 커지거나, 관리가 어려워지는 것을 방지합니다.
삭제(Delete) 및 보존(Retention)
- 세그먼트는 보관 기간(log.retention.ms/hours/minutes) 또는 **최대 크기(log.retention.bytes)**를 초과하면 오래된 세그먼트부터 삭제됩니다1 35.
- 이로써 디스크 공간을 효율적으로 관리할 수 있습니다.
컴팩션(Compaction)
- 보존 정책이 compact로 설정된 토픽의 경우, 동일 키에 대해 가장 최신 메시지만 남기고 이전 메시지는 세그먼트 내에서 제거합니다1 23.
- 대표적으로 __consumer_offsets 토픽이 이 방식을 사용합니다.

세그먼트의 역할과 중요성

효율적 대용량 데이터 관리: 세그먼트 단위로 데이터가 나뉘어 저장되기 때문에, 삭제·압축·복구 등 관리 작업이 효율적으로 이루어집니다4.
순차적 읽기/쓰기 최적화: Kafka는 세그먼트에 데이터를 순차적으로 추가(append-only)하므로, 디스크 I/O 성능이 뛰어납니다46.
오프셋 기반 접근: 컨슈머는 세그먼트 파일에서 오프셋을 기반으로 원하는 메시지를 빠르게 조회할 수 있습니다78.

요약

**log segment**는 Kafka 파티션 내 데이터를 저장하는 기본 파일 단위입니다.
세그먼트는 크기 또는 시간 기준으로 분할·관리되며, 삭제/컴팩션 정책에 따라 오래된 데이터가 정리됩니다.
세그먼트 구조 덕분에 Kafka는 대용량 메시지의 저장, 읽기, 삭제, 압축 등 다양한 작업을 효율적으로 수행할 수 있습니다.

[min.insync.replicas 에 대해서 알려줘]

Kafka min.insync.replicas란?

**min.insync.replicas**는 Kafka에서 파티션의 리더와 팔로워 중 동기화(In-Sync) 상태를 유지해야 하는 최소 레플리카(replica) 개수를 지정하는 설정입니다.
이 값보다 적은 수의 레플리카만 동기화되어 있으면, 프로듀서의 쓰기 요청이 거부되고, 메시지가 저장되지 않습니다.

주요 개념 및 동작 방식

ISR(In-Sync Replicas):
리더와 팔로워 중, 최신 데이터를 모두 반영하고 있는 브로커 집합입니다.
min.insync.replicas:
ISR에 포함되어 있어야 하는 최소 레플리카 수(리더 포함)를 의미합니다.
acks=all과의 연계:
프로듀서가 acks=all로 메시지를 보낼 때, ISR의 개수가 min.insync.replicas 이상이어야만 메시지가 정상적으로 저장되고 ack가 반환됩니다1 23.

예시 시나리오

replication.factor=3, min.insync.replicas=2
- 세 개의 브로커(리더+팔로워2)가 모두 동기화 상태라면 정상 동작.
- 브로커 하나가 장애로 ISR이 2개만 남아도, 메시지 쓰기는 계속 가능.
- ISR이 1개(리더만 남음)로 줄어들면, 쓰기 요청이 거부되고 에러(NotEnoughReplicasException)가 발생1 23.

설정 목적 및 효과

데이터 내구성 보장
최소한의 레플리카가 항상 최신 데이터를 보유하도록 강제해, 브로커 장애 시에도 데이터 손실을 방지합니다.
운영 권장값
- 일반적으로 replication.factor=3, min.insync.replicas=2 조합을 많이 사용합니다.
- 이 조합은 브로커 하나가 장애 나도 서비스가 중단되지 않으면서, 데이터 무손실을 보장할 수 있습니다13.

주의사항

min.insync.replicas > ISR
- ISR이 min.insync.replicas보다 적으면 쓰기 불가, 프로듀서에 에러 반환.
replication.factor와의 관계
- min.insync.replicas는 replication.factor 이하로 설정해야 하며, 너무 높게 설정하면 브로커 장애 시 전체 쓰기가 중단될 수 있습니다.
acks=all과 함께 사용
- 데이터 무손실 보장이 필요하다면 반드시 acks=all과 함께 사용해야 효과가 있습니다.

요약 표

설정 예시동작 및 효과

replication.factor=3 min.insync.replicas=2	브로커 1대 장애 시에도 쓰기 가능, 데이터 무손실 보장
replication.factor=3 min.insync.replicas=3	브로커 1대만 장애 나도 쓰기 불가(가용성 저하)
replication.factor=2 min.insync.replicas=2	브로커 1대 장애 시 쓰기 불가, 데이터 무손실 보장

정리
min.insync.replicas는 Kafka의 데이터 내구성과 무손실 보장을 위한 핵심 옵션입니다.
적절한 값으로 설정하면 장애 상황에서도 데이터 손실 없이 안정적으로 메시지를 처리할 수 있습니다1 23.

[message.max.bytes 에 대해서 알려줘]

message.max.bytes는 **Kafka 브로커에서 허용하는 단일 메시지(혹은 레코드 배치)의 최대 크기(바이트 단위)**를 지정하는 설정입니다.
이 값보다 큰 메시지는 브로커에서 거부되어 저장되지 않습니다.

주요 특징

기본값: 약 1MB(1048588 bytes)1 7 8
설정 위치: 브로커(server.properties) 전체에 적용되며, 토픽별로 max.message.bytes로 별도 지정도 가능합니다14.
작동 방식: 프로듀서가 보낸 메시지(혹은 레코드 배치)가 이 값을 초과하면 브로커가 메시지를 거부하고 에러를 반환합니다1 25.
압축 사용 시: 압축이 적용된 경우, 압축 후 크기가 기준이 됩니다24.

연관 설정 및 주의점

컴포넌트관련 설정설명 및 주의사항

Producer	max.request.size	프로듀서가 한 번에 보낼 수 있는 최대 요청 크기(기본 1MB). 이 값도 함께 늘려야 함1 25.
Broker	message.max.bytes	브로커가 허용하는 최대 메시지 크기. 프로듀서의 max.request.size보다 크거나 같아야 함1 23.
Topic	max.message.bytes	특정 토픽에만 별도로 최대 메시지 크기를 지정할 수 있음14.
Consumer	fetch.max.bytes, max.partition.fetch.bytes	컨슈머가 한 번에 가져올 수 있는 최대 데이터 크기. 이 값도 충분히 커야 함1 69.

설정 불일치 시 문제:
- Producer의 max.request.size < Broker의 message.max.bytes < Consumer의 fetch.max.bytes
- 이 순서로 설정되어야 대용량 메시지 송수신이 원활합니다1 2 36.

실무 적용 및 주의사항

대용량 메시지 사용 시:
- 이미지, 대형 JSON 등 1MB를 초과하는 메시지를 쓸 경우, 위 모든 관련 설정을 동일하게 충분히 늘려줘야 합니다1 25.
네트워크 및 리소스 영향:
- 메시지 크기가 커질수록 네트워크 지연, 브로커 및 컨슈머의 메모리 사용량, 장애 시 복구 시간 등이 증가할 수 있으니 주의가 필요합니다17.
오류 예시:
- RecordTooLargeException 등 메시지 크기 초과 관련 에러가 발생할 수 있습니다5.

요약

**message.max.bytes**는 Kafka 브로커가 허용하는 단일 메시지(혹은 레코드 배치)의 최대 크기입니다.
기본값은 약 1MB이며, 대용량 메시지 송수신 시 프로듀서, 브로커, 컨슈머의 관련 설정을 모두 일관성 있게 조정해야 합니다.
값이 맞지 않으면 메시지 전송 실패, 에러 발생 등 문제가 생길 수 있습니다1 2 3 4 5 7 89.

※ 이 값은 압축된 메시지의 크기를 기준으로 한다. 즉, 압축전 메시지가 이 값보다 크더라도 압축된 크기가 이 설정값보다 적다면, 메시지 전송이 여전히 가능하다.

MongoDB document 관련 기본 조작 (CRUD) - 2

`O` — Fri, 4 Jul 2025 02:54:45 +0900

이 페이지에서는 이전 게시글에 이어 MongoDB 의 document 에 대한 CRUD 에 대하여 계속 다룬다.

[+] 2025.07.03 - [MongoDB, AWS DocumentDB/아키텍처 및 내부 구조] - MongoDB document 관련 기본 조작 (CRUD) - 1

또한, 이 게시글은 도서 O'REILLY 사의 저서 '몽고DB 완벽가이드' 의 내용들을 심화 이해하기 위하여 작성하는 글이다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

마지막으로 이 페이지는 EC2 Amazon Linux 2023 에 설치된 기본 MongoDB 를 사용한다.

[updateOne 와 updateMany 에 대해서 알려주고 RDBMS 의 update 와의 차이점을 알려줘]

1. updateOne과 updateMany란?

updateOne

설명:
조건에 일치하는 첫 번째 도큐먼트 하나만 수정합니다.
형식:

db.collection.updateOne(조건, {$set: {수정할필드: 값}})

특징:
- 조건에 맞는 여러 도큐먼트가 있어도 가장 먼저 찾은 한 개만 수정
- 반환값: 수정된 도큐먼트 수, 매칭된 도큐먼트 수 등

updateMany

설명:
조건에 일치하는 모든 도큐먼트를 한 번에 수정합니다.
형식:

db.collection.updateMany(조건, {$set: {수정할필드: 값}})

특징:
- 조건에 맞는 모든 도큐먼트가 동시에 수정
- 반환값: 수정된 도큐먼트 수, 매칭된 도큐먼트 수 등

예시

메서드예시 코드결과 설명

updateOne	db.users.updateOne({age: 20}, {$set: {city: "Seoul"}})	age가 20인 첫 번째 도큐먼트만 수정
updateMany	db.users.updateMany({age: 20}, {$set: {city: "Seoul"}})	age가 20인 모든 도큐먼트 수정

$set 연산자를 사용하지 않으면, 해당 도큐먼트 전체가 덮어써질 수 있으니 주의해야 합니다12.

2. RDBMS의 UPDATE와의 차이점

구분MongoDB (NoSQL)RDBMS (MySQL, Oracle 등)

데이터 구조	Document 기반 (JSON/BSON)	Table(Row/Column) 기반
updateOne	조건에 맞는 첫 도큐먼트 1개만 수정	WHERE 조건에 맞는 Row 1개만 수정
updateMany	조건에 맞는 모든 도큐먼트 수정	WHERE 조건에 맞는 모든 Row 수정
기본 동작	$set 등 연산자 필요, 아니면 전체 도큐먼트 덮어씀	SET 구문으로 컬럼 값만 수정
트랜잭션/무결성	기본적으로 약함 (ACID 보장 약함, 옵션에 따라 다름)	ACID(원자성, 일관성, 고립성, 지속성) 강함
스키마	유연(스키마 없음/동적)	엄격(스키마 고정)
대량 수정	updateMany로 한 번에 처리	UPDATE ... WHERE ...

주요 차이점 요약

연산자 사용:
MongoDB는 $set, $inc 등 연산자를 반드시 사용해야 부분 수정이 가능하며, 그렇지 않으면 전체 도큐먼트가 덮어써집니다.
RDBMS는 SET 구문으로 컬럼만 수정합니다12.
트랜잭션/무결성:
RDBMS는 트랜잭션과 데이터 무결성 보장이 강력하지만, MongoDB는 기본적으로 약하며 옵션에 따라 다릅니다3.
스키마 유연성:
MongoDB는 스키마가 유연해 필드 추가/삭제가 자유롭지만, RDBMS는 스키마가 고정되어 있습니다.
대량 처리:
MongoDB의 updateMany, RDBMS의 UPDATE ... WHERE ... 모두 대량 수정이 가능하지만, MongoDB는 JSON 기반 문서 전체를 다루는 점이 다릅니다.

3. 정리

updateOne: 조건에 맞는 첫 도큐먼트 1개만 수정
updateMany: 조건에 맞는 모든 도큐먼트 수정
RDBMS UPDATE와의 차이:
연산자 사용 방식, 트랜잭션/무결성, 스키마 유연성 등에서 차이가 있음

MongoDB의 update 계열 명령은 RDBMS와 유사하지만, 문서 지향적 구조와 연산자 사용 방식, 트랜잭션 특성 등에서 중요한 차이가 있으니 실무 적용 시 반드시 주의해야 합니다1 23.

※ MongoDB 는 RDBMS 보다 update 무결성이 약한 편이지만, 순서대로 들어오는 update 구문을 순차적으로 처리함으로써 가능한 ACID 를 보장하려고 한다.

[replaceOne 을 통해 document 에 있는 기존 필드를 서브도큐먼트로 옮기는 예시를 보여줘]

MongoDB의 replaceOne은 문서 전체를 새 문서로 완전히 대체하는 명령입니다. 기존 필드를 서브도큐먼트로 옮기려면, 원하는 구조로 새 문서를 만들어서 replaceOne의 두 번째 인자로 전달해야 합니다.

예시 상황

기존 문서

{
  "_id": ObjectId("..."),
  "name": "Alice",
  "age": 30,
  "city": "Seoul"
}

목표 구조

name, age를 profile이라는 서브도큐먼트로 이동

{
  "_id": ObjectId("..."),
  "profile": {
    "name": "Alice",
    "age": 30
  },
  "city": "Seoul"
}

replaceOne 사용 예시

db.users.replaceOne(
  { _id: ObjectId("...") }, // 대상 문서 조건
  {
    _id: ObjectId("..."),
    profile: {
      name: "Alice",
      age: 30
    },
    city: "Seoul"
  }
)

주의:
- replaceOne은 해당 문서를 완전히 새 문서로 교체하므로, _id 필드를 반드시 포함해야 합니다.
- 기존에 있던 다른 필드(예: city)도 새 문서에 명시적으로 포함해야 삭제되지 않습니다1 23.

활용 팁

여러 문서에 대해 반복적으로 구조를 바꿔야 한다면, 애플리케이션 코드(Python, Node.js 등)에서 기존 문서를 읽어 새 구조로 변환한 뒤 replaceOne을 반복 호출하는 방식이 일반적입니다.
부분 수정만 원한다면 $set을 사용하는 updateOne/updateMany가 더 적합합니다.

요약:
replaceOne은 문서 전체를 새 구조로 대체하므로, 기존 필드를 서브도큐먼트로 옮기려면 새 문서에 원하는 구조를 직접 만들어서 사용해야 합니다.
이때 _id와 유지할 모든 필드를 반드시 포함해야 데이터 손실이 없습니다1 23.

※ 위에도 기술되었지만 RDBMS update 와는 다르게 set, $set 의 차이가 있으므로 상황에 따라 맞는 명령어를 쓰는게 좋다.

[updateOne 시 _id 가 아닌 다른 필드 중복으로 에러가 발생 할 수 있는 예시를 알려줘]

MongoDB에서 updateOne을 사용할 때, _id가 아닌 다른 필드에 대해 unique 인덱스가 설정되어 있다면, 해당 필드 값이 중복될 경우 에러가 발생할 수 있습니다.

예시 상황

1. unique 인덱스가 설정된 컬렉션

예를 들어, email 필드에 unique 인덱스가 설정된 users 컬렉션이 있다고 가정합니다.

db.users.createIndex({ email: 1 }, { unique: true })

2. 기존 데이터

[
  { "_id": 1, "name": "Alice", "email": "alice@example.com" },
  { "_id": 2, "name": "Bob",   "email": "bob@example.com" }
]

3. updateOne으로 중복 시도

아래와 같이 Bob의 이메일을 Alice와 동일하게 변경하려고 하면:

E11000 duplicate key error collection: test.users index: email_1 dup key: { email: "alice@example.com" }

4. 발생하는 에러

DuplicateKeyError (E11000 duplicate key error)
에러 메시지 예시:
text

E11000 duplicate key error collection: test.users index: email_1 dup key: { email: "alice@example.com" }

요약

unique 인덱스가 걸린 필드에 대해 updateOne으로 중복 값을 넣으려 하면,
_id와 무관하게 중복 키 에러가 발생합니다.
이 에러는 데이터 무결성을 보장하기 위한 MongoDB의 동작입니다.

상황결과/에러 설명

_id 중복	항상 에러 발생 (기본키 충돌)
unique 인덱스 필드 중복	DuplicateKeyError 발생 (중복 키 인덱스 충돌)

실무에서는 unique 인덱스가 걸린 필드의 중복 여부를 사전에 체크하거나, try-catch 등 예외 처리를 반드시 구현해야 합니다.

MongoDB document 관련 기본 조작 (CRUD) - 1

`O` — Thu, 3 Jul 2025 02:38:11 +0900

이 페이지에서는 MongoDB 의 document 에 대한 CRUD 에 대하여 다룬다.

또한, 이 게시글은 도서 O'REILLY 사의 저서 '몽고DB 완벽가이드' 의 내용들을 심화 이해하기 위하여 작성하는 글이다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

마지막으로 이 페이지는 EC2 Amazon Linux 2023 에 설치된 기본 MongoDB 를 사용한다.

[MongoDB 의 InsertOne 과 InsertMany 에 대해서 알려줘]

MongoDB에서 InsertOne과 InsertMany는 컬렉션에 데이터를 삽입할 때 사용하는 대표적인 메서드입니다. 두 메서드의 차이와 특징을 아래와 같이 정리할 수 있습니다.

InsertOne

설명:
컬렉션에 단일(document 하나) 문서를 삽입할 때 사용합니다.
사용법:

db.collection.insert_one({"name": "Alice", "age": 25})

파라미터:
- 삽입할 문서(딕셔너리) 1개
- (선택) writeConcern: 데이터 쓰기 보장 수준 지정 가능
반환값:
- InsertOneResult 객체 반환
- 삽입된 문서의 _id 값은 inserted_id 속성에 저장됨
특징:
- _id 필드를 지정하지 않으면 MongoDB가 자동으로 생성
- 삽입 실패 시 예외 발생
- 트랜잭션 내에서도 사용 가능1 2 3 4 5

InsertMany

설명:
컬렉션에 여러(document 여러 개) 문서를 한 번에 삽입할 때 사용합니다.
사용법:

db.collection.insert_many([ {"name": "Bob", "age": 30}, {"name": "Charlie", "age": 22} ])

파라미터:
- 삽입할 문서(딕셔너리)들의 리스트
- (선택) writeConcern: 데이터 쓰기 보장 수준 지정 가능
- (선택) ordered: 기본값 True. True면 순서대로 삽입, False면 일부 실패해도 나머지 계속 시도
반환값:
- InsertManyResult 객체 반환
- 삽입된 각 문서의 _id 값은 inserted_ids 리스트에 저장됨
특징:
- 대량 삽입 시 성능이 뛰어남
- _id 필드를 지정하지 않으면 각 문서마다 자동 생성
- 일부 문서에서 오류 발생 시 BulkWriteError 예외 발생 가능
- 트랜잭션 내에서도 사용 가능6 7 4

비교 표

메서드명삽입 대상반환값주요 옵션특징

insert_one	1개 문서	InsertOneResult	writeConcern	단일 문서 삽입, _id 자동생성
insert_many	여러 문서	InsertManyResult	writeConcern, ordered	대량 삽입, 순서 제어 가능

요약

insert_one: 한 번에 하나의 문서만 삽입, 결과로 삽입된 문서의 _id 반환
insert_many: 여러 문서를 한 번에 삽입, 결과로 각 문서의 _id 리스트 반환
두 방법 모두 Python의 PyMongo, MongoDB Shell 등에서 동일한 원리로 사용됩니다8 2 45.

[위의 내용과 관련하여 _id 를 임의로 넣을 때, 주의 해야 할 사항]

MongoDB에서 _id 필드를 임의로 지정할 때 주의해야 할 사항은 다음과 같습니다.

_id는 컬렉션 내에서 반드시 고유해야 함
- _id는 MongoDB 컬렉션의 기본 키(primary key) 역할을 하며, 같은 값이 중복되면 삽입 시 duplicate key error가 발생합니다1 23.
- 따라서 애플리케이션에서 직접 값을 지정할 경우, 100% 고유한 값을 생성해야 합니다.
_id 타입과 값의 일관성 유지
- 기본적으로 MongoDB는 _id에 ObjectId 타입을 자동 생성하지만, 문자열(String), 숫자(Number) 등 다른 타입도 사용할 수 있습니다4.
- 다만, 타입이 혼재되면 쿼리나 인덱스 성능에 영향을 줄 수 있으니 일관성 있게 사용하는 것이 좋습니다.
중복 삽입 방지
- 동일한 _id 값으로 문서를 삽입하려 하면 오류가 발생하므로, 업데이트가 필요한 경우 insert 대신 update 또는 upsert를 사용해야 합니다5.
_id를 직접 지정하는 경우의 장단점
- 장점: 애플리케이션에서 이미 관리하는 고유 ID를 그대로 사용할 수 있어 별도의 인덱스 필드가 불필요해지고, 조회 시 효율적일 수 있음5.
- 단점: 고유성 보장 책임이 개발자에게 있으며, 잘못 지정 시 데이터 무결성 문제가 발생할 수 있음.
샤딩 환경에서 주의점
- _id가 샤딩 키인 경우, 기본 ObjectId는 생성 시점 기준으로 정렬되어 특정 샤드에 부하가 집중될 수 있으므로 해시 샤딩을 권장합니다4.
예외 처리 권장
- 삽입 시 중복 _id 오류가 발생할 수 있으므로, 예외 처리를 통해 적절한 대응(예: 재시도, 업데이트 등)을 구현하는 것이 좋습니다.

요약

주의사항설명

고유성 보장	_id 값은 컬렉션 내에서 반드시 유일해야 함
타입 일관성	_id 타입은 일관되게 사용 (ObjectId, String 등)
중복 삽입 시 오류 발생	중복 _id 삽입 시 duplicate key error 발생
직접 지정 시 책임	고유성 보장과 관리 책임은 개발자에게 있음
샤딩 환경 고려	샤딩 시 해시 샤딩 권장, 기본 ObjectId는 순차적 생성
예외 처리 구현 권장	삽입 실패 시 적절한 예외 처리 및 대응 필요

[위의 내용과 관련하여 MongoDB 의 삽입 유효성을 알려주고 이와 관련하여 Document 크기 제한 및 Insert 제한 크기를 알려줘]

MongoDB에서 데이터 삽입(insert)과 관련된 유효성(Validation), Document 크기 제한, Insert 제한에 대해 아래와 같이 정리할 수 있습니다.

1. MongoDB 삽입 유효성(Validation)

Schema Validation
MongoDB는 기본적으로 유연한 스키마 구조를 가지지만, 컬렉션 단위로 **스키마 유효성 검사(Validation Rules)**를 설정할 수 있습니다.
예를 들어, 특정 필드는 반드시 문자열이어야 하거나, 값의 범위가 정해져 있어야 하며, 필수 필드 여부도 지정할 수 있습니다.
삽입 시 유효성 검사
스키마 유효성 규칙이 설정된 경우, 문서가 해당 규칙을 위반하면 삽입(insert)이나 갱신(update)이 거부됩니다.
기본값은 위반 시 삽입/갱신이 실패하고, 로그에 기록됩니다.
(단, 옵션에 따라 경고만 남기고 허용할 수도 있음)12.
활용 예시
- password 필드는 반드시 문자열
- item 필드는 특정 목록 내 값만 허용
- gpa 필드는 양수만 허용

2. Document 크기 제한

단일 Document 최대 크기
MongoDB에서 **하나의 Document 크기는 최대 16MB(16,777,216 bytes)**입니다3 45.
제한 이유
단일 문서가 과도하게 커지는 것을 방지하여, 성능 저하 및 메모리/네트워크 과부하를 막기 위함입니다.
16MB 초과 데이터 저장
16MB를 초과하는 대용량 데이터(예: 이미지, 동영상 등)는 GridFS라는 별도 API를 사용해 저장해야 합니다.

3. Insert(삽입) 제한

insertMany의 Document 수 제한
한 번에 insertMany로 삽입할 수 있는 Document 수는 최대 1000개입니다.
1000개를 초과하면 내부적으로 1000개 단위로 나누어 처리합니다6.
각 Document의 크기 제한
insertMany로 여러 개를 넣더라도, 각 문서가 16MB를 넘을 수 없습니다.
(즉, insertMany로 1000개를 넣더라도 각 문서는 16MB 이하여야 함)74.
중첩(Depth) 제한
BSON 문서의 중첩(객체/배열)은 최대 100단계까지 허용됩니다3.

4. 삽입 유효성 및 제한 관련 정리 표

항목제한/설명

단일 Document 크기	최대 16MB
insertMany 1회 최대	1000개 Document (내부적으로 자동 분할)
Document 중첩 깊이	최대 100단계
스키마 Validation	컬렉션 단위로 JSON Schema 기반 유효성 검사 가능
유효성 위반 시	기본적으로 삽입/갱신 거부, 옵션에 따라 경고만 허용 가능
16MB 초과 데이터	GridFS 사용 필요

참고:

삽입 시 스키마 유효성 검사를 적극 활용하면 데이터 품질과 일관성을 높일 수 있습니다.
대용량 데이터는 반드시 GridFS 등 별도 저장 방식을 고려해야 하며, insertMany 등 대량 삽입 시에는 개수와 크기 제한을 항상 염두에 두어야 합니다.

[deleteOne 과 deleteMany 를 알려주고 이에 대한 예시를 보여줘]

deleteOne

설명:
지정한 조건에 일치하는 첫 번째 문서 하나만 삭제합니다.
특징:
- 조건에 맞는 문서가 여러 개여도, 오직 하나만 삭제합니다.
- 삭제된 문서가 없으면 아무 변화도 없습니다.

예시

// age가 25인 첫 번째 문서만 삭제 db.users.deleteOne({ age: 25 })

deleteMany

설명:
지정한 조건에 일치하는 모든 문서를 삭제합니다.
특징:
- 조건에 맞는 문서가 0개면 아무 변화도 없습니다.
- 조건에 맞는 문서가 여러 개면 모두 삭제됩니다.

예시

// age가 25인 모든 문서를 삭제 db.users.deleteMany({ age: 25 })

요약 비교

메서드명삭제 대상삭제 개수

deleteOne	조건에 맞는 첫 번째 문서	최대 1개
deleteMany	조건에 맞는 모든 문서	0개 이상

[deleteMany 로 모든 도큐먼트를 삭제하는 방법과 이와 연관지어 drop 을 같이 알려줘]

1. deleteMany로 모든 도큐먼트 삭제

설명:
deleteMany에 빈 조건({})을 주면 해당 컬렉션의 모든 도큐먼트가 삭제됩니다.
컬렉션 구조(인덱스 등)는 그대로 남고, 데이터만 사라집니다.

예시

// users 컬렉션의 모든 도큐먼트 삭제 db.users.deleteMany({})

2. drop으로 컬렉션 자체 삭제

설명:
drop()은 컬렉션 전체(데이터 + 인덱스 등 메타데이터 포함)를 완전히 삭제합니다.
컬렉션 자체가 사라지므로, 이후에는 해당 컬렉션이 존재하지 않게 됩니다.
복구 불가에 유의해야 합니다.

예시

// users 컬렉션 자체를 삭제 db.users.drop()

차이점 요약

방법데이터 삭제인덱스/스키마 삭제컬렉션 존재 여부

deleteMany({})	O	X	O
drop()	O	O	X

정리

deleteMany({}) : 모든 도큐먼트를 삭제하지만 컬렉션과 인덱스는 남아있음.
drop() : 컬렉션 전체(데이터, 인덱스, 메타데이터 포함)를 완전히 삭제.

Amazon Q CLI 를 자신의 Aurora Cluster 에 연결하기 (MCP)

`O` — Wed, 2 Jul 2025 02:09:13 +0900

이 페이지에서는 Amazon Q CLI 를 자신의 Aurora Cluster DB 에 MCP 개념으로 연결하는 과정을 기재한다.

이 페이지는 perplexity pro 를 통하여 확인 한 가이드 사항에 사용자가 더 이해하기 쉽게 추가 내용을 기재한다.

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

(Perplexity 가 아니더라도 자신이 사용하는 AI 솔루션을 유료 버전으로 사용한다면 설치 안내 과정은 비슷하게 안내 될 것이다.)

이 가이드는 Amazon Linux 2023 를 기준으로 설명된다.

또한 필자가 AI 를 통하여 만든 가이드 또한 아래에 첨부한다. 이 가이드에 있는 명령어를 복사하여 Amazon Q CLI 를 구성 할 수 있다.

Amazon Q CLI MCP 구성 (Amazon 2023).txt

0.01MB

Amazon Q CLI 설치 과정

- 먼저 Amazon Q Cli 를 설치하기 위해서는 확인 해야 할 사항이있다.

먼저, 아래와 같이 glibc 패키지가 설치되어 있는지 확인한다.

또한 glibc 2.34 이상인지 확인한다. 2.34 미만이면 musl 버전을 사용해야 한다.

$ ldd --version

ldd (GNU libc) 2.34
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Roland McGrath and Ulrich Drepper.
[ec2-user@ip-10-0-1-202 ~]$ sudo dnf update
Last metadata expiration check: 6:59:59 ago on Tue Jul  1 06:35:04 2025.

- 그 다음 curl 과 unzip 이 설치되어 있는지 확인 후 필요시 설치한다.

$sudo dnf update

Last metadata expiration check: 6:59:59 ago on Tue Jul  1 06:35:04 2025.
Dependencies resolved.
==================================================================================================================================
 Package                                    Architecture     Version                              Repository                 Size
==================================================================================================================================
Upgrading:
 amazon-linux-repo-s3                       noarch           2023.7.20250623-0.amzn2023           amazonlinux                16 k
 awscli-2                                   noarch           2.25.0-1.amzn2023.0.1                amazonlinux                12 M
 kernel-libbpf                              x86_64           6.12.31-35.92.amzn2023               amazonlinux               186 k
 kernel-livepatch-repo-s3                   noarch           2023.7.20250623-0.amzn2023           amazonlinux                16 k
 kernel-tools                               x86_64           6.12.31-35.92.amzn2023               amazonlinux               174 k
(...)

$ sudo dnf install curl unzip -y
Last metadata expiration check: 7:00:36 ago on Tue Jul  1 06:35:04 2025.
Package unzip-6.0-57.amzn2023.0.2.x86_64 is already installed.
Error:
Problem: problem with installed package curl-minimal-8.11.1-4.amzn2023.0.1.x86_64
(...)

# 필자의 EC2 에는 이미 amzn2023 curl 이 설치되어 있어서 curl 설치시 충돌이 일어나기에 필자의 테스트 환경에서는 이를 생략한다.

- 위와 같이 필요 패키지 및 프로그램을 설치했다면, 아래의 명령어를 그대로 사용하여 Amazon Q zip 을 다운로드 받을 디렉토리에 다운로드 한다.

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"

#위의 사항은 Amazon Linux 2023 (x86_64 아키텍처) 에서만 사용가능한 명령어다. 만일 자신의 EC2 또는 OS 환경이 ARM (aarch64) 이면 아래의 명령어를 사용한다.

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" -o "q.zip"

- 그 후, unzip 으로 압축을 푼 후, 설치를 한다.

$ unzip q.zip
Archive:  q.zip
   creating: q/
  inflating: q/install.sh
  inflating: q/README
  inflating: q/BUILD-INFO
   creating: q/bin/
  inflating: q/bin/q
  inflating: q/bin/qterm
  inflating: q/bin/qchat

# 아래의 install 을 하면 AI 가 shell config 를 변경하도록 허용 할 지, login 은 어떤 계정을 사용할지 선택한다. 이 때, Amazon Q 를 pro 로 사용하는 사용자라면 pro 를 선택한다. 

$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
❯ Use for Free with Builder ID
  Use with Pro license
(...)

- 위의 설정이 완료되면 아래와 같이 브라우저에서 사용하는 Amazon ID 를 login 하도록 요청받는다.

안내 받은 링크를 통해 Amazon.com 로그인과 같이 로그인 하면 된다.

Confirm the following code in the browser
Code: SDWN-QSTK

Open this URL: https://view.awsapps.com/start/#/device?user_code=SDWN-QSTK

- 로그인이 정상적으로 되면 아래와 같이 Amazon Q 가 자신의 데이터가 접근하도록 허용한다.

출처 : 본인 테스트

- 접속허용까지 되면 아래와 같이 설치가 완료된다.

Confirm the following code in the browser
Code: SDWN-QSTK

Open this URL: https://view.awsapps.com/start/#/device?user_code=SDWN-QSTK
Device authorized
Logged in successfully

#만일 이후에 login 을 다시 해야 하는 경우에는 아래의 명령어를 입력하면 된다.
(필자의 테스트 환경에서 이를 입력시 어떤 결과가 나오는지 미리 확인)

$q login
error: Already logged in, please logout with q logout first

- 그다음 Amazon Q 가 사용할 프로젝트 디렉토리를 만든다.

# 전역 설정 디렉토리 생성
mkdir -p ~/.aws/amazonq

# 또는 워크스페이스 설정 디렉토리 생성
mkdir -p .amazonq

- 이제 필자가 사용하는 Aurora MySQL Cluster 에 Amazon Q CLI 를 연동시키기 위해서 아래와 같이 ~/.aws/amazonq/mcp.json 파일을 만들고 아래의 내용을 기재한다. 여기서 사용자가 준비 해야 할 사항은 아래와 같다.

- 연동시킬 Aurora Cluster

- Secret Manager 정보 (현재 Amazon Q 는 Aurora Cluster 등의 DB 접근시, 보안을 위하여 Secret Manager 를 통해서만 접속이 가능하다. 만일 기존에 user, PW 의 단순 login 을 사용했다면 관리자 계정을 기준으로 하는 Secret Manager 정보를 하나 만들고, 이를 Cluster 에 반영하도록 Cluster 를 수정 (Modify) 하면 된다. ARN 또한 Secret Manager 에서 확인 가능하다.)

- AWS Profile (필자는 default 로 사용하나, 이는 사용자마다 회사 규정등으로 인하여 정해진 profile 을 쓸 수 있다. 이에 맞춰쓴다.)

$ vi ~/.aws/amazonq/mcp.json

{
  "mcpServers": {
    "awslabs.mysql-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.mysql-mcp-server@latest",
        "--resource_arn", "arn:aws:rds:ap-northeast-2:(계정):db:(CLuster 명)",
        "--secret_arn", "arn:aws:secretsmanager:ap-northeast-2:(계정):secret:rds!cluster-b67dae33-bd0c-4cf7-8751-7b0099dde66d-ClYBVr",
        "--database", "test",
        "--region", "ap-northeast-2",
        "--readonly", "False"
      ],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "ap-northeast-2",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

- 만일 PostgreSQL 에 접속시에는 아래의 포맷을 사용하면 된다.

{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.postgres-mcp-server@latest",
        "--resource_arn", "arn:aws:rds:us-east-1:123456789012:cluster:your-cluster-name",
        "--secret_arn", "arn:aws:secretsmanager:us-east-1:123456789012:secret:your-secret-name",
        "--database", "your-database-name",
        "--region", "us-east-1",
        "--readonly", "True"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

- 그 후, Amazon CLI 가 정상적으로 실행되도록 마지막으로 python 및 종속 패키지 설치 확인을 한다.

# Python 3.10 이상 설치 확인
python3 --version

# uv 설치 (Python 패키지 관리자)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

- 그 후, Amazon Q CLI 의 설치확인을 한다. Amazon Q 가 정상적으로 설치되었다면 CLI 또한 설치 되었을 가능성이 높으나 만일을 위하여 최종확인을 한다.

$sudo dnf install awscli -y

Last metadata expiration check: 7:27:44 ago on Tue Jul  1 06:35:04 2025.
Package awscli-2-2.25.0-1.amzn2023.0.1.noarch is already installed.
Dependencies resolved.
Nothing to do.
Complete!

- 이제 Amazon Q CLI 가 RDS, Aurora Cluster 에 사용할 Data API 및 Secret Manager 를 사용하려면 아래와 같이 IAM 권한을 추가 해 줘야한다. 필자는 이를 신규 Policy 로 만들어서 사용중인 role 에 넣었다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds-data:ExecuteStatement",
                "rds-data:BatchExecuteStatement",
                "rds-data:BeginTransaction",
                "rds-data:CommitTransaction",
                "rds-data:RollbackTransaction"
            ],
            "Resource": "arn:aws:rds:*:*:cluster:your-cluster-name"
        },
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:your-secret-name"
        }
    ]
}

출처 : 본인 테스트

- 그다음 아래 CLI 를 통하여 Aurora Cluster 에 사용할 Data API 를 활성화 시킨다.

# Aurora 클러스터의 Data API 활성화 (결과가 나오는지 까지 확인 필요)

$ aws rds modify-db-cluster \
    --db-cluster-identifier support-rds-aurora-mysql-test \
    --enable-http-endpoint \
    --region ap-northeast-2

{
    "DBCluster": {
        "AllocatedStorage": 1,
        "AvailabilityZones": [
            "ap-northeast-2b",
            "ap-northeast-2a",
            "ap-northeast-2d"
(...)

- 여기까지가 설치과정이며, 이후에는 Amazon Q CLI 가 정상적으로 실행되는지 테스트 해 보면된다.

$q

# Amazon Q 접속 후, tool 확인

/tools

출처 : 본인 테스트

Amazon Q 에서는 영어가 기본 제공 언어이지만 AI 특성상 한국어도 인식한다.

> 한국어 인식

> I can recognize and understand Korean text. You wrote "한국어 인식" which means "Korean recognition" or "Korean language
recognition."

I'm able to communicate in Korean if you'd prefer to continue our conversation in Korean, or I can help you with any Korean-
related tasks you might have. What would you like assistance with?

출처 : 본인 테스트

- 이제 우리가 위의 JSON 파일을 통해 인식시킨 Cluster 에 Amazon Q 가 접속하는지 확인 해 보자. 아래의 프롬프트를 작성하면 된다. (보안을 위해 필자의 cluster 명은 가렸다.)

출처 : 본인 테스트

- 위와 같이 Amazon Q 가 접속이 가능해 지면 DB 작업 등도 요청 할 수 있다. 이 때, 아래에 보면 Amazon Q 가 DB 작업을 수행하도록 허용 하도록 한번 더 묻는데. 여기서 필자는 Amazon Q 가 계속 이후에도 작업을 하도록 t (trust) 로 설정했다.

출처 : 본인 테스트

- 이후에 MCP 의 장점을 기술하겠지만, MCP 는 아래와 같이 사용자 환경에 맞춰 공개 AI 솔루션의 답변이외에 자체적인 조치도 취할 수있다. 예를 들어 필자가 사용하는 Amazon Linux 에는 MySQL Client 가 설치되어 있지 않아 실제 DB 작업을 할 수 없었지만, Amazon Q 에게 특정 작업을 요청하면서 Amazon Q 가 이를 확인 필요한 조치도 알아서 취할 수 있다.

출처 : 본인 테스트

(중간 생략)

출처 : 본인 테스트

이와 같이 사용자가 SQL 및 명령어등을 직접 작성하지 않아도 Amazon Q CLI MCP 가 사용자의 환경에 맞춘 답변을 내놓 도록 할 수 있다.

Kafka server.property (config 설정) 관련 옵션들 - 1

`O` — Tue, 1 Jul 2025 03:10:45 +0900

이 페이지에서는 Kafka broker 들을 구성할 때, 튜닝을 고려 할 수 있는 server.property 옵션들에 대하여 다룬다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

또한, 출처 또한 동시에 표기한다.

[kafka server.properties 에서 자주 사용되는 옵션들을 알려줘]

Kafka 서버(브로커)에서 자주 사용되는 주요 옵션(properties)은 다음과 같다.

주요 Kafka Server Properties

옵션명타입기본값설명

broker.id	int	0	브로커의 고유 식별자. 클러스터 내 각 브로커마다 중복되지 않아야 함1.
listeners	string	PLAINTEXT://:9092	브로커가 클라이언트 연결을 받을 수 있는 주소와 프로토콜 목록. 예: PLAINTEXT://:9092,SSL://:90932 31.
advertised.listeners	string	null	클라이언트가 실제로 연결해야 하는 주소. 외부 클라이언트가 접근해야 할 경우 설정 필요21.
log.dirs	string	/tmp/kafka-logs	메시지 데이터가 저장되는 디렉터리 경로. 여러 경로 지정 가능2 31.
num.network.threads	int	3	네트워크 요청을 처리하는 스레드 수3 41.
num.io.threads	int	8	디스크 I/O 처리 스레드 수3 41.
num.recovery.threads.per.data.dir	int	1	데이터 디렉터리마다 로그 복구에 사용되는 스레드 수3 41.
default.replication.factor	int	1	새로 생성되는 토픽의 기본 복제 인자. 보통 3으로 설정41.
num.partitions	int	1	새로 생성되는 토픽의 기본 파티션 수41.
log.retention.hours	int	168 (7일)	로그(메시지)가 보관되는 최대 시간41.
log.segment.bytes	int	1073741824 (1GB)	하나의 로그 세그먼트 파일의 최대 크기41.
zookeeper.connect	string	localhost:2181	ZooKeeper 연결 정보. 클러스터 내 ZooKeeper 서버 목록1.
auto.create.topics.enable	boolean	true	존재하지 않는 토픽에 대한 생성을 자동으로 허용할지 여부1.

참고

listeners와 advertised.listeners는 클라이언트가 브로커에 접근하는 방식과 실제 연결 주소를 구분하여 설정할 때 중요하다21.
log.dirs는 여러 경로를 지정할 수 있어 데이터 저장 공간을 확장할 수 있다2 31.
num.network.threads, num.io.threads 등은 브로커의 성능 튜닝에 자주 사용된다3 41.
default.replication.factor와 num.partitions는 토픽의 내구성과 병렬 처리 능력에 영향을 준다41.
log.retention.hours와 log.segment.bytes는 메시지 저장 정책을 결정한다41.

이 옵션들은 Kafka 브로커의 기본 동작, 성능, 내구성, 확장성에 큰 영향을 미친다.

※ RDBMS 에서 파라미터 사용에 익숙하다면 이를 연상하여 읽으면 된다.

[broker.id 가 필요한 이유]

broker.id는 Kafka 클러스터 내에서 각 브로커를 고유하게 식별하기 위해 반드시 필요한 값이다. 클러스터에 여러 브로커가 존재할 때, 각 브로커가 자신만의 고유한 숫자 ID를 가져야만 클러스터 관리, 메타데이터 동기화, 장애 복구, 파티션 할당 등 다양한 작업에서 서로를 명확히 구분할 수 있다1 56.

예를 들어, 브로커가 새로 추가되거나 장애가 발생했을 때 클러스터는 broker.id를 기준으로 해당 브로커를 식별하고, 메타데이터(예: 컨트롤러 정보, 파티션 할당 상태 등)를 올바르게 관리한다78. 만약 broker.id가 중복되면 클러스터 내에서 브로커를 구분할 수 없게 되어 시스템 오류나 데이터 불일치가 발생할 수 있다.

정리하면, broker.id는 Kafka 클러스터의 안정적이고 일관성 있는 운영을 위해 각 브로커에 반드시 설정해야 하는 고유 식별자다.

[listeners 가 필요한 이유와 advertised.listeners 와의 연관성]

listeners는 Kafka 브로커가 실제로 클라이언트의 연결 요청을 수신하는 네트워크 인터페이스와 포트를 지정하는 설정이다. 즉, 브로커가 어느 IP 주소나 호스트, 그리고 어떤 포트에서 메시지를 받을지 결정한다. 예를 들어, listeners=PLAINTEXT://localhost:9092로 설정하면 브로커는 로컬호스트의 9092 포트에서 PLAINTEXT 프로토콜로 들어오는 연결을 받게 된다1 23.

이 설정은 브로커가 클라이언트와 통신하기 위해 반드시 필요하다. 만약 listeners를 설정하지 않으면, 브로커는 외부에서 접근할 수 없게 된다2.

advertised.listeners는 브로커가 클라이언트(프로듀서, 컨슈머, 다른 브로커 등)에게 자신의 위치를 알릴 때 사용하는 주소다. 클라이언트는 이 정보를 바탕으로 브로커에 접속한다. 특히, 브로커가 내부 네트워크와 외부 네트워크에서 서로 다른 주소로 접근해야 할 때(예: 내부에서는 사설 IP, 외부에서는 퍼블릭 IP 또는 도메인 사용), advertised.listeners를 통해 외부 클라이언트가 올바른 주소로 접속할 수 있게 해준다1 45.

예를 들어,

listeners=PLAINTEXT://192.168.1.10:9092
advertised.listeners=PLAINTEXT://kafka.example.com:9092
이렇게 설정하면, 브로커는 내부 네트워크(192.168.1.10)에서 실제로 연결을 받지만, 클라이언트는 kafka.example.com 주소로 연결을 시도하게 된다.

두 설정의 연관성은 다음과 같다.

listeners는 브로커가 실제로 바인딩하는 주소(수신 주소)다.
advertised.listeners는 클라이언트가 브로커에 접속할 때 사용할 주소(공개 주소)다.
advertised.listeners를 따로 지정하지 않으면, listeners 설정이 클라이언트에게도 그대로 전달된다15.

이렇게 분리함으로써 내부/외부 네트워크, 프록시, 로드밸런서 등 다양한 환경에서 Kafka 클러스터를 유연하게 운영할 수 있다.

※ Kafka listeners 는 프로토콜, 호스트 이름, 포트 양식으로 접속 설정이 된다. 구버전은 단순 포트 설정으로만 설정이 가능했다.

[log.dirs 와 num.recovery.threads.per.data.dir 와의 연관성]

log.dirs와 num.recovery.threads.per.data.dir는 모두 Kafka 브로커가 데이터를 저장하고 관리하는 데 중요한 역할을 하며, 서로 밀접하게 연관되어 있다.

log.dirs
- Kafka가 메시지를 저장하는 로그 디렉터리(폴더) 경로를 지정한다.
- 여러 경로를 쉼표로 구분해 입력할 수 있으며, 이 경우 데이터가 여러 디렉터리로 분산 저장된다1 23.
num.recovery.threads.per.data.dir
- 각 로그 디렉터리(즉, log.dirs에 지정된 각 경로)마다 로그 복구(시작/종료 시 데이터 검증 및 동기화)에 사용할 수 있는 스레드(쓰레드) 개수를 지정한다4 12.
- 예를 들어, log.dirs에 3개의 경로가 있고, num.recovery.threads.per.data.dir=4로 설정하면 총 12개의 스레드가 복구 작업에 사용될 수 있다(그러나 실제로는 복구 작업이 각 디렉터리별로 병렬로 이루어지므로, 복구 속도가 빨라질 수 있다).

즉, log.dirs에 지정된 디렉터리 개수가 많아질수록 num.recovery.threads.per.data.dir 값이 전체 복구 스레드 수에 미치는 영향이 커진다.
이 두 설정은 함께 조정하여, 브로커 시작/종료 시 로그 복구 속도를 최적화할 수 있다.
실제 운영 환경에서는 여러 디렉터리를 사용해 I/O 병목을 줄이고, 복구 스레드 수를 늘려 복구 시간을 단축하는 것이 일반적이다.

[auto.create.topics.enable 에 대해서 더 알려줘]

auto.create.topics.enable는 Kafka 브로커의 중요한 설정 중 하나로, 존재하지 않는 토픽에 대해 메시지를 전송하거나 읽으려고 할 때 해당 토픽을 자동으로 생성할지 여부를 결정한다. 기본값은 true로, 별도로 지정하지 않으면 자동 생성이 활성화된다1 25.

이 옵션의 주요 특징과 주의점은 다음과 같다.

자동 생성 동작
- 프로듀서가 존재하지 않는 토픽으로 메시지를 발송하거나, 컨슈머가 존재하지 않는 토픽을 읽으려고 할 때 브로커가 토픽을 자동으로 생성한다.
- 자동 생성되는 토픽의 파티션 수와 복제 인자(replication factor)는 각각 num.partitions, default.replication.factor 설정값을 따른다1 28.
편의성 vs 관리
- 개발 및 테스트 환경에서는 편의를 위해 자동 생성이 유용하다.
- 운영 환경에서는 원치 않는 토픽이 생성되어 불필요한 리소스를 소모하거나, 잘못된 설정(파티션 수, 복제 인자 등)으로 성능에 영향을 줄 수 있으므로 false로 설정하는 것이 권장된다2 36.
성능 및 관리 영향
- 자동 생성된 토픽이 많아지면 브로커의 메타데이터 관리 부담이 커지고, 불필요한 파티션 증가로 인해 컨슈머의 데이터 읽기 지연(latency)이 발생할 수 있다36.
- 복제 인자나 파티션 수가 기본값(1)으로 설정될 경우, 장애 내구성이나 병렬 처리 성능이 떨어질 수 있다.
관리 팁
- 운영 환경에서는 토픽을 명시적으로 생성해 관리하는 것이 바람직하다.
- 자동 생성 기능을 끄고 싶다면 auto.create.topics.enable=false로 설정하면 된다6 910.

정리하면, auto.create.topics.enable는 Kafka의 편의성을 높여주지만, 운영 안정성과 성능을 위해 신중히 사용해야 하는 옵션이다.

MongoDB shell 사용방법 및 관련 명령어 - 2

`O` — Tue, 17 Jun 2025 02:12:53 +0900

이 페이지에서는 이전 게시글에 이어 MongoDB 를 사용하기 위해 필요한 MongoDB shell 사용방법 및 관련 명령어에 대하여 다룬

다.

[+] 2025.06.14 - [분류 전체보기] - MongoDB shell 사용방법 및 관련 명령어 - 1

또한, 이 게시글은 도서 O'REILLY 사의 저서 '몽고DB 완벽가이드' 의 내용들을 심화 이해하기 위하여 작성하는 글이다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

마지막으로 이 페이지는 EC2 Amazon Linux 2023 에 설치된 기본 MongoDB 를 사용한다.

Mongoshrc.js 파일을 이용한 MongoDB 접속시 표기되는 프롬프트 커스토마이징

MongoDB 는 mongoshrc.js 를 이용하여 아래 예시와 같이 mongoshell 의 프롬프트 환경또한 커스토마이징 할 수 있다.

#아래의 구문을 추가하여 mongosh 의 prompt 에서 현재 명령어가 수행되는 시간을 표기

$vi ~/.mongoshrc.js

prompt = function() {
        return (new Date())+"> ";
};

$ mongosh 127.0.0.1:27017
Current Mongosh Log ID: 685046103fe32ebbe069e327
Connecting to:          mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.2
Using MongoDB:          8.0.10
Using Mongosh:          2.5.2

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

------
   The server generated these startup warnings when booting
   2025-06-16T14:19:15.343+00:00: Access control is not enabled for the database. Read and write access to data and configuration is unrestricted
   2025-06-16T14:19:15.344+00:00: For customers running the current memory allocator, we suggest changing the contents of the following sysfsFile
   2025-06-16T14:19:15.344+00:00: For customers running the current memory allocator, we suggest changing the contents of the following sysfsFile
   2025-06-16T14:19:15.344+00:00: We suggest setting the contents of sysfsFile to 0.
   2025-06-16T14:19:15.344+00:00: vm.max_map_count is too low
------

Hello, you're looking particulary intelligent today!
Mon Jun 16 2025 16:28:00 GMT+0000 (Coordinated Universal Time)>

Shell 에서 다중 코드 및 객체 블록등을 작성할 때, 아래 줄을 작성 중, 윗줄에서 오타등을 수정하는 건 매우 번거롭다. 이 때 사용할 수 있는데 editor 다. editor 는 아래와 같은 순서로 사용한다.

# Mongo shell 사용

# 어떤 editor 를 사용할 지 설정

test> config.set("editor", "vi")

# Editor 가 저장될 경로 설정

test> EDITOR="/home/ec2-user/"
/home/ec2-user/

# 특정 변수를 설정

test> var wap = db.books.findOne({title: "War and Peace"});

# 해당 변수값을 editor 에서 편집

test> edit wap
Opening an editor...

# vi 편집기에서 나오면 해당 변수 값이 shell 에 재반영 된다.

test> wap = null

특정 커맨드창에서 version 등의 단어들은 명령어 수행과 연관된 경우 예약어인 경우가 많다. MongoDB 에서 또한 이를 고려해야하는데 이는 사용자가 version 이라는 collection 을 만들면 아래의 기존 예약어와 충돌이 발생할수 있기 때문이다. 이때는 MongoDB 의 함수를 사용해야한다. (아래 예시이외에 여러 함수들은 AI 검색을 사용하면 편리하다.)

# version 이라는 collection 에 접근시, 이는 기존 예약어와 충돌된다.

test> db.version
[Function: version] AsyncFunction {
  apiVersions: [ 0, 0 ],
  returnsPromise: true,
  serverVersions: [ '0.0.0', '999.999.999' ],
  topologies: [ 'ReplSet', 'Sharded', 'LoadBalanced', 'Standalone' ],
  returnType: { type: 'unknown', attributes: {} },
  deprecated: false,
  platforms: [ 'Compass', 'Browser', 'CLI' ],
  isDirectShellCommand: false,
  acceptsRawInput: false,
  shellCommandCompleter: undefined,
  help: [Function (anonymous)] Help
}

# getCollection 이라는 함수를 통해 version collection 에 접근

test> db.getCollection("version");
test.version

Array (배열) 를 통해 유효하지 않은 collection 명을 피할 수도 있다. 또한 Mongo shell 은 Javascript 편집기 기능도 있으므로, 이를 이용해 아래의 반복문을 통해 Array 에 있는 collection 만 조회 할 수도 있다.

test> var collections = ["posts","comments","authors"]

test> for (var i in collections) {
... print(db.blog[collections[i]]);
... }
test.blog.posts
test.blog.comments
test.blog.authors

접근하려는 collection 의 이름이 조회하기 힘든 명칭일 시, 아래와 같은 wildcard 등을 이용한 검색을 이용 할 수도 있다.

test> var name = "@#&!"

test> db[name].find()

Kafka Broker 설치 방법

`O` — Mon, 16 Jun 2025 02:46:29 +0900

이 페이지에서는 Zookeeper 설치 이후, Kafka Broker 를 설치하는 방법에 대하여 다룬다.

Kafka Broker 설치는 Zookeeper 설치가 먼저 선행 되어야 하기에 아래의 게시글을 먼저 참조 및 수행 후, 이 게시글을 확인하는 것을 권장한다.

[1] 2025.06.13 - [Kafka, MSK, Kinesis/아키텍처 및 내부 구조] - Zookeeper 설치 방법 - 기본설치

[2] 2025.06.15 - [Kafka, MSK, Kinesis/아키텍처 및 내부 구조] - Zookeeper 설치 방법 - 앙상블 (ensemble) 구성

또한 설치하는 방법에 추가로 덧붙일 내용은 ※ 로 추가한다.

필자는 AWS EC2 Linux 2 기준으로 Kafka 를 설치한다.

Kafka 설치

Zookeeper 를 설치했다면 이제 Kafka 를 설치할 수 있다.

Kafka 는 아래의 링크에서 설치할 버전을 고르면 된다.

[+] https://kafka.apache.org/downloads

- 여기서 필자는 Scala 2.13.0 - Kafka 3.9.1 버전을 사용한다.

출처 : 본인 테스트

※ Kakfa 는 JVM 기반에서 작동하는 Scala 언어로 만들어졌다.

- EC2 에서 Zookeeper 와 유사하게 wget 으로 다운로드 및 tar 로 압축을 푼다.

(필자는 ec2-user home directory 에 이를 설치 및 구성을 한다.)

$ wget https://dlcdn.apache.org/kafka/3.9.1/kafka_2.13-3.9.1.tgz
--2025-06-15 17:00:49--  https://dlcdn.apache.org/kafka/3.9.1/kafka_2.13-3.9.1.tgz
Resolving dlcdn.apache.org (dlcdn.apache.org)... 151.101.2.132, 2a04:4e42::644
Connecting to dlcdn.apache.org (dlcdn.apache.org)|151.101.2.132|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 122110298 (116M) [application/x-gzip]
Saving to: ‘kafka_2.13-3.9.1.tgz’

100%[========================================================================================>] 122,110,298  316MB/s   in 0.4s

2025-06-15 17:00:50 (316 MB/s) - ‘kafka_2.13-3.9.1.tgz’ saved [122110298/122110298]

$ tar -xzf kafka_2.13-3.9.1.tgz

- kafka 의 log 를 보관할 디렉토리를 임의로 생성 후, kafka 디렉토리에 있는 bin 디렉토리에서 아래의 명령어로 kafka daemon 을 실행한다.

# log 디렉토리 생성

$ mkdir /tmp/kafka-logs
 
# bin 디렉토리에서 daemon 기동
 
$ sh /home/ec2-user/kafka_2.13-3.9.1/bin/kafka-server-start.sh \
> -daemon /home/ec2-user/kafka_2.13-3.9.1/config/server.properties

# kafka 기동유무 확인

$ ps -ef | grep kafka

ec2-user 20794     1  4 17:06 pts/1    00:00:06 /usr/java/jdk-17.0.2//bin/java -Xmx1G -Xms1G -server -XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+ExplicitGCInvokesConcurrent -XX:MaxInlineLevel=15 -Djava.awt.headless=true -Xlog:gc*:file=/home/ec2-user/kafka_2.13-3.9.1/bin/../logs/kafkaServer-gc.log:time,tags:filecount=10,filesize=100M -Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dkafka.logs.dir=/home/ec2-user/kafka_2.13-3.9.1/bin/../logs -Dlog4j.configuration=file:/home/ec2-user/kafka_2.13-3.9.1/bin/../config/log4j.properties -cp /home/ec2-user/kafka_2.13-3.9.1/bin/../libs/activation-1.1.1.jar:/home/ec2-user/kafka_2.13-3.9.1/bin/../libs/aopalliance-repack
(...)

- Kafka 기동을 확인하면 아래 명령어들을 수행하여 topic 을 생성하고, 메시지를 기록해 본다.

# bin 디렉토리에서 해당 명령어로 Topic 생성

sh kafka-topics.sh --bootstrap-server localhost:9092 \
> --create --replication-factor 1 --partitions 1 --topic test

Created topic test.

# 메시지 기입, 기입 후 ctrl + c 로 빠져나오기가 가능

sh kafka-console-producer.sh --bootstrap-server localhost:9092 --topic test
>Test Message 1
>Test Message 2
^C

# 작성한 메시지 읽기

sh kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic test --from-beginning
Test Message 1
Test Message 2
^C
Processed a total of 2 messages

Zookeeper 설치 방법 - 앙상블 (ensemble) 구성

`O` — Sun, 15 Jun 2025 23:22:45 +0900

이 페이지에서는 Kafka 를 설치하기 위해 필요한 zookeeper 를 앙상블 (ensemble) 클러스터 단위로 설치하는 방법에 대해서 다룬다. 이 게시글은 아래의 게시글에 이어지는 글이기에 이전 글을 먼저 읽는 것을 권장한다.

[+] 2025.06.13 - [Kafka, MSK, Kinesis/아키텍처 및 내부 구조] - Zookeeper 설치 방법 - 기본설치

또한 설치하는 방법에 추가로 덧붙일 내용은 ※ 로 추가한다.

Zookeeper 의 기본설치 방법을 확인했다면 이제 실제 운영환경에서의 Zookeeper 의 고가용성도 고려 할 수 있다.

Zookeeper 는 이를 앙상블 (ensemble) 이라는 클러스터 개념으로 구현한다. 이에 대한 정보는 AI 검색을 하면 더 상세한 정보를 확인 해 볼 수 있다.

[Zookeeper 앙상블에 대해서 알려줘]

ZooKeeper 앙상블(Ensemble)이란?

ZooKeeper 앙상블은 여러 대의 ZooKeeper 서버가 하나의 클러스터를 이루어 동작하는 구조를 의미합니다. 이 구조는 고가용성(HA)과 데이터 일관성을 보장하기 위해 사용됩니다. 앙상블 내의 ZooKeeper 서버들은 서로 복제(replication) 및 동기화(synchronization)를 하며, 분산 시스템의 신뢰성과 안정성을 높입니다1 45.

주요 특징 및 구조

Leader-Follower 구조
앙상블에는 반드시 한 대의 Leader와 여러 대의 Follower가 존재합니다.
- Leader: 모든 쓰기(Write), 업데이트(Update), 삭제(Delete) 요청을 처리합니다.
- Follower: Leader의 복제본 역할을 하며, 주로 읽기(Read) 요청을 처리하고 Leader의 명령에 따라 데이터를 동기화합니다1 57.
리더 선출(Leader Election)
서버가 시작되면 자동으로 리더 선출 과정이 진행됩니다. 리더가 장애가 나면 나머지 서버 중 하나가 새로운 리더로 선출됩니다15.
쿼럼(Quorum) 기반 합의
ZooKeeper 앙상블은 과반수(쿼럼) 이상의 서버가 동작해야 쓰기 작업이 가능합니다. 예를 들어, 3대 앙상블이면 2대 이상이 살아 있어야 정상 동작합니다4 710.
홀수 개 서버 권장
쿼럼 구조상 서버 수는 홀수(3, 5, 7...)로 구성하는 것이 일반적입니다. 짝수로 구성해도 되지만, 장애 허용 범위와 쿼럼 계산상 효율이 떨어집니다2 3 47.

앙상블의 동작 방식

쓰기(Write) 요청:
모든 쓰기 요청은 리더에게 전달되어, 리더가 팔로워들에게 제안(Propose) 후 과반수(쿼럼) 이상의 승인(ACK)을 받으면 커밋(Commit)합니다. 이 과정에서 데이터 일관성이 보장됩니다5.
읽기(Read) 요청:
팔로워 서버에서도 읽기 요청을 처리할 수 있으나, 강한 일관성이 필요한 경우 리더를 통해 읽기도 가능합니다.
장애 허용:
예를 들어 3대 앙상블이면 1대가 장애 나도 2대가 살아 있으면 정상 동작합니다. 5대면 2대까지 장애 허용410.

ZooKeeper 앙상블 구성 예시

tickTime=2000 
dataDir=/data 
clientPort=2181 
initLimit=10 
syncLimit=5 
server.1=zk01:2888:3888 
server.2=zk02:2888:3888 
server.3=zk03:2888:3888

각 서버는 고유한 myid(1, 2, 3 등)를 부여받아야 하며, 설정 파일에 서버 정보를 명시합니다68.

ZooKeeper 앙상블의 활용

Kafka, HBase, ClickHouse 등 다양한 분산 시스템에서 메타데이터 관리, 클러스터 상태 동기화 등에 필수적으로 사용됩니다57.
앙상블이 구성되어 있으면 한 대의 ZooKeeper 서버가 장애 나더라도 서비스가 중단되지 않고 지속적으로 동작할 수 있습니다10.

요약

ZooKeeper 앙상블은 여러 대의 ZooKeeper 서버로 구성된 클러스터
Leader-Follower 구조, 리더 선출, 쿼럼 기반 합의 방식
서버 수는 홀수로 구성 권장(최소 3대)
고가용성, 장애 허용, 데이터 일관성 보장
Kafka 등 다양한 분산 시스템에서 필수적으로 사용

앙상블 구조 덕분에 ZooKeeper는 분산 환경에서 신뢰성과 안정성을 확보할 수 있으며, 실제 운영 환경에서는 반드시 앙상블로 구성하는 것이 표준입니다1 4 5 710.

※ Quorum 은 AWS Aurora Cluster 의 장애 관리 logic 에도 쓰이는 개념이므로 Aurora Cluster 도 같이 이용하는 사용자라면 같이 알아 두면 좋다.

※ 앙상블은 합의 프로토콜로 운영됨에 따라 이와 연관되는 성능을 고려 시, 9대 이내의 서버로 구성되는 것이 권장된다. (출처 : O'REILLY - '카프카 핵심 가이드' )

※ 위의 예시는 3대의 서버로 앙상블을 구성 하는 예시며, 이때 사용되는 config 명령문은 server.{x}={hostname}:{peerPort}:{leaderPort} 로 정의된다. 이 때, x 는 서버ID, hostname 은 서버의 호스트명 또는 IP 주소, peerPort 는 각 서버간 통신을 할 때 사용할 TCP port, leaderPort 는 리더를 선출하는 데 사용할 TCP port 번호다. 이 때, client 는 clientPort 에 지정된 port 만 사용해도 되지만 앙상블 구성 서버들은 이 3개의 port 를 모두 사용 할 수 있어야 한다.

※ 모든 앙상블 서버의 dataDir 디렉토리에는 myid 라는 이름의 파일에 각 서버 ID 번호를 가지고 있어야하며 이를 통해 앙상블간 통신이 가능하다.

실제 운영환경에서는 3개의 독립적인 서버에 zookeeper 를 설치해 이를 구현하나, 테스트환경에서는 한대의 서버 또는 클라우드 instance 에 아래의 방법으로 구현 할 수 있다.

1대의 EC2 에 3개의 node 로 앙상블 구현하기

먼저, 아래와 같이 3개의 node 가 이용될 data 디렉토리, zoo.cfg, myid 를 구성해야한다.

# 각 node 가 사용할 data 디렉토리 생성, 필자는 /home/ec2-user/ 디렉토리에 생성한다.

$ mkdir zookeeper1
$ mkdir zookeeper2
$ mkdir zookeeper3

# 기본 설치에서 사용했던 zoo.cfg 를 각 디렉토리에 복사 후, 각 환경에 맞게 수정한다.

$ cp zoo.cfg ~/zookeeper1/zoo.cfg
$ cp zoo.cfg ~/zookeeper2/zoo.cfg
$ cp zoo.cfg ~/zookeeper3/zoo.cfg

# 각 노드의 zoo.cfg 를 수정시, 한대의 ec2 에서 모든 node 를 구성하려면 아래와 같이 dataDir, clientPort 및 통신 Port 가 달라야한다.

[zookeeper1 - zoo.cfg]

tickTime=2000
dataDir=/home/ec2-user/zookeeper1/data
clientPort=2181
initLimit=20
syncLimit=5
server.1=127.0.0.1:2881:3881
server.2=127.0.0.1:2882:3882
server.3=127.0.0.1:2883:3883

[zookeeper2 - zoo.cfg]

tickTime=2000
dataDir=/home/ec2-user/zookeeper2/data
clientPort=2182
initLimit=20
syncLimit=5
server.1=127.0.0.1:2881:3881
server.2=127.0.0.1:2882:3882
server.3=127.0.0.1:2883:3883

[zookeeper3 - zoo.cfg]

tickTime=2000
dataDir=/home/ec2-user/zookeeper3/data
clientPort=2183
initLimit=20
syncLimit=5
server.1=127.0.0.1:2881:3881
server.2=127.0.0.1:2882:3882
server.3=127.0.0.1:2883:3883

# 각 data directory 에 myid 파일 생성및 ID 를 순차적으로 1,2,3 을 부여 (이 번호는 사용자가 임의로 지정 가능)


$cat ~/zookeeper1/data/myid
1
$cat ~/zookeeper2/data/myid
2
$cat ~/zookeeper3/data/myid
3

해당 사항을 작성하면 이제 순차적으로 아래의 명령어들로 각 node 를 실행하면 된다.

$cd  ~/apache-zookeeper-3.8.4-bin/bin

$ sh zkServer.sh start /home/ec2-user/zookeeper1/zoo.cfg
ZooKeeper JMX enabled by default
Using config: /home/ec2-user/zookeeper1/zoo.cfg
Starting zookeeper ... STARTED
$ sh zkServer.sh start /home/ec2-user/zookeeper2/zoo.cfg
ZooKeeper JMX enabled by default
Using config: /home/ec2-user/zookeeper2/zoo.cfg
Starting zookeeper ... STARTED
$ sh zkServer.sh start /home/ec2-user/zookeeper3/zoo.cfg
ZooKeeper JMX enabled by default
Using config: /home/ec2-user/zookeeper3/zoo.cfg
Starting zookeeper ... STARTED

3개의 node 가 모두 실행되면 이전 게시글의 test 과정 처럼 telnet 을 통해 접속을 수행 및 Mode 가 leader 인지, follower 인지 확인한다.

$ telnet localhost 2181
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
srvr
Zookeeper version: 3.8.4-9316c2a7a97e1666d8f4593f34dd6fc36ecc436c, built on 2024-02-12 22:16 UTC
Latency min/avg/max: 0/0.0/0
Received: 1
Sent: 0
Connections: 1
Outstanding: 0
Zxid: 0x0
Mode: follower
Node count: 5
Connection closed by foreign host.

$ telnet localhost 2182
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
srvr
Zookeeper version: 3.8.4-9316c2a7a97e1666d8f4593f34dd6fc36ecc436c, built on 2024-02-12 22:16 UTC
Latency min/avg/max: 0/0.0/0
Received: 1
Sent: 0
Connections: 1
Outstanding: 0
Zxid: 0x100000000
Mode: leader
Node count: 5
Proposal sizes last/min/max: -1/-1/-1
Connection closed by foreign host.

$ telnet localhost 2183
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
srvr
Zookeeper version: 3.8.4-9316c2a7a97e1666d8f4593f34dd6fc36ecc436c, built on 2024-02-12 22:16 UTC
Latency min/avg/max: 0/0.0/0
Received: 1
Sent: 0
Connections: 1
Outstanding: 0
Zxid: 0x100000000
Mode: follower
Node count: 5
Connection closed by foreign host.

MongoDB shell 사용방법 및 관련 명령어 - 1

`O` — Sat, 14 Jun 2025 15:51:23 +0900

이 페이지에서는 MongoDB 를 사용하기 위해 필요한 MongoDB shell 사용방법 및 관련 명령어에 대하여 다룬다.

또한, 이 게시글은 도서 O'REILLY 사의 저서 '몽고DB 완벽가이드' 의 내용들을 심화 이해하기 위하여 작성하는 글이다.

이 페이지는 perplexity 를 통해 필자가 어떤 prompt 를 작성하여 공부하는지를 공유한다. ([] 로 표기)

또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.

AI 를 통해 관련된 자료를 검색하다보면 이전 게시글과 중복된 사항도 있으나 이는 복습 및 상기 차원에서 그대로 기재 되도록 한다.

마지막으로 이 페이지는 EC2 Amazon Linux 2023 에 설치된 기본 MongoDB 를 사용한다.

EC2 Amazon Linux 2023 에 MongoDB 를 설치하는 방법은 아래의 링크를 참조한다.

[+] https://www.mongodb.com/ko-kr/docs/manual/tutorial/install-mongodb-on-amazon/#std-label-install-mdb-community-amazon-linux

MongoDB shell 을 통한 MongoDB 접속시 사용하는 기본 명령어

- MongoDB 는 아래의 명령어로 기본접속이 가능하다

Mongo host(host명):30000(port, MongoDB 의 기본 port 는 27017 이다.)/test(DB명)

- 위의 명령어 없이 기본 shell 로만 대화형 인터페이스로만 들어갈수도 있다.

mongo --nodb

- 위의 상태로만 접속을 해도 shell 에서 아래의과정으로 mongod 에 접속이 가능하다.

> conn = new Mongo("127.0.0.1:27017")
mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000
> db = conn.getDB("test")
test
test>

- 다른 프로그램과 마찬가지로 MongoDB 도 help 를 사용 할 수 있다.

test> help

  Shell Help:

    log                                        'log.info(<msg>)': Write a custom info/warn/error/fatal/debug message to the log file
                                               'log.getPath()': Gets a path to the current log file

    use                                        Set current database
    show                                       'show databases'/'show dbs': Print a list of all available databases
                                               'show collections'/'show tables': Print a list of all collections for current database
                                               'show profile': Prints system.profile information
                                               'show users': Print a list of all users for current database
                                               'show roles': Print a list of all roles for current database
                                               'show log <type>': log for current connection, if type is not set uses 'global'
                                               'show logs': Print all logs
    exit                                       Quit the MongoDB shell with exit/exit()/.exit
    quit                                       Quit the MongoDB shell with quit/quit()
    Mongo                                      Create a new connection and return the Mongo object. Usage: new Mongo(URI, options [optional])
    connect                                    Create a new connection and return the Database object. Usage: connect(URI, username [optional], password [optional])
    it                                         result of the last line evaluated; use to further iterate
    version                                    Shell version
    load                                       Loads and runs a JavaScript file into the current shell environment
    enableTelemetry                            Enables collection of anonymous usage data to improve the mongosh CLI
    disableTelemetry                           Disables collection of anonymous usage data to improve the mongosh CLI
    passwordPrompt                             Prompts the user for a password
    sleep                                      Sleep for the specified number of milliseconds
    print                                      Prints the contents of an object to the output
    printjson                                  Alias for print()
    convertShardKeyToHashed                    Returns the hashed value for the input using the same hashing function as a hashed index.
    cls                                        Clears the screen like console.clear()
    isInteractive                              Returns whether the shell will enter or has entered interactive mode

  For more information on usage: https://mongodb.com/docs/manual/reference/method

- 추가로 help 옆에 명령어를 추가로 붙이면, DB 단위, collection 단위로 help 명령어를 확인 할 수 있다.

test> db.help()

  Database Class:

    getMongo                                   Returns the current database connection
    getName                                    Returns the name of the DB
    getCollectionNames                         Returns an array containing the names of all collections in the current database.
    getCollectionInfos                         Returns an array of documents with collection information, i.e. collection name and options, for the current database.
    runCommand                                 Runs an arbitrary command on the database.
    adminCommand                               Runs an arbitrary command against the admin database.
    aggregate                                  Runs a specified admin/diagnostic pipeline which does not require an underlying collection.
    getSiblingDB                               Returns another database without modifying the db variable in the shell environment.
    getCollection                              Returns a collection or a view object that is functionally equivalent to using the db.<collectionName>.
    dropDatabase                               Removes the current database, deleting the associated data files.
    createUser                                 Creates a new user for the database on which the method is run. db.createUser() returns a duplicate user error if the user already exists on the database.
    updateUser                                 Updates the user’s profile on the database on which you run the method. An update to a field completely replaces the previous field’s values. This includes updates to the user’s roles array.
    changeUserPassword                         Updates a user’s password. Run the method in the database where the user is defined, i.e. the database you created the user.
    logout                                     Ends the current authentication session. This function has no effect if the current session is not authenticated.
    dropUser                                   Removes the user from the current database.
    dropAllUsers                               Removes all users from the current database.
    auth                                       Allows a user to authenticate to the database from within the shell.
    grantRolesToUser                           Grants additional roles to a user.
    revokeRolesFromUser                        Removes a one or more roles from a user on the current database.
    getUser                                    Returns user information for a specified user. Run this method on the user’s database. The user must exist on the database on which the method runs.
    getUsers                                   Returns information for all the users in the database.
    createCollection                           Create new collection
    createEncryptedCollection                  Creates a new collection with a list of encrypted fields each with unique and auto-created data encryption keys (DEKs). This is a utility function that internally utilises ClientEnryption.createEncryptedCollection.
    createView                                 Create new view
    createRole                                 Creates a new role.
    updateRole                                 Updates the role’s profile on the database on which you run the method. An update to a field completely replaces the previous field’s values.
    dropRole                                   Removes the role from the current database.
    dropAllRoles                               Removes all roles from the current database.
    grantRolesToRole                           Grants additional roles to a role.
    revokeRolesFromRole                        Removes a one or more roles from a role on the current database.
    grantPrivilegesToRole                      Grants additional privileges to a role.
    revokePrivilegesFromRole                   Removes a one or more privileges from a role on the current database.
(...)

test> db.foo.help()

  Collection Class:

    aggregate                                  Calculates aggregate values for the data in a collection or a view.
    bulkWrite                                  Performs multiple write operations with controls for order of execution.
    count                                      Returns the count of documents that would match a find() query for the collection or view.
    countDocuments                             Returns the count of documents that match the query for a collection or view.
    deleteMany                                 Removes all documents that match the filter from a collection.
    deleteOne                                  Removes a single document from a collection.
    distinct                                   Finds the distinct values for a specified field across a single collection or view and returns the results in an array.
    estimatedDocumentCount                     Returns the count of all documents in a collection or view.
    find                                       Selects documents in a collection or view.
    findAndModify                              Modifies and returns a single document.
    findOne                                    Selects documents in a collection or view.
    renameCollection                           Renames a collection.
    findOneAndDelete                           Deletes a single document based on the filter and sort criteria, returning the deleted document.
    findOneAndReplace                          Modifies and replaces a single document based on the filter and sort criteria.
    findOneAndUpdate                           Updates a single document based on the filter and sort criteria.
    insert                                     Inserts a document or documents into a collection.
    insertMany                                 Inserts multiple documents into a collection.
    insertOne                                  Inserts a document into a collection.
    isCapped                                   Checks if a collection is capped
    remove                                     Removes documents from a collection.
    replaceOne                                 Replaces a single document within the collection based on the filter.
    update                                     Modifies an existing document or documents in a collection.
    updateMany                                 Updates all documents that match the specified filter for a collection.
    updateOne                                  Updates a single document within the collection based on the filter.
    compactStructuredEncryptionData            Compacts structured encryption data
    convertToCapped                            calls {convertToCapped:'coll', size:maxBytes}} command
    createIndexes                              Creates one or more indexes on a collection
    createIndex                                Creates one index on a collection
    ensureIndex                                Creates one index on a collection
    getIndexes                                 Returns an array that holds a list of documents that identify and describe the existing indexes on the collection.
    getIndexSpecs                              Alias for getIndexes. Returns an array that holds a list of documents that identify and describe the existing indexes on the collection.
    getIndices                                 Alias for getIndexes. Returns an array that holds a list of documents that identify and describe the existing indexes on the collection.
    getIndexKeys                               Return an array of key patterns for indexes defined on collection
    dropIndexes                                Drops the specified index or indexes (except the index on the _id field) from a collection.
    dropIndex                                  Drops or removes the specified index from a collection.
    totalIndexSize                             Reports the total size used by the indexes on a collection.
    reIndex                                    Rebuilds all existing indexes on a collection.
    getDB                                      Get current database.
    getMongo                                   Returns the Mongo object.
    dataSize                                   This method provides a wrapper around the size output of the collStats (i.e. db.collection.stats()) command.
    storageSize                                The total amount of storage allocated to this collection for document storage.
    totalSize                                  The total size in bytes of the data in the collection plus the size of every index on the collection.
    drop                                       Removes a collection or view from the database.
    exists                                     Returns collection infos if the collection exists or null otherwise.
    getFullName                                Returns the name of the collection prefixed with the database name.
    getName                                    Returns the name of the collection.
(...)

- Javascript file 을 만들어서 sh 명령문에 바로 적용 할 수 있다.

#scrip1.js 파일 생성

print("I am script1.js")

# mongosh 에 바로 수행

$ mongosh script1.js
I am script1.js

- 아래와 같이 host,port,db 를 명시하여 적용 할 수 있다.

$ mongosh 127.0.0.1:27017/test script1.js
I am script1.js

- Shell 안에서 바로 파일을 load 할 수 있다.

test> load("script1.js")
I am script1.js
true

- 스크립트를 만들 때, shell 에서 사용하는 명령어를 Javascript 로 변환 해야 할 수 있다.

예를 들어, show db 는 javascript 파일에서는 db.get.Mongo().getDBs() 로 변환해서 작성해야한다.

- Javascript 파일이 위치한 경로와 실제 mongosh 를 수행하는 경로가 다를 시, 절대경로를 입력하면 다른 경로에 있는 Javascript 파일을 load 할 수 있다.

test> load("/home/ec2-user/script1.js")
I am script1.js
true

- Linux 등에서 프로그램을 실행 시, 임의로 시작 문구를 만들 수 있는 것 처럼 MongoDB 도 시작 문구를 만들 수 있다.

$ vi .mongoshrc.js

var compliment = ["attractive", "intelligent", "like Batman"];
var index = Math.floor(Math.random()*3);

print("Hello, you're looking particulary "+compliment[index]+" today!");

#작성 후 Mongosh 실행행

$ mongosh
Current Mongosh Log ID: 684d191a3094095ba169e327
Connecting to:          mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.2
Using MongoDB:          8.0.10
Using Mongosh:          2.5.2

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

------
   The server generated these startup warnings when booting
   2025-06-14T05:33:28.794+00:00: Access control is not enabled for the database. Read and write access to data and configuration is unrestricted
   2025-06-14T05:33:28.794+00:00: For customers running the current memory allocator, we suggest changing the contents of the following sysfsFile
   2025-06-14T05:33:28.794+00:00: For customers running the current memory allocator, we suggest changing the contents of the following sysfsFile
   2025-06-14T05:33:28.794+00:00: We suggest setting the contents of sysfsFile to 0.
   2025-06-14T05:33:28.794+00:00: vm.max_map_count is too low
------

Hello, you're looking particulary attractive today!