CUBRID | Enterprise Open Source DBMS

CircleCI 테스트 카테고리 확장 도입기 — Shell 테스트를 머지 이전 단계로 (1편)

강태우 — Tue, 02 Jun 2026 18:10:03 +0900

CircleCI 테스트 카테고리 확장 도입기 — Shell 테스트를 머지 이전 단계로 (1편)

통합 빌드에서 "원인 커밋"을 찾던 시간을, 어떻게 머지 이전으로 당겼는가

엔진 품질 · CI/테스트 인프라 | 1편

이 글에서 자주 나오는 용어

CI (Continuous Integration, 지속적 통합)
개발자가 코드를 고칠 때마다, 사람이 일일이 챙기지 않아도 자동으로 빌드(코드를 실행 가능한 형태로 조립)하고 테스트를 돌려 문제를 빠르게 잡아내는 방식. "코드를 합칠 때마다 자동으로 돌아가는 검사 라인"이라고 생각하면 됩니다.

파이프라인 (Pipeline)
CI에서 코드 변경이 들어오면 자동으로 빌드 → 테스트 → 결과 보고로 이어지는 일련의 작업 흐름. 이 글에서 '한 파이프라인'은 한 번의 PR이 트리거한 한 번의 작업 흐름 단위를 가리킵니다.

큐 (Queue)
먼저 들어온 것이 먼저 나가는 줄. 식당에서 차례를 기다리는 줄을 떠올리면 됩니다. 이 글에서는 대기 중인 테스트 파이프라인이나, 다시 돌려야 할 실패 케이스가 차례를 기다리는 줄을 가리킵니다.

커밋 · 머지 · PR
커밋은 코드 변경을 저장한 하나의 묶음, 머지는 여러 사람이 만든 커밋을 하나의 코드로 합치는 일, PR(Pull Request)은 "이 변경을 합쳐도 될까요?"라고 검토를 요청하는 단위입니다.

리그레션 테스트 (Regression Test, 회귀 테스트)
새로 고친 코드가 "원래 잘 되던 기능"을 망가뜨리지 않았는지 확인하는 테스트. 한 곳을 고쳤다가 엉뚱한 데가 깨지는 일을 막아 줍니다.

통합 빌드
여러 개발자의 커밋을 한꺼번에 합쳐서 만든 하나의 결과물. 여러 사람의 변경이 섞여 있어, 문제가 생기면 누구의 변경 탓인지 가려내기 어렵습니다.

컨테이너 · 파드(Pod) · Kubernetes
컨테이너는 프로그램과 그 실행 환경을 통째로 담아 어디서든 똑같이 돌아가게 만든 "포장 상자"입니다. 파드는 Kubernetes에서 컨테이너를 다루는 가장 작은 단위이고, Kubernetes(k8s)는 이 상자들을 자동으로 배치·관리해 주는 시스템입니다.

flaky 테스트 (불안정 테스트)
코드를 전혀 바꾸지 않았는데도 어떤 때는 통과하고 어떤 때는 실패하는, 결과를 믿기 어려운 테스트입니다.

노이지 네이버 (Noisy Neighbor)
같은 장비를 나눠 쓰는 옆 작업이 자원(디스크·CPU 등)을 너무 많이 차지해서, 정작 내 작업이 느려지거나 실패하는 현상. "옆집이 시끄러워서 내가 일을 못 하는" 상황에 빗댄 표현입니다.

CircleCI
코드를 올리면 자동으로 빌드·테스트를 실행해 주는 외부 CI 서비스. 이 글에서는 머지 이전 PR 단계의 테스트를 여기서 수행합니다.

RAID (0, 5 등)
여러 개의 물리 디스크를 묶어 하나의 큰 디스크처럼 쓰는 방식. RAID 0은 용량과 속도에는 유리하지만 디스크 한 장이 고장 나면 전체가 영향을 받고, RAID 5는 한 장이 고장 나도 견딜 수 있는 대신 쓰기 성능이 조금 떨어집니다. 어떤 레벨이든 묶인 디스크를 여러 작업이 동시에 두드리면 RAID 컨트롤러에서 경합이 일어나 느려질 수 있습니다.

fsync
데이터를 메모리에만 두지 않고 "지금 디스크에 확실히 기록하라"고 강제하는 명령. 데이터베이스가 안정적으로 동작하려면 꼭 필요하지만, 그만큼 디스크에 부담을 줍니다.

IaC (Infrastructure as Code, 코드형 인프라)
서버·클러스터 같은 인프라를 손으로 하나씩 설정하지 않고, 코드로 정의해 두고 그 코드를 실행해 똑같이 만들어 내는 방식. 재구축과 변경 이력 관리가 쉬워집니다.

들어가며

AI가 본격적으로 개발 현장에 들어오기 전, 우리 팀의 업무 시간 중 상당 부분을 잡아먹던 일이 하나 있었다. 바로 "어떤 커밋이 리그레션 테스트 실패를 유발했는가"를 찾아내는 일이다.

리그레션 테스트는 새로운 변경이 기존 기능을 망가뜨리지 않았는지 확인하는 테스트다. 문제는 이 테스트가 통합 빌드 — 여러 개발자의 커밋이 하나의 빌드에 모두 합쳐진 결과물 — 를 대상으로 수행된다는 점이었다.

왜 통합 빌드에서는 원인 커밋을 찾기 어려운가

그림 1. 기존에는 통합 빌드를 대상으로 리그레션 테스트를 한 번만 수행해 원인 커밋을 특정하기 어려웠다. 머지 이전에 커밋별로 동일한 테스트를 각각 수행하면, 실패해도 원인 커밋이 곧바로 드러난다.

테스트가 실패했다고 하자. 그런데 그 빌드 안에는 여러 사람의 커밋이 섞여 있다. 실패를 발견했다 한들 명확한 원인이 바로 드러나지 않고, 실패 상황을 똑같이 재현하기도 어려우며, "이 커밋이 원인이다"라고 증명하는 일은 더더욱 어렵다.

당시 원인을 찾는 방법은 크게 두 가지였다. 하나는 커밋을 하나씩 떼어내 개별 빌드를 만들고 실패한 리그레션 케이스를 반복 수행해 범인을 색출하는 방식, 다른 하나는 각 커밋의 이슈 내용과 코드 변경 사항을 읽어가며 실패 원인을 추론하는 방식이다. 어느 쪽이든 사람의 시간과 판단이 많이 드는 일이었다.

해결의 방향 — 테스트를 머지 이전으로 당기다

원인을 더 일찍, 더 명확하게 찾으려면 결국 테스트를 머지 이전 단계로 당겨야 했다. 우리는 이미 커밋이 머지되기 전 각 PR 단계에서 테스트를 수행하는 CircleCI를 쓰고 있었다. 여기에 그동안 가장 실패 원인 분석이 힘들었던 Shell 테스트 카테고리를 추가하기로 했다.

Shell 테스트는 사용자 관점의 시나리오·기능 테스트가 중심이다. 글에서는 편의상 "일부"라고 표현하지만, 실제로는 우리 테스트 자산 전체의 절반가량을 차지하는 결코 작지 않은 규모다.

1차 시도 — 클라우드 컨테이너 기반 테스트

그림 2. 1차 시도는 CircleCI가 제공하는 클라우드 컨테이너 인프라였다. 비용과 flaky 테스트라는 두 가지 벽에 부딪혔다.

첫 시도는 CircleCI가 제공하는 컨테이너 형태의 테스트 인프라를 만들어 클라우드 환경에서 테스트를 수행하는 것이었다. 결과는 두 가지 벽이었다. 하나는 감당하기 어려운 수준의 클라우드 인프라 비용, 다른 하나는 flaky 테스트의 폭증이었다.

우리 테스트 케이스 중에는 특정 고정 환경을 전제로 작성된 것들이 있어, 클라우드 환경에서 불안정하게 동작했다. 이 경험을 바탕으로 "직접 호스팅(self-hosted)"으로 방향을 틀었고, 두 번째 시도로 이어졌다.

2차 시도 — 셀프 호스팅 Kubernetes 클러스터

그림 3. 2차 시도는 신규 장비를 구매해 직접 운영하는 Kubernetes 클러스터. Ansible과 Kubespray로 클러스터 구축을 코드화했다.

두 번째 시도는 우리가 만든 컨테이너를 자체 호스팅하는 Kubernetes(k8s) 클러스터에서 운영하는 것이었다. 클러스터를 운영할 만한 장비가 없었기 때문에 신규 장비를 구매해 진행했다.

클러스터 구축은 코드로 관리할 수 있도록 Ansible 프로젝트로 구성했다. 클러스터를 프로비저닝하는 과정 전체를 코드 형태로 남긴 것이다. 구성에는 공식 툴인 Kubespray를 사용했고, 이 툴은 클러스터 생성뿐 아니라 이후 안정적인 운영에도 도움이 되었다.

회고 한 가지. 이 시점에 운영 중이던 실제 테스트의 메타데이터 — 자원 사용률, 디스크 사용률, 테스트 수행 시간 등 — 가 잘 기록되어 있었다면 구조 설계에 큰 도움이 되었을 것이다. 뒤에서 다시 이야기하겠지만, 이 데이터의 부재는 이후 여러 문제의 원인을 "확정"하지 못하게 만든 배경이 된다.

클러스터는 만들었지만 — 디스크 병목

그림 4. RAID로 묶인 디스크는 1:1 격리가 불가능해, 컨테이너 수가 많을수록 같은 RAID 묶음에 I/O가 집중되어 RAID 컨트롤러가 바빠지고 병목이 두드러진다.

클러스터를 완성했으니 다음은 "이 환경에서 테스트가 안정적으로 수행되는가"를 검증할 차례였다.

테스트 워크로드의 특성상 병렬도를 높일수록 수행 시간이 의미 있게 줄어들었고, 반대로 테스트 노드 한 대의 자원(CPU·메모리)을 키우는 것은 큰 도움이 되지 않았다. 추가하려는 Shell 테스트는 사용자 시나리오 기능 테스트가 중심이고, 검증의 유효성을 위해 테스트 시작과 끝에 DB 생성·삭제가 포함된다. 한 테스트 인스턴스에서 여러 CUBRID 프로세스와 테스트 케이스를 동시에 돌려 자원 사용률이 폭증할 일은 없는 구조였다.

하지만 병렬도를 높일 때 가장 큰 부작용은 디스크 병목이었다. 우리가 테스트하는 제품은 관계형 데이터베이스다. 디스크에 대한 랜덤 read/write, 그리고 fsync 같은 디스크 쓰기 작업이 필연적으로 발생한다. 이 사실을 인프라 구성 전에 충분히 고려하지 못해, CPU·메모리는 넉넉하지만 클러스터를 이루는 물리 노드(=서버) 대수는 적은 형태가 되어 있었다.

참고 — '물리 노드'와 '물리 디스크'는 다른 단위다. 물리 노드는 클러스터를 구성하는 1U 서버 한 대를 가리키고, 물리 디스크는 그 서버 안에 RAID로 묶여 있는 드라이브 한 장이다. 기존 리그레션 호스트는 1TB × 4장을 RAID 5로 묶은 1U 서버 여러 대를 한 대당 VM 2개로 쪼개 운영했고, 새 K8s 클러스터는 2TB × 4장을 RAID 0으로 묶은 1U 서버 4대 중 2대에 파드를 배포한다.

디스크가 RAID로 묶여 있는 한, '디스크 1장 = VM/파드 1개' 식의 1:1 격리는 본질적으로 불가능하다. 결국 같은 RAID 묶음을 여러 VM·파드가 공유하게 되니, 어느 환경에서든 디스크 병목은 일정 부분 발생할 수밖에 없다. 사실 기존 리그레션 환경(RAID 5 + 노드당 VM 2개)도 같은 원인의 flaky 현상을 가지고 있었다. 다만 K8s 클러스터는 한 노드에 훨씬 많은 파드가 올라가기 때문에 RAID 컨트롤러가 더 바빠지고, 그만큼 디스크 병목 현상이 더 두드러져 보였을 뿐이다.

그러나 당시에는 모니터링 시스템이 없었기 때문에 이를 "확정된 문제"로 인지하지 못했고, 막연히 "노이지 네이버 문제일 것"이라고 추측만 하고 있었다. 디스크 병목은 지금도 완전히 해결된 문제는 아니다. 다만 이를 최대한 회피하기 위해 여러 시도를 병행했다.

회피 전략 1 — 물리 디스크 대신 RAM 디스크

그림 5. 기존에는 한 노드의 모든 Pod이 그 노드의 RAID 디스크 묶음을 공유했지만, RAM 디스크(tmpfs)는 Pod별로 독립되어 공유 자원과 RAID 컨트롤러 경합 자체가 사라진다.

첫 번째 회피책은 물리 디스크 대신 메모리 디스크(RAM 디스크)를 사용해 디스크 병목을 원천 차단하는 것이었다. 이 아이디어는 연구소 개발팀 동료(H)의 제안에서 출발했다. 리그레션 테스트용 물리 호스트보다 k8s 클러스터의 메모리가 풍부했기 때문에, 이 메모리를 활용해 더 안정적인 테스트 환경을 만들 수 있었다.

이 과정에서 쓰기·읽기 타이밍 문제 — 데이터가 너무 빨리 쓰여 오히려 문제가 되는 상황 — 로 불안정해지는 테스트 케이스들이 드러났다. 이런 케이스는 unstable로 분류했다. unstable 케이스는 리그레션 테스트에서는 계속 수행하되, 개발 단계의 CI 테스트에는 포함하지 않기로 했다.

새로운 병목 — 동시성 대기 큐

그림 6. 한 파이프라인이 split으로 50개 워커를 모두 점유하면, 다른 사용자의 파이프라인은 대기 큐에서 차례를 기다려야 했다.

RAM 디스크를 적용하자 한 파이프라인의 처리 시간이 50% 감소했다. 그런데 다수의 사용자가 CI 테스트 서비스를 동시에 이용하면서 새로운 문제 — 동시성 대기 큐 — 가 나타났다. 도로는 있지만 1차선이라고 생각하면 된다.

계약사항 제약상 셀프 호스티드 러너는 워커 50개까지만 쓸 수 있었다. 빠른 적용을 목표로 했기에 테스트 프레임워크를 추가 개발하기보다는, CircleCI CLI가 제공하는 split(테스트 케이스 분배) 기능을 사용했다. 50개의 러너가 모두 워커가 되고, 각자 일정한 테스트 케이스 묶음을 받아 순차 수행하는 "50개의 로컬 워커" 형태였다. 이 구조에서는 한 사용자가 50개를 모두 선점하면, 뒤이어 테스트를 수행하려는 사용자는 대기 큐에서 자기 차례를 기다려야 한다.

50개를 모두 사용하게 된 데에는 이유가 있다. 50개보다 적은 병렬도로는 테스트 수행 시간이 1시간을 넘어가, 개발자들이 원하던 "비교적 빠른 결과 전달"이 불가능했다. 결국 워커 50개를 모두 사용해 각 분할(파드)이 로컬 워커로 동작하도록 했고, unstable로 분류한 리그레션 전용 케이스(약 10%)를 제외한 Shell 케이스 전체를 빠르게 처리할 수 있는 구조를 만들었다.

예상하지 못한 부작용 — 공유 자원 오염

그림 7. develop 브랜치의 테스트 케이스를 모두가 공유하다 보니, 머지로 인한 케이스 수정이 대기 중이던 다른 사용자의 파이프라인을 오염시켰다.

적용 결과는 예상과 달랐다. 동시성 대기 큐로 인한 생산성 저하가 오히려 더 심해진 것이다.

원인을 파고들어 보니 공유 자원 오염이 문제였다. 테스트 케이스가 develop 브랜치 하나만을 공유 자원으로 두고 많은 개발자가 함께 사용하다 보니, 머지 순서에 따라 — 혹은 머지와 함께 테스트 케이스를 수정한 경우 — 대기 큐에서 기다리던 다른 사용자의 테스트가 오염되었다. 수 시간을 기다렸는데, 정작 자기가 개발한 코드의 문제가 아닌 이유로 실패하는 일이 벌어진 것이다. 사용자 불편이 급증했다.

회피 전략 2 — PR별 테스트 케이스 브랜치 분리

후속 조치로, PR을 생성할 때 테스트 케이스도 함께 분기하도록 했다. 테스트 파이프라인마다 독립적인 테스트 케이스 브랜치를 갖게 해, 다른 PR의 영향을 받지 않도록 분리한 것이다.

이 조치로 대기 큐 문제 자체가 사라지지는 않았다. 하지만 공유 자원이던 테스트 케이스가 각각 독립 상태를 갖게 되면서, 다른 사용자에 의한 오염 현상은 사라졌다. 이전에는 "누가 파이프라인을 오염시켰는가"를 찾는 데 시간을 썼다면, 이제는 그 문제가 없어져 개발자가 자기 PR에 더 집중할 수 있게 되었다.

리그레션의 노이지 네이버 — retry 로직 재설계

그림 8. retry 로직을 '즉시 같은 자리에서 반복'에서 '재시도 큐'로 재설계했다. 실패 횟수가 약 80% 감소했다.

여기까지 CI 테스트는 사용자 불편이 줄고 그럭저럭 안정적인 형태가 되었다. 그러나 리그레션 테스트에는 여전히 노이지 네이버 문제가 남아 있었고, 품질보증팀의 업무량 — 실패 원인을 파악해야 하는 대상 — 은 아직 줄지 않았다. 이를 해결하기 위한 세 번째 조치로, 프레임워크의 retry(재시도) 기능을 재설계했다.

재설계 전에는, 테스트가 실패하면 그 즉시 같은 인스턴스에서 설정된 횟수만큼 루프를 돌며 재수행했다. 문제는 옆 파드의 부하(노이지 네이버)가 그대로인 상태에서 다시 돌리니 실패가 반복되기 쉬웠다는 점이다.

재설계 후에는 실패 케이스를 retry 큐에 담아두고, 한 사이클(전체 케이스 수행)이 끝난 뒤에 실패 케이스만 다시 분배해 재수행하도록 했다. 비교적 한가해진, 즉 조용한 상태에서 다시 돌려 노이지 네이버 문제를 회피하는 방식이다. 이 변경으로 실패 횟수가 약 80% 감소(35회 → 7회)했다.

지금까지의 결과

글 초반에 세웠던 목적 — "원인을 찾기 어려운 통합 빌드의 테스트 실패를, 머지 이전 CI 단계에서 미리 발견한다" — 가 상당 부분 달성되었다.

머지 이전 CI 단계에서 Shell 테스트 카테고리(테스트 자산의 절반가량)를 미리 수행해 문제를 조기에 발견하게 되었고, 스펙에 따른 기대값(답지) 변경과 테스트를 통과한 소스 코드만 머지되는 흐름이 만들어졌다. 또한 리그레션 테스트에서도 retry 로직 재설계로 노이지 네이버 문제를 완화하면서, 테스트 실패율이 의미 있게 줄어들었다.

남은 과제

아직 할 일이 남아 있다. 다음 편에서 다룰 예정이며, 완성되는 대로 연재하겠다.

테스트 워커 확장 — 테스트에 관여하는 워커 수를 늘리기 (AS-IS 50개 → To-Be 50개 이상)
CI 테스트 카테고리 확장 — CI 단계에 좀 더 많은 테스트가 수행될 수 있도록, 테스트 카테고리를 추가 편입
수행 대상 필터링 — 매번 전체를 돌리지 않고, 실패한 케이스만 타겟팅해 수행
하위 버전 백포트 — 카테고리가 확장된 CI를 하위 버전에도 적용해, 통합 테스트 이전 단계에서 엔진 소스 코드의 신뢰도를 더욱 높이기

마치며 — 머지 이전 검증으로 코드 안정성을 끌어올리다

들어가며에서 이야기했듯, 우리 팀의 업무 시간을 가장 크게 잡아먹던 일은 "어떤 커밋이 리그레션 테스트 실패를 유발했는가"를 찾아내는 일이었다. 통합 빌드 안에 여러 커밋이 섞여 있어 원인을 짚기 어렵고, 짚었다 하더라도 증명하기는 더 어려운 작업이었다.

이번에 다룬 일련의 개선 — Shell 테스트 카테고리를 머지 이전 CI 단계로 당기고, RAM 디스크로 디스크 병목을 회피하고, PR별 테스트 케이스 브랜치 분리로 공유 자원 오염을 끊고, retry 로직 재설계로 노이지 네이버 영향을 줄인 것 — 으로 그 문제를 상당 부분 해결했다. 원인 커밋을 찾아 떠도는 시간이 줄었고, 품질보증팀이 마주해야 했던 실패 케이스의 양도 함께 줄었다.

다만 가장 큰 변화는 코드의 안정성에 있다. 이전에는 머지된 다음에야 실패가 드러나는 일이 적지 않았지만, 이제는 머지하기 전에 테스트가 먼저 돌고 통과한 코드만 develop 브랜치에 들어온다. "머지되는 코드는 이미 한 번 검증된 코드"라는 작은 전제가 팀의 기본값이 되었고, 이 전제 덕분에 이후의 모든 작업 — 리뷰, 회귀 검증, 릴리스 준비 — 이 한 단계씩 더 단단해졌다.

남은 과제(테스트 워커 확장, CI 카테고리 추가 편입, 수행 대상 필터링, 하위 버전 백포트)가 이어지면 이 흐름은 더 안정적으로 자리 잡을 것이다.

— 다음 편에서는 '테스트 워커 확장', 'CI 카테고리 추가 편입', '수행 대상 필터링', '하위 버전 백포트'를 다룹니다.

CUBRID 장애 보고서 작성법 : Broker Log와 Server Log로 원인, 영향, 조치를 정리하기

큐브리드_김주현 — Thu, 28 May 2026 19:12:28 +0900

CUBRID 운영 노트 장애 보고서 CUBRID 11.4 기준

CUBRID 장애 보고서 작성법:
Broker Log와 Server Log로 원인, 영향, 조치를 정리하기

장애를 복구하는 것과 장애를 설명하는 것은 다른 작업이다. Broker SQL Log, Server Log, Broker 상태를 근거로 원인·영향·조치·재발 방지를 하나의 타임라인으로 연결하는 CUBRID 장애 보고서 작성법을 정리한다.

장애 보고서가 필요한 이유
CUBRID 장애 보고서의 기본 구조
장애 개요 작성법
발생 시간 — 타임라인으로 작성하기
영향 범위 — 서비스 지표와 DB 지표 연결하기
최초 감지 지표 작성법
Broker 상태 작성법
DB Server 상태 작성법
원인 SQL 작성법
조치 내용 작성법
재발 방지 대책 작성법
실무 예시: 조건절 누락 대량 UPDATE 장애 보고서
자주 하는 실수
장애 보고서 템플릿
핵심 정리

1. 장애 보고서가 필요한 이유

장애 대응에서 중요한 것은 장애를 복구하는 것만이 아니다. 장애가 끝난 뒤에는 반드시 다음 질문에 답할 수 있어야 한다.

무슨 장애였는가

장애명, 유형, 영향 서비스, 데이터 영향 여부

언제 발생·복구되었는가

시작 시각, 복구 시각, 지속 시간 — 분 단위 기록

원인과 근거는 무엇인가

Broker SQL Log, Server Log, Broker 상태를 근거로 판단한 원인

재발 방지는 어떻게 할 것인가

담당자, 완료 기한, 실행 항목으로 구체화된 대책

핵심 메시지

좋은 장애 보고서는 로그를 많이 모은 문서가 아니라, 로그를 근거로 장애 흐름을 설명하는 문서다.

장애 보고서가 없으면 같은 장애가 반복되고, 재발 방지 대책이 실행되지 않으며, 운영팀 내부 지식이 쌓이지 않는다.

2. CUBRID 장애 보고서의 기본 구조

보고서는 기술 담당자만 보는 문서가 아니다. 팀장, 서비스 담당자, 고객사도 볼 수 있다. 두 층으로 나눠 작성한다.

상단 — 요약

비기술 담당자도 이해할 수 있는 장애 개요, 영향, 조치 요약

하단 — 상세 근거

DBA와 개발자가 검증할 수 있는 Broker 상태, SQL Log, Server Log 근거

#	섹션	핵심 내용
1	장애 개요	장애명, 발생/복구 시간, 유형, 원인 요약, 조치 요약
2	발생 시간 / 타임라인	분 단위 이상, 가능하면 초 단위로 기록
3	영향 범위	영향 서비스, API, 사용자, 응답 시간, 데이터 정합성
4	최초 감지 지표	알람, WAS 로그, DB 지표 최초 이상 발생
5	Broker 상태	JQ, LONG-Q, ERR-Q, BUSY CAS, CLIENT_WAIT
6	DB Server 상태	기동 여부, Server Log, Disk, Lock 관련 메시지
7	원인 SQL 또는 원인 작업	Client IP, CAS ID, execute time, 영향 테이블
8	조치 내용	시간 순서, 조치 후 지표 변화
9	복구 확인	복구 판단 기준과 확인 지표
10	재발 방지 대책	담당자, 완료 기한, 실행 항목
11	첨부 로그	Broker status, SQL Log, Server Log, WAS 로그

3. 장애 개요 작성법

장애 개요는 보고서의 첫 화면에서 읽혀야 한다. 상세 로그는 뒤에 두고, 첫 페이지에는 원인과 영향, 조치를 간결하게 작성한다.

장애 개요 예시

장애명:    주문 API 응답 지연 장애
발생 시간: 2026-05-13 14:03
복구 시간: 2026-05-13 14:22
지속 시간: 약 19분
장애 유형: DB SQL 지연 및 CAS 점유 증가

원인 요약:
  배치 SQL의 WHERE 조건절 누락으로 order_history 테이블에 대한 대량 UPDATE가 발생했다. 이로 인해 Archive Log 증가,Lock 대기, CAS BUSY 증가가 발생했다.

조치 요약:
  배치 작업을 중단하고 Lock 대기 세션을 정리한 뒤,
  백업 테이블 기준으로 일부 데이터 보정을 수행했다.

4. 발생 시간 — 타임라인으로 작성하기

장애 시간은 단순히 "14시경"이라고 쓰면 안 된다. 분 단위, 가능하면 초 또는 분 단위로 작성하고 반드시 타임라인으로 정리한다.

나쁜 예

오후 2시쯤 장애 발생

좋은 예

2026-05-13 14:03:12 주문 API 응답 시간 증가 알람 발생

14:03

주문 API 응답 시간 증가 알람 발생

14:04

WAS 로그에서 /api/orders/history API timeout 증가 확인

14:05

cubrid broker status -b 확인 → JQ 증가, LONG-Q 증가 확인

14:06

cubrid broker status -f broker1 확인 → CAS 12개 중 10개 BUSY

14:08

Broker SQL Log에서 order_history 대량 UPDATE SQL 반복 확인

14:10

배치 담당자에게 배치 중단 요청

14:12

배치 프로세스 중단

14:15

Lock 대기 세션 정리

14:18

주문 API 응답 시간 회복 확인 (18초 → 1.5초)

14:22

Broker JQ 정상화 및 장애 복구 판단

시간 작성 시 주의

복구 시간은 조치 완료 시간이 아니라 서비스 지표 정상화 시간을 기준으로 잡는다. DB 서버 시간과 WAS 서버 시간의 NTP 동기화 여부를 먼저 확인한다.

5. 영향 범위 — 서비스 지표와 DB 지표 연결하기

장애 보고서는 DB 지표만 쓰면 부족하다. DB 지표와 서비스 지표를 연결해서 작성해야 한다.

영향 범위 예시

영향 서비스: 주문 서비스
영향 API:    GET /api/orders/history
             GET /api/orders/{orderId}
영향 시간:   2026-05-13 14:03 ~ 14:22
사용자 영향: 주문 이력 조회 지연 및 일부 timeout 발생
응답 시간:   평균 1.2초 → 최대 18초
오류 현상:   HTTP 504 timeout 일부 발생
데이터 영향: 일부 주문 이력 상태값이 잘못 변경되어 백업 테이블 기준으로 보정 수행

DB 지표와 서비스 지표를 연결하는 문장 예시:

연결 문장 예시

14:03 이후 Broker JQ와 LONG-Q가 증가했고, 동일 시간대 주문 API 평균 응답 시간이 1.2초에서 18초로 증가했다. Broker SQL Log에서 주문 이력 테이블 대량 UPDATE SQL이 반복 수행된 것이 확인되었다.

6. 최초 감지 지표 작성법

"누가 먼저 알았는가"보다 "어떤 지표가 먼저 이상을 보였는가"가 중요하다.

최초 감지 예시

감지 시간:   2026-05-13 14:03
감지 경로:   APM 응답 시간 알람
알람 내용:   주문 API 평균 응답 시간 1.2초 → 18초 증가

DB 측 최초 확인 지표:
  - Broker JQ 증가
  - LONG-Q 증가
  - BUSY CAS 증가

CUBRID 측 확인 명령어

cubrid broker status -b
cubrid broker status -b -s 1
cubrid broker status -f broker1
cubrid server status
df -h
tail -100 $CUBRID/log/broker/error_log/*
tail -100 $CUBRID/log/server/*

7. Broker 상태 작성법

Broker 상태는 API 장애와 DB 처리 지연을 연결하는 핵심 근거다. 원인을 확정하는 지표가 아니라 원인 영역을 좁히는 지표임을 기억한다.

cubrid broker status -b (브로커의 상태정보 출력)
cubrid broker status -b -s 1(1초 단위로 상태정보를 갱신하면서 출력)
cubrid broker status -f broker1 (브로커가 접속한 DB 및 호스트 정보를 출력)

지표	의미	보고서 해석
`JQ` 증가	요청 대기	CAS 부족 또는 SQL 지연 가능성
`LONG-Q` 증가	느린 SQL 증가	원인 SQL 확인 필요 → Broker SQL Log 확인
`ERR-Q` 증가	오류 SQL 증가	SQL 오류 또는 접속 오류 확인
`BUSY CAS` 증가	CAS 점유 증가	장시간 SQL, Lock Wait, 배치 영향
`CLIENT_WAIT` 증가	클라이언트 대기	애플리케이션 connection 반환 문제 확인
`#REJECT` 증가	접속 거부	access control 또는 Broker 설정 확인

Broker 상태 보고서 예시

확인 시간: 2026-05-13 14:06
Broker:    broker1

상태 요약:
  AS: 12  JQ: 8  LONG-Q: 24  ERR-Q: 0  #REJECT: 0

CAS 상태:
  전체: 12  BUSY: 10  IDLE: 1  CLIENT_WAIT: 1

판단:
  Broker는 기동 중이나 대부분의 CAS가 BUSY 상태였다.
  JQ와 LONG-Q가 함께 증가했으므로 신규 요청 대기와
  장시간 SQL이 동시에 발생한 상태로 판단된다.

8. DB Server 상태 작성법

DB Server 상태는 Broker 상태와 분리해서 작성한다. Lock Wait이나 Deadlock 의심 장애에서는 Server Log 확인 결과를 반드시 포함한다.

CUBRID에서 교착 상태 관련 잠금 정보는 서버 오류 로그에 기록된다. 서버 오류 로그 파일은 $CUBRID/log/server 디렉터리에 저장된다.

cubrid server status 
ps -ef | grep cub_server
tail -100 $CUBRID/log/server/*
df -h

DB Server 상태 보고서 예시

확인 시간: 2026-05-13 14:06
DB_NAME:   orderdb

상태:
  DB Server 기동 중
  cub_server 프로세스 확인됨

Server Log:
  DB Server 비정상 종료 없음
  장애 시간대 Lock 대기 관련 메시지 일부 확인

Disk:
  Log 경로 사용률 82%
  Archive Log 증가 확인

판단:
  DB Server 자체 중단은 발생하지 않았다.
  장애 시간대 Lock 대기와 Archive Log 증가가 확인되어
  대량 UPDATE 작업의 영향으로 판단된다.

나쁜 예

Server Log 500줄 전체 첨부

좋은 예

장애 시간대 14:03~14:12 사이 Server Log에서 Deadlock 관련 메시지 3건이 확인되었다. 로그 원문은 부록에 첨부한다.

9. 원인 SQL 작성법

CAS마다 하나의 SQL 로그 파일이 생성된다. CUBRID JDBC 드라이버는 CUBRIDConnection.toString()으로 CAS ID와 Process ID를 포함한 연결 정보를 출력할 수 있다. CAS ID를 확인하면 해당 CAS의 SQL 로그 파일을 바로 찾을 수 있다.

# 장애 시간대 SQL 추출
grep -E "14:03|14:04|14:05|14:06|14:07|14:08|14:09|14:10|14:11|14:12" \
  broker1_*.sql.log > /tmp/incident_sql.log

# 특정 테이블 기준
grep -i "order_history" broker1_*.sql.log

# 특정 CAS 기준 (CAS ID 3인 경우)
grep -i "order_history" broker1_3.sql.log

원인 SQL 보고서 예시

발생 시간: 2026-05-13 14:03 이후 반복
SQL 유형:  대량 UPDATE
대상 테이블: order_history
Client IP: 10.10.20.51 (배치 서버)
CAS ID:    3

원인:
  order_history 테이블에 대해 WHERE 조건절이 누락된
  UPDATE SQL이 실행됨

근거:
  - Broker SQL Log: 14:03 이후 order_history UPDATE SQL 반복
  - Broker 상태: LONG-Q 24, BUSY CAS 10
  - Server Log: Lock 대기 메시지 확인

나쁜 예

느린 SQL이 있었다.

좋은 예

14:03부터 10.10.20.51 배치 서버가 CAS 3에서 order_history UPDATE SQL을 반복 수행했고, execute time이 120초 이상 지속되었다.

SQL 원문 작성 시 주의

개인정보나 민감 정보가 포함된 SQL 원문은 마스킹하거나 "별도 보안 첨부로 보관한다"고 명시한다. 보고서에는 테이블명, SQL 유형, 조건절 누락 사실만 기록해도 된다.

10. 조치 내용 작성법

"무엇을 했다"보다 "언제 무엇을 왜 했으며, 어떤 지표가 변화했는가"를 함께 쓴다.

시간	조치	담당자	결과
14:10	배치 담당자에게 배치 중단 요청	DBA	중단 요청 완료
14:12	배치 프로세스 중단	배치 담당자	프로세스 종료 확인
14:15	Lock 대기 세션 정리	DBA	CAS BUSY 감소 시작
14:18	API 응답 시간 회복 확인	DBA/개발	18초 → 1.5초 감소
14:20	백업 테이블 기준 변경 데이터 확인	DBA	보정 대상 확인 완료
14:22	Broker JQ 정상화 확인 후 복구 판단	DBA	장애 복구 완료

나쁜 예

배치를 중단해서 정상화됨

좋은 예

14:12 배치 프로세스 중단 후 14:18부터 주문 API 평균 응답 시간이 18초에서 1.5초 수준으로 감소했다. 14:22 Broker JQ가 0으로 유지되고 BUSY CAS가 정상 수준으로 감소하여 복구로 판단했다.

11. 재발 방지 대책 작성법

나쁜 예

향후 배치 SQL 작성 시 주의

좋은 예

배치 실행 전 대상 건수 검증 SQL을 필수로 수행하고, 검증 결과를 작업 승인 문서에 첨부한다.

재발 방지 항목	담당자	완료 예정일	상태
배치 SQL 실행 전 SELECT COUNT 검증 필수화	DBA	2026-05-20	진행
Broker JQ / LONG-Q 알림 추가	운영팀	2026-05-22	예정
대량 DML 체크리스트 배포	DBA	2026-05-24	예정
배치 SQL 리뷰 프로세스 적용	개발팀	2026-05-30	예정

운영 팁

재발 방지 대책은 담당자와 완료일이 없으면 실행되지 않는다. 보고서에는 반드시 담당자, 기한, 확인 방법을 넣는다.

12. 실무 예시: 조건절 누락 대량 UPDATE 장애 보고서

CUBRID 장애 보고서 — 완성 예시

# CUBRID 장애 보고서

## 1. 장애 개요

장애명:    주문 API 응답 지연 장애
발생 시간: 2026-05-13 14:03
복구 시간: 2026-05-13 14:22
지속 시간: 약 19분
장애 유형: 대량 UPDATE로 인한 DB 응답 지연

최종 원인:
  배치 SQL의 WHERE 조건절 누락으로 order_history 테이블에
  대한 대량 UPDATE가 발생했다. Archive Log 증가, Lock 대기,
  CAS BUSY 증가로 인해 주문 API 응답 시간이 증가했다.

## 2. 영향 범위

영향 API:    GET /api/orders/history
영향 시간:   14:03 ~ 14:22
응답 시간:   평균 1.2초 → 최대 18초
오류 현상:   HTTP 504 timeout 일부 발생
데이터 영향: 일부 상태값 잘못 변경 → 백업 테이블 기준 보정

## 3. Broker 상태 (14:06 기준)

AS: 12  JQ: 8  LONG-Q: 24  ERR-Q: 0
BUSY: 10  IDLE: 1  CLIENT_WAIT: 1

판단:
  JQ + LONG-Q 동시 증가 → 신규 요청 대기 + 장시간 SQL 병존

## 4. DB Server 상태 (14:06 기준)

DB Server: 기동 중 (비정상 종료 없음)
Server Log: Lock 대기 관련 메시지 확인
Disk:      Log 경로 82%

## 5. 원인 SQL

UPDATE order_history SET order_status = 'CANCEL'
WHERE /* 조건절 누락 */;

근거:
  - Broker SQL Log: 14:03 이후 반복 확인
  - Client IP: 10.10.20.51 (배치 서버)
  - CAS ID: 3, execute time: 120초 이상

## 6. 조치 내용

14:12 배치 프로세스 중단
14:15 Lock 대기 세션 정리
14:18 API 응답 시간 18초 → 1.5초 감소 확인
14:22 Broker JQ 0 유지, 복구 판단

## 7. 재발 방지

- 배치 SQL 실행 전 SELECT COUNT 검증 필수화
- 대량 UPDATE/DELETE 전 백업 테이블 생성 의무화
- Broker JQ, LONG-Q 알림 추가
- 배치 작업 중단 기준 문서화

13. 자주 하는 실수

로그 원문만 붙여 넣음

로그는 많지만 원인 설명이 없다. 로그를 근거로 원인과 영향을 해석해야 한다.

원인과 증상 구분 안 함

"응답 지연"은 원인이 아니라 증상이다. "조건절 누락 대량 UPDATE로 인한 CAS 점유 및 Lock 대기"가 원인이다.

복구 시간 = 조치 완료 시간

배치 중단 시각이 복구 시각이 아니다. API 응답 시간과 Broker 지표가 정상화된 시각이 복구 시각이다.

재발 방지가 추상적

"향후 주의"는 재발 방지가 아니다. 담당자, 기한, 실행 항목을 명시한다.

담당자와 완료일 없음

재발 방지 대책에 담당자와 완료 기한이 없으면 실행되지 않는다.

타임라인이 부정확

원인 분석이 맞아도 타임라인이 틀리면 보고서 신뢰도가 떨어진다. 분 단위로 정확히 기록한다.

14. 장애 보고서 템플릿

CUBRID 장애 보고서 템플릿 (복사해서 사용)

# CUBRID 장애 보고서

## 1. 장애 개요

장애명:
발생 시간:
복구 시간:
지속 시간:
대상 DB:
대상 Broker:
영향 서비스:
장애 유형:
최종 원인:
최종 조치:

## 2. 장애 타임라인

HH:MM  [내용]
HH:MM  [내용]
HH:MM  [내용]

## 3. 영향 범위

영향 서비스:
영향 API:
영향 시간:
사용자 영향:
응답 시간 변화:
오류 건수:
데이터 영향:

## 4. 최초 감지 지표

감지 시간:
감지 경로:
DB 측 최초 확인:
  - JQ:
  - LONG-Q:
  - BUSY CAS:

## 5. Broker 상태

확인 명령: cubrid broker status -b / -b -s 1 / -f 

AS:  JQ:  LONG-Q:  ERR-Q:  #REJECT:
BUSY CAS:  IDLE:  CLIENT_WAIT:  CLOSE_WAIT:

판단:

## 6. DB Server 상태

확인 명령: cubrid server status / tail $CUBRID/log/server/*

DB Server 상태:
Server Log 특이사항:
Disk 사용률:
Archive Log 증가 여부:

판단:

## 7. 원인 SQL 또는 원인 작업

SQL 유형:
대상 테이블:
실행 주체:
Client IP:
CAS ID:
수행 시간:

SQL 요약:

근거:
  - Broker SQL Log:
  - Broker 상태:
  - Server Log:
  - 애플리케이션 로그:

## 8. 조치 내용

시간 | 조치 | 담당자 | 결과
-----|------|--------|------
     |      |        |

## 9. 복구 확인

복구 시간:
판단 기준:
확인 항목:
  - API 응답 시간 정상화
  - Broker JQ 정상화
  - LONG-Q 추가 증가 없음
  - BUSY CAS 정상화
  - DB Server 정상
  - Error Log 신규 오류 없음
  - 데이터 정합성 확인

## 10. 재발 방지 대책

항목 | 담당자 | 완료 예정일 | 상태
-----|--------|------------|------
     |        |            |

## 11. 첨부 자료

- Broker status 결과
- Broker SQL Log
- Broker Error Log
- DB Server Log
- WAS 로그
- OS 지표
- 조치 SQL
- 보정 SQL

꼭 작성자가 제시한 양식을 사용할 필요는 없다. 업무, 시스템성격, 보안 등에 따라 기입하지 못하는 항목이 있을 수 있다. 그러므로 예제를 참고하여 본인들이 담당하는 시스템을 점검하는 양식을 작성하는 방법을 고민해 보았으면 한다.

15. 핵심 정리

핵심 메시지 1

CUBRID 장애 보고서는 Broker Log, Server Log, SQL Log를 근거로 장애 원인과 서비스 영향을 설명하는 문서다.

핵심 메시지 2

장애 원인은 기술적으로 쓰고, 장애 영향은 서비스 관점으로 써야 한다. 두 관점이 하나의 타임라인으로 연결되어야 한다.

핵심 메시지 3

복구 시간은 조치 완료 시간이 아니라 서비스 지표 정상화 시간이다. 재발 방지 대책은 담당자와 완료 기한이 없으면 실행되지 않는다.

핵심 메시지 4

좋은 장애 보고서는 다음 장애 대응 Runbook의 재료가 된다. 장애 대응은 복구로 끝나지 않는다.

보고서는 다음 질문에 답해야 한다.

→ 언제 발생했는가?
→ 무엇이 영향을 받았는가?
→ 어떤 로그를 근거로 판단했는가?
→ 원인 SQL 또는 원인 작업은 무엇인가?
→ 어떤 조치를 했으며, 조치 후 어떤 지표가 변화했는가?
→ 복구는 어떤 기준으로 판단했는가?
→ 같은 장애를 막기 위해 무엇을 언제까지 바꿀 것인가?

참고 자료

CUBRID 11.4 — 트러블슈팅 (CAS SQL Log, Server Log 확인) CUBRID 11.4 — Broker 상태 확인 (cubrid broker status) CUBRID 11.4 — JDBC 드라이버 (CAS INFO, logSlowQueries) CUBRID 11.4 운영 매뉴얼 목차

CUBRID EOL 대응 가이드 : 운영 DB 업그레이드 계획 수립하기

큐브리드_김주현 — Wed, 27 May 2026 13:12:00 +0900

CUBRID 운영 노트 EOL 대응 CUBRID 11.4 기준

CUBRID EOL 대응 가이드:
운영 DB 업그레이드 계획 수립하기

CUBRID Server는 GA 이후 기본 5년 지원을 제공하며, 규모가 큰 배포 버전은 3년 추가 연장이 결정될 수 있다. EOL 대응은 설치 파일 교체가 아니라, 드라이버 호환성·백업·성능 회귀·HA 검증을 모두 포함하는 변경관리 작업이다.

DB 업그레이드를 변경관리로 봐야 하는 이유
CUBRID EOL 정책 이해
EOL 대응이 필요한 이유
현재 버전 확인
업그레이드 대상 버전 선정
변경 영향 범위 분석
드라이버 호환성 확인
백업 및 Rollback 계획
SQL 호환성 · 성능 회귀 테스트
배치 SQL 별도 테스트
Broker CAS 재산정
HA 환경 업그레이드 점검
업그레이드 일정 수립
운영 반영 당일 Runbook
반영 후 안정화 모니터링
운영자가 자주 하는 실수
체크리스트
핵심 정리

1. DB 업그레이드를 변경관리로 봐야 하는 이유

CUBRID 운영 DB의 버전을 올린다는 것은 단순히 설치 파일을 교체하는 작업이 아니다. 다음 요소를 함께 변경하는 작업이다.

DB 레이어

DB Engine · Broker · cubrid.conf · cubrid_broker.conf · HA 구성

애플리케이션 레이어

JDBC Driver · CCI Driver · ODBC Driver · WAS connection pool 설정

운영 레이어

백업·복구 절차 · 배치 수행 시간 · 모니터링 기준 · 장애 대응 Runbook

성능 레이어

SQL 실행 계획 · 통계 정보 · 인덱스 처리 방식 · JOIN 방식 변경 가능성

핵심 메시지

DB 업그레이드는 설치 작업이 아니라 장애 가능성을 줄이는 변경관리 작업이다.

2. CUBRID EOL 정책 이해

CUBRID의 EOL(End of Life) 정책은 다음과 같다.

항목	내용
기본 지원 기간	GA 이후 기본 5년 동안 제품에 대한 안정적인 지원을 제공한다. 기능 추가와 개선, 버그 수정, 보안 패치, 핫픽스가 지원 범위에 포함된다.
연장 지원	많은 사이트에서 배포되어 사용되고 있는 버전은 EOL 기간을 3년 연장할 수 있다. 연장 여부는 매년 12월에 결정하여 공지한다.
EOL 이후	기능 개선, 버그, 보안 패치 및 핫픽스를 지원받을 수 없고 유지관리 서비스만 지원받을 수 있다.
유지관리 서비스	EOL과 상관없이 최종 사용자에게 제공된다.

EOL vs EOS 구분

EOL (End of Life) — 제품에 대한 개선(upgrade)/수정(patch, hotfix) 작업 종료
EOS (End of Service) — 제품에 대한 기술지원 서비스 종료

현재 운영 중인 버전의 EOL 상태는 CUBRID 공식 EOL 페이지에서 확인한다.

EOL 확인 시점

EOL 페이지 확인은 업그레이드 직전에만 하는 것이 아니다. 월간 DBA 점검 항목에 현재 운영 버전의 EOL 상태를 포함하는 것이 좋다.

3. EOL 대응이 필요한 이유

EOL이 지난 버전을 계속 운영하면 다음 문제가 발생할 수 있다.

보안

보안 패치 지원 범위에서 제외된다. 신규 취약점이 발견되어도 공식 패치를 받을 수 없다.

장애 대응

공식 지원 범위가 제한되어 장애 발생 시 기술지원을 받기 어려워질 수 있다.

호환성

신규 OS, 라이브러리, JDBC/CCI Driver의 최신 버전 사용이 제약될 수 있다.

운영 리스크

감사 또는 보안 점검에서 지적 대상이 될 수 있다. 운영 표준 미준수로 분류될 수 있다.

EOL 상태	판단	조치
지원 기간 충분	정기 점검	중장기 업그레이드 계획 수립
1년 이내 EOL	주의	업그레이드 계획 수립 시작
6개월 이내 EOL	경고	테스트 환경 구성 및 일정 확정
EOL 경과	위험	빠른 업그레이드 또는 지원 정책 확인

운영 원칙

EOL 대응은 장애가 발생한 뒤 시작하면 늦다. 지원 종료 예정일 최소 6개월 전에는 업그레이드 계획을 수립해야 한다.

4. 현재 버전 확인

업그레이드 계획 수립 전 현재 운영 환경을 정확히 파악한다.

# CUBRID 버전 확인
cubrid --version
cubrid (CUBRID utilities)
CUBRID 11.5.0 (11.5.0.2204-295db40) (64bit release build for Linux) (May 19 2026 18:11:40)

# 서비스 상태 전체 확인
cubrid service status
cubrid server status
cubrid broker status

기록할 정보

업그레이드 계획서에는 DB Engine 버전만 적으면 부족하다. JDBC Driver 버전, CCI Driver 버전, 운영 OS 버전, HA 구성 여부, 백업 방식까지 함께 기록해야 한다.

5. 업그레이드 대상 버전 선정

5.1 CUBRID 버전 표기 방식과 업그레이드 범위 이해

CUBRID DBMS는 Major 버전 · Minor 버전 · Patch 버전으로 표기한다. 버전 범위에 따라 업그레이드 복잡도가 크게 달라진다.

변경 범위	예시	DB 볼륨 호환	권고 사항
Patch만 다름	11.4.0 → 11.4.1	호환됨	가능하면 최신 Patch로 업그레이드 권고
Minor가 다름	11.3 → 11.4	미호환	데이터 이관(CMT 또는 unloaddb/loaddb) 필요
Major가 다름	10.x → 11.x	미호환	데이터 이관 필수. 고려사항 대폭 증가

Patch 버전 업그레이드 권고

Patch만 다른 경우에는 DB 볼륨이 호환되므로 가능하면 최신 Patch 버전으로 업그레이드할 것을 권고한다. Patch 업그레이드는 상대적으로 간단하며, 버그 수정·보안 패치 혜택을 받을 수 있다.

Major · Minor 업그레이드 주의

Major 또는 Minor 버전이 다른 경우에는 DB 볼륨이 호환되지 않아 데이터 이관(CMT 또는 unloaddb/loaddb)이 필요하다. 이관 작업은 서비스 중단 시간, 데이터 검증, 드라이버 호환성, HA 구성 변경 등 고려사항이 대폭 늘어나므로 충분한 사전 준비가 필요하다.

5.2 대상 버전 선정 기준

대상 버전 선정 기준은 다음과 같다.

→ 현재 운영 버전에서 직접 업그레이드 가능한가?
→ 애플리케이션 Driver가 호환되는가?
→ 운영 OS에서 지원되는가?
→ HA 환경 업그레이드 절차가 명확한가?
→ 기존 SQL 호환성 이슈가 없는가?

CUBRID 11.4는 2025년 1월 출시되었으며, PL/CSQL 지원, 대용량 처리를 위한 Hash Join 추가, 옵티마이저 및 인덱스 처리 성능 개선, redo recovery 병렬 처리가 주요 변경사항이다. 최신 Patch 버전은 CUBRID Release 페이지에서 확인한다.

Major · Minor 업그레이드 시 — 매뉴얼 DB 볼륨 호환 확인 필수

Major 또는 Minor까지 버전을 올리는 경우 DB 볼륨 호환 여부를 반드시 CUBRID 매뉴얼에서 확인한 후 대상 버전을 선정해야 한다. 호환되지 않는 볼륨을 그대로 사용하면 DB 기동 실패 또는 데이터 손상이 발생할 수 있다.

6. 변경 영향 범위 분석

업그레이드는 DB 서버만 바꾸는 작업이 아니다. 다음 대상 전체의 영향 범위를 먼저 정리해야 한다.

구분	영향 여부	확인 내용
DB Engine	있음	데이터베이스 업그레이드 절차
Broker	있음	broker 설정 호환성
JDBC Driver	있음	WAS / 배치 서버 교체 필요
CCI / ODBC Driver	확인 필요	사용 시스템 파악 후 결정
HA	있음	Failover 리허설 필요
백업 스크립트	있음	backupdb / restoredb 테스트
모니터링 스크립트	확인 필요	명령어 출력 형식 변경 여부
SQL	있음	호환성 및 실행 계획 검증

주의

업그레이드 영향 범위에 애플리케이션 Driver가 빠지면 운영 반영 당일 문제가 생긴다. DB 서버와 Driver는 하나의 변경 묶음으로 관리한다.

7. 드라이버 호환성 확인

CUBRID 업그레이드에서 자주 놓치는 것이 JDBC Driver다. DB Server만 올리고 애플리케이션 Driver를 그대로 두면 접속 오류, SQL 실행 오류, Connection pool 동작 차이 등이 발생할 수 있다.

# 전체 서버에서 JDBC Driver 파일 경로 검색
find /home -name "*cubrid*.jar"
find /app -name "*cubrid*.jar"
find /was -name "*cubrid*.jar"
find /batch -name "*cubrid*.jar"

실무 팁

JDBC Driver는 한 곳에만 있는 것처럼 보여도 실제로는 여러 애플리케이션에 중복 포함되어 있는 경우가 많다. 업그레이드 전 find 명령으로 전체 경로를 확인한다.

Driver 교체 체크리스트

운영 WAS에 포함된 JDBC Driver 경로 전수 확인

배치 서버 JDBC Driver 경로 확인

공통 lib와 애플리케이션 lib 중복 여부 확인

새 Driver로 개발계 접속 테스트

Connection pool 정상 동작 확인

AutoCommit / Timeout 설정 확인

8. 백업 및 Rollback 계획

8.1 업그레이드 전 백업

운영 DB 업그레이드 전에는 반드시 복구 가능한 Full Backup을 확보해야 한다.

# Full Backup 수행
cubrid backupdb -C -D /backup/cubrid 

# 백업 목록 확인
cubrid restoredb --list

8.2 Rollback 기준을 사전에 정한다

Rollback 판단 기준 예시는 다음과 같다.

→ DB Server 기동 실패
→ Broker 기동 실패
→ 애플리케이션 접속 실패
→ 핵심 API 장애 또는 성능 회귀 기준 초과
→ 핵심 배치 실패
→ HA Failover 실패
→ 데이터 정합성 검증 실패

원칙

Rollback 계획이 없는 업그레이드는 운영 반영하면 안 된다. 업그레이드 성공 절차보다 실패했을 때 되돌리는 절차가 더 중요하다.

복구 리허설 필수

백업만 수행하고 복구 테스트를 하지 않으면 의미가 없다. 운영 반영 전 테스트 서버에서 restoredb 리허설을 반드시 수행한다.

9. SQL 호환성 · 성능 회귀 테스트

9.1 SQL 호환성 테스트

버전 업그레이드 후 일부 SQL은 실행 계획이 달라질 수 있다. 확인 대상은 다음과 같다.

주요 API SQL (로그인, 조회, 생성)
배치 SQL (정산, 통계, 로그 삭제)
날짜·문자열 함수 사용 SQL
페이징 SQL (LIMIT / OFFSET)
DBLink SQL
Stored Procedure / Function

9.2 성능 회귀 기준 설정

업그레이드 전 주요 SQL의 기준 성능을 먼저 확보하고 이후 비교한다.

항목	업그레이드 전	업그레이드 후	기준	판단
로그인 API	100ms	120ms	+30% 이내	통과
주문 조회 API	500ms	800ms	+30% 이내	확인 필요
주문 이력 API	700ms	3s	+30% 이내	실패
정산 배치	15분	18분	+30% 이내	통과

성능 테스트 기준

SQL 호환성 테스트는 성공/실패만 보면 부족하다. 결과가 같아도 수행 시간이 크게 늘면 운영 관점에서는 실패다. Broker JQ, LONG-Q, BUSY CAS까지 함께 확인한다.

10. 배치 SQL 별도 테스트

운영 장애는 온라인 API보다 배치에서 발생하는 경우가 많다. 온라인 API만 검증하고 배치를 놓치면 운영 반영 후 새벽에 장애가 발생할 수 있다.

배치명	기존 수행 시간	신규 수행 시간	처리 건수	판단
일 정산	10분	12분	100만	통과
월 정산	40분	90분	500만	실패 — 재검토
로그 삭제	20분	25분	1,000만	통과

배치 검증 항목은 수행 시간 외에도 다음을 확인한다.

→ COMMIT 단위 적정 여부
→ Archive Log 증가량
→ Temporary 공간 사용량
→ Broker CAS 점유 시간
→ Lock 영향 및 Error Log 발생 여부

11. Broker CAS 재산정

업그레이드 후 SQL 성능이 변하면 CAS 점유 시간도 변한다. 기존 Broker CAS 설정이 더 이상 적절하지 않을 수 있으므로 재산정이 필요하다.

WAS 서버 수4대
WAS당 connection pool max30
운영 여유 (Spike·장애 대응)+10
권장 MAX_NUM_APPL_SERVER = (4 × 30) + 10= 130

여유 CAS 확보 이유

피크 트래픽·장애 상황에서 일시적으로 connection이 증가할 수 있다. WAS 전체 최대 연결 수에 여유를 더한 값을 MAX_NUM_APPL_SERVER로 설정해야 JQ 증가 없이 안정적으로 운영할 수 있다.

문제 상황

WAS 전체 최대 연결 수가 Broker MAX_NUM_APPL_SERVER보다 크면 피크 시간대에 JQ 증가가 발생할 수 있다. MAX_NUM_APPL_SERVER 합과 max_clients를 함께 검토해야 한다.

# Broker 상태 확인
cubrid broker status -b -s 1
cubrid broker status -f

12. HA 환경 업그레이드 점검

HA 환경에서는 업그레이드 난이도가 더 높다. 다음 항목을 사전에 확인해야 한다.

HA 업그레이드 사전 체크리스트

현재 HA 상태 및 Master / Slave 역할 확인

Replication 지연 여부 확인

Full Backup 수행 및 복구 테스트

Failover 리허설 완료

애플리케이션 접속 전환 절차 확인

서비스 중단 가능 시간 확인

Rollback 절차 문서화 및 승인

원칙

HA 환경 업그레이드는 반드시 리허설이 필요하다. Failover 절차를 운영 반영 당일 처음 수행하면 안 된다.

13. 업그레이드 일정 수립

운영 반영일을 먼저 정한 뒤 역산해서 준비한다.

D-90

현재 버전 및 EOL 상태 확인. 업그레이드 필요 여부 판단

D-75

대상 버전 선정 (Patch 수준까지 확정)

D-60

개발계 업그레이드 → SQL 호환성 1차 확인

D-45

테스트계 업그레이드 → SQL 호환성 · 성능 회귀 테스트

D-21

배치 SQL 테스트 · 백업/복구 리허설 · HA Failover 리허설

D-7

변경 승인 완료. Rollback 계획 최종 확인

D-Day

운영 반영. Smoke Test 수행

D+7

안정화 모니터링 종료 후 완료 판단

일정 산정 기준

DB 업그레이드 일정은 설치 시간 기준으로 잡으면 안 된다. 테스트, 리허설, 승인, Rollback 검토 시간을 포함해서 잡아야 한다.

14. 운영 반영 당일 Runbook

반영 전 확인

변경 승인 완료 / 작업자 및 승인자 대기

Full Backup 완료 / restoredb --list 확인

기존 Driver 백업 / 신규 Driver 준비

설치 파일 checksum 확인

Rollback 기준 재확인

반영 중 작업 순서

서비스 중지 / 현재 상태 수집

CUBRID 서비스 중지 / 신규 버전 설치

DB 업그레이드 절차 수행

Broker 설정 확인 / DB Server 기동 / Broker 기동

Driver 교체 / 애플리케이션 기동

Smoke Test 수행 (로그인, 핵심 API, 핵심 배치)

# 반영 전 현재 상태 수집 예시
date
hostname
cubrid service status
cubrid broker status -b
df -h

15. 반영 후 안정화 모니터링

업그레이드 후 최소 1주일은 별도 안정화 기간으로 본다.

항목	업그레이드 전	업그레이드 후	판단
API 평균 응답	500ms	550ms	정상
Broker LONG-Q	0~2	0~1	정상
Broker JQ	0	0	정상
일 배치	20분	23분	정상
Archive Log/day	30GB	35GB	추이 확인
Backup 시간	40분	42분	정상

완료 판단 기준

업그레이드는 반영이 끝이 아니다. 최소 1주일 동안 Broker JQ, LONG-Q, ERR-Q, API 응답 시간, 배치 수행 시간, Backup 성공 여부가 안정적인지 확인해야 완료로 판단할 수 있다.

16. 운영자가 자주 하는 실수

DB만 업그레이드, Driver 누락

DB는 올렸지만 WAS의 JDBC Driver를 기존 버전 그대로 두어 접속 오류 발생. 전체 서버에서 Driver 경로를 검색하고 교체 계획에 포함한다.

백업은 했지만 복구 테스트 누락

업그레이드 실패 후 restore 과정에서 권한·경로·버전 문제 발생. 운영 반영 전 테스트 서버에서 restoredb 리허설을 수행한다.

SQL 결과만 보고 성능 미확인

SQL 결과는 같지만 수행 시간이 10배 증가하는 사례. 주요 SQL은 전후 수행 시간과 실행 계획을 비교한다.

배치 테스트 누락

온라인 API는 정상이나 새벽 배치가 실패하거나 지연되는 사례. 핵심 배치 SQL은 운영 반영 전 반드시 수행 시간을 비교한다.

Rollback 기준 없음

장애가 발생해도 계속 진행할지 되돌릴지 판단이 늦어짐. Rollback 조건과 최종 판단자를 사전에 정한다.

HA Failover 리허설 미실시

운영 반영 당일 Failover 절차를 처음 수행해 장애 확산. Failover 리허설은 운영 반영 전 반드시 완료해야 한다.

17. 체크리스트

사전 준비

현재 CUBRID 버전 및 EOL 상태 확인 (CUBRID EOL 페이지 기준)

업그레이드 대상 버전 Patch 수준까지 확정

영향 범위 전체 파악 (DB / Broker / Driver / 배치 / HA / 백업)

JDBC Driver 전체 서버 경로 검색

테스트

개발계 → 테스트계 → 스테이징 순으로 단계적 검증

SQL 호환성 테스트 (결과 + 수행 시간 비교)

성능 회귀 테스트 (+30% 기준 등 기준 사전 정의)

배치 SQL 별도 테스트

백업 / 복구 리허설

HA Failover 리허설

Broker CAS 재산정

운영 반영

변경 승인 완료 / Rollback 기준 및 담당자 확정

반영 전 Full Backup + restoredb --list 확인

Smoke Test 수행 (로그인 / 핵심 API / 핵심 배치)

반영 후 최소 1주일 안정화 모니터링

18. 핵심 정리

핵심 메시지 1

DB 업그레이드는 설치 작업이 아니라 장애 가능성을 줄이는 변경관리 작업이다.

핵심 메시지 2

CUBRID EOL 대응은 현재 버전 확인, 대상 버전 선정, Driver 호환성, 백업/복구, 성능 회귀 테스트를 모두 포함해야 한다.

핵심 메시지 3

업그레이드 성공의 기준은 DB가 기동되는 것이 아니라, 애플리케이션과 배치가 기존 수준으로 안정적으로 동작하는 것이다.

참고 자료

CUBRID EOL 정책 (cubrid.com) CUBRID EOL 정책 (cubrid.org) CUBRID Release 페이지 CUBRID 11.4 Release Notes CUBRID 11.4 매뉴얼 (설치 및 업그레이드) CUBRID Migration Toolkit

Testcontainers-cubrid로 CUBRID 통합 테스트 환경 구성하기

김동민 — Sun, 24 May 2026 16:38:01 +0900

🐳 Testcontainers × CUBRID

테스트 코드에서 바로 띄우는
CUBRID 통합 테스트 환경

로컬 DB 환경 차이, 외부 테스트 서버 관리, 테스트 후 정리 작업까지 통합 테스트를 번거롭게 만드는 요소를 Testcontainers와 CUBRID 공식 모듈로 단순하게 해결해봅니다.

0 CUBRID 통합 테스트 환경의 고민

CUBRID를 사용하는 프로젝트에서 통합 테스트를 작성할 때는 보통 로컬에 CUBRID를 띄워 두기 → 테스트 수행 → 테스트 후 정리의 과정을 반복합니다.

팀원마다 로컬 환경이 달라 "내 환경에선 됐는데"라는 문제가 생기기 쉽고, 외부 서버에 CUBRID를 띄우고 테스트한다고 해도 관리 포인트가 늘어납니다.

결국 테스트를 수행하는 과정 자체가 복잡해지고, 개발자의 테스트 피로도가 올라갑니다.

Testcontainers는 통합 테스트에 필요한 컨테이너의 기동과 정리를 코드 안에서 자동으로 처리해 주는 라이브러리로, 이를 이용하면 위와 같은 불편을 해결할 수 있습니다. 이에 발맞춰, 개발자들이 CUBRID를 더 쉽게 사용할 수 있도록 공식 Testcontainers 모듈인 testcontainers-cubrid를 배포했습니다.

testcontainers-cubrid는 CUBRID 컨테이너의 기동, 부팅 헬스체크, 데이터베이스·사용자 생성, JDBC URL 제공을 한 줄짜리 API로 자동화해 주는 모듈입니다.

이 글에서는 모듈을 사용해 격리된 CUBRID 인스턴스를 테스트 코드에서 직접 띄우고 사용하는 방법을 JUnit 5와 Spring Boot 예제로 함께 살펴봅니다.

1 사전 요구사항

JDK 8 이상 (Spring Boot 3.x 사용 시 JDK 17 이상)

Docker가 동작 가능한 로컬

Gradle 또는 Maven 기반 Java 프로젝트

2 의존성 추가

테스트 코드에서 CUBRID 컨테이너를 사용하기 위해 testcontainers-cubrid와 cubrid-jdbc를 추가합니다.

Gradle build.gradle

Source

dependencies {
    testImplementation 'org.cubrid:testcontainers-cubrid:0.1.0'
    testRuntimeOnly   'org.cubrid:cubrid-jdbc:11.3.2.0053'
}

Maven pom.xml

Source


    org.cubrid
    testcontainers-cubrid
    0.1.0
    test



    org.cubrid
    cubrid-jdbc
    11.3.2.0053
    test

💡 참고

testcontainers-cubrid가 org.testcontainers:jdbc 의존성을 가져오므로 Testcontainers 코어를 별도로 추가할 필요 없습니다.

3 CubridContainer로 통합 테스트 작성

CubridContainer 객체를 만들고 start()를 호출하면 Docker가 CUBRID 컨테이너를 띄우고, 부팅이 끝날 때까지 자동으로 대기한 뒤 JDBC 접속이 가능한 상태로 만들어 줍니다.

Source

class CubridIntegrationTest {

    @Test
    void selectOneFromCubrid() throws SQLException {
        try (CubridContainer cubrid = new CubridContainer("cubrid/cubrid:11.4")
                .withDatabaseName("sampledb")
                .withUsername("foo")
                .withPassword("bar")) {

            cubrid.start();

            try (Connection conn = DriverManager.getConnection(
                    cubrid.getJdbcUrl(), cubrid.getUsername(), cubrid.getPassword());
                 Statement stmt = conn.createStatement();
                 ResultSet rs = stmt.executeQuery("SELECT 1")) {

                assertTrue(rs.next());
                assertEquals(1, rs.getInt(1));
            }
        }
    }
}

./gradlew test (또는 mvn test)로 실행하면 다음과 같이 컨테이너가 자동으로 기동되고 테스트가 통과합니다.

Terminal

18:38:26.685 INFO  t.cubrid/cubrid:11.4 - Creating container for image: cubrid/cubrid:11.4
18:38:26.703 INFO  t.cubrid/cubrid:11.4 - Container cubrid/cubrid:11.4 is starting: 90a54edbacfc
18:38:26.824 INFO  t.cubrid/cubrid:11.4 - Waiting for database connection to become available at jdbc:cubrid:localhost:57962:sampledb::: using query 'SELECT 1'
18:38:32.919 INFO  t.cubrid/cubrid:11.4 - Container cubrid/cubrid:11.4 started in PT6.234003S
18:38:32.919 INFO  t.cubrid/cubrid:11.4 - Container is started (JDBC URL: jdbc:cubrid:localhost:57962:sampledb:::)

SampleTest > programmaticUsage() PASSED

BUILD SUCCESSFUL in 7s

🐳 알아두면 좋은 점

CUBRID 모듈 내 부팅 헬스체크 코드가 있어, DB가 부팅되기까지 대기하는 별도의 코드를 작성할 필요 없습니다.

try-with-resources 블록을 빠져나오는 순간 컨테이너가 종료·삭제됩니다. 별도 정리 코드가 필요 없습니다.

withDatabaseName, withUsername, withPassword를 생략하면 기본값 (testdb / testuser / testpass)이 사용됩니다.

실행할 CUBRID 버전을 바꾸고 싶다면 이미지 태그만 변경하면 됩니다.

Source

// 11.3 버전으로 실행
try (CubridContainer cubrid = new CubridContainer("cubrid/cubrid:11.3")
        .withDatabaseName("sampledb")
        .withUsername("foo")
        .withPassword("bar")) {
    // ... 이하 동일
}

4 JDBC URL로 더 간단하게 사용하기

컨테이너 객체를 직접 생성하지 않고, JDBC URL의 접두어만 jdbc:tc:cubrid:로 바꾸면 Testcontainers가 알아서 컨테이너를 띄워 줍니다.

Source

@Test
void usingJdbcUrl() throws SQLException {
    String url = "jdbc:tc:cubrid:11.4://localhost/sampledb";

    try (Connection conn = DriverManager.getConnection(url);
         Statement stmt = conn.createStatement();
         ResultSet rs = stmt.executeQuery("SELECT 1")) {

        assertTrue(rs.next());
        assertEquals(1, rs.getInt(1));
    }
}

URL이 jdbc:tc:cubrid:로 시작하면 Testcontainers JDBC 드라이버가 연결 요청을 가로채, 해당 버전의 CUBRID 컨테이너를 자동으로 띄우고 연결을 컨테이너로 라우팅합니다.

Terminal

18:39:14.319 DEBUG o.t.j.ContainerDatabaseDriver - Container not found in cache, creating new instance
18:39:14.798 INFO  t.cubrid/cubrid:11.4 - Creating container for image: cubrid/cubrid:11.4
18:39:14.815 INFO  t.cubrid/cubrid:11.4 - Container cubrid/cubrid:11.4 is starting: 523f75d9dc09
18:39:14.950 INFO  t.cubrid/cubrid:11.4 - Waiting for database connection to become available at jdbc:cubrid:localhost:58095:sampledb::: using query 'SELECT 1'
18:39:21.103 INFO  t.cubrid/cubrid:11.4 - Container cubrid/cubrid:11.4 started in PT6.305344S
18:39:21.104 INFO  t.cubrid/cubrid:11.4 - Container is started (JDBC URL: jdbc:cubrid:localhost:58095:sampledb:::)

SampleTest > jdbcUrlUsage() PASSED

BUILD SUCCESSFUL in 7s

5 Spring Boot 테스트에서 사용하기

Spring Boot 프로젝트라면 application-test.yml에서 다음과 같이 데이터소스 URL만 바꿔주면 됩니다.

Spring Boot application-test.yml

Source

spring:
  datasource:
    url: jdbc:tc:cubrid:11.4://localhost/sampledb
    username: foo
    password: bar
    driver-class-name: org.testcontainers.jdbc.ContainerDatabaseDriver

이 설정만으로 테스트 클래스에서 JdbcTemplate이나 EntityManager를 주입받아 바로 사용할 수 있습니다.

Source

@SpringBootTest
@ActiveProfiles("test")
class DataSourceIntegrationTest {

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Test
    void selectOneFromCubrid() {
        Integer result = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        assertThat(result).isEqualTo(1);
    }
}

애플리케이션 코드는 손대지 않고, 테스트 프로필에서만 컨테이너 기반 CUBRID를 쓰도록 전환할 수 있습니다. CI 환경에서도 Docker만 있다면 동일하게 작동합니다.

6 마치며

testcontainers-cubrid 모듈로 통합 테스트에서 CUBRID를 손쉽게 사용하는 방법을 살펴봤습니다.

통합 테스트를 작성할 때 "CUBRID 환경부터 어떻게 마련할지"를 고민하던 시간을 이 모듈이 조금이라도 덜어 줄 수 있다면 좋겠습니다.

몇 줄의 코드로 CUBRID를 띄우고, 테스트가 끝나면 자동으로 정리되는 환경에서 개발자가 본질적인 테스트 시나리오에 더 집중하실 수 있기를 바랍니다.

히스토그램 출시 임박 기념 칼럼: 바인드 피킹과 플랜 유효성 문제

정소희 — Thu, 21 May 2026 11:08:51 +0900

— “바인드 기반 선택도”는 얼마나 의미가 있을까요?

이제 큐브리드에도 히스토그램이 도입될 예정입니다. 히스토그램의 목적은 명확합니다. 데이터 분포를 더 정확히 모델링해서, 옵티마이저가 선택도(selectivity)와 카디널리티(cardinality)를 제대로 추정하도록 돕는 것입니다.

그런데 한 가지가 마음에 걸립니다. 히스토그램이 아무리 좋아도, 결국 많은 쿼리는 바인드 변수를 사용합니다. 기존의 값을 통해 이미 선택도를 계산하고 플랜을 만들었다고 하더라도, 새로 들어오는 바인드 값에 해 해당 플랜을 재사용해도 되는걸까요?

저희는 플랜 공유로 비용을 줄이고 싶지만, 바인드값에 따라 최적 실행 계획이 달라질 수 있다는 사실도 고려해야 합니다. 해당 문제를 “바인드 피킹(bind peeking)”이라고 하며, 이 글은 바인드 피킹이 만들어내는 플랜 유효성 문제를 정리하고, 새로운 시스템을 설계한다는 관점에서 어떤 방향이 실용적인지(특히 런타임 관측 없이) 생각을 정리해보려는 목적입니다.

바인드 피킹

구체적으로 바인드 피킹이라는 것은 무엇일까요?

저희는 플랜을 만들 때, 처음으로 들어온 값을 기준으로 그 값에 대해 선택도를 계산하고 플랜을 생성합니다. 그런데 처음으로 들어온 쿼리가 다음을 만족한다면 어떡할까요?

1. 데이터 분포가 스큐한 상황인데, 어떤 값이 희귀하고, 어떤 값은 흔한 경우

2. 선택도에 의해 유리한 플랜이 바뀌는 경우 (인덱스/ 풀스캔)

처음에 들어온 값과 근접한 값을 최대한 사용한다면 사용자 입장에서는 큰 불편을 느끼지 않을 수도 있습니다. 그러나, 다음의 예시와 같은 상황이 발생한다면 어떡할까요?

대부분의 컬럼은 99%가 ID=1 이고 1%만이 ID가 다른 값을 가지는 테이블 T (인덱스 존재)를 가정하여 봅시다.

SELECT *
FROM T
WHERE ID = 1;

다음과 같은 쿼리가 들어왔을 경우엔, ID가 1이므로 선택도가 매우 높고, 따라서 풀스캔 플랜을 생성할 것입니다. 그러나, ID가 다른 값에 대해서도 해당 플랜을 재사용 하는 상황에는 인덱스 스캔이 명백히 유리함에도 불구하고 풀스캔 플랜을 사용하게 됩니다. 해당 상황을 바인드 피킹이라고 부릅니다.

바인드 피킹의 시스템적 해결

해당 문제를 요약하면 이렇게도 볼 수 있습니다.

플랜을 캐시할 때 ‘SQL 텍스트’만을 키로 삼으면 부족합니다. 값이 바뀌면서 선택도가 달라질 수 있기 때문입니다.

그러나, 바인드 값 하나하나를 기준으로 매번 다른 실행 계획을 만들겠다는 접근은, 결국 바인드 파라미터의 장점인 플랜 공유를 포기하라는 말과 크게 다르지 않습니다.

플랜 공유와 바인드 피킹 문제를 둘다 해결하는 좋은 방법은 무엇일까요?

바로, 바인드 원시 값이 아니라 SELECTIVITY(ID) 를 플랜의 키로 사용하는 것입니다.

바인드값에 의해 영향을 많이 받는 쿼리를 대상으로, 추가적으로 SELECTIVITY를 사용하여, 플랜 캐시 키를 확장하는 것이죠.

어떤 쿼리를 대상으로 플랜 캐시 키를 확장해야 할까?

모든 쿼리를 대상으로 선택도에 따라 플랜을 확장하는 것은 큰 오버헤드를 불러일으킬 수 있습니다. 따라서, 대상이 될 쿼리를 구분하는 것이 그 무엇보다 중요합니다.

오라클 같은 경우에는 Adaptive Cursor Sharing을 통해서 런타임 관측 통계를 기반으로 생성을 하기도 합니다.

큐브리드에서는 플랜에 대해 실행 정보를 저장하지 않으므로, 다음과 같은 방식으로 정적 예측 도입을 하는 것이 가능합니다.

l 테이블의 스큐가 심할 경우 (MCV의 비중이 높을 경우)

l 해당 Predicate가 등장하는 곳이 플랜 선택을 크게 뒤집을 경우

이 때 해당 SQL을 바인드 어웨어로 표기하고, 해당 SELECTIVITY에 의해 플랜이 분기하는 임계점을 플랜 캐시 키로 사용할 수 있을 것입니다. 해당 방법을 통해 바인드 피킹을 어느 정도 해결할 수 있습니다.

마무리

히스토그램이 도입되었다고 해서 옵티마이저가 곧바로 완전해지는 것은 아닙니다. 이와 같이 바인드 변수가 존재하기 때문입니다. 히스토그램을 활용하면 바인드 피킹으로 인한 문제를 일부 완화할 수는 있지만, 값이 바뀔 때마다 최적 실행 계획이 달라질 수 있는 근본적인 특성까지 완전히 제거할 수는 없습니다.

또한 다른 DBMS에서 제공하는 Adaptive Cursor Sharing 같은 기능 역시 만능 해법은 아닙니다. 워크로드 특성에 따라 기대만큼 동작하지 않거나, 운영 환경(특히 OLTP)에서는 부작용이나 제약을 함께 고려해야 하는 경우도 있습니다.

결국 중요한 것은 사람의 판단입니다. CUBRID에 히스토그램이 도입된 이후에도 “이 쿼리는 바인드 값에 따라 플랜이 흔들릴 수 있다”는 가능성을 염두에 두고, 필요하다면 쿼리를 튜닝하거나 재작성해 안정적인 실행 계획을 유도하는 DBA의 역량이 더욱 중요해 질 것입니다.

CUBRID 전환 후 성능 이슈 분석: SQL 문법보다 실행 패턴이 중요하다

큐브리드_김주현 — Fri, 15 May 2026 09:51:18 +0900

CUBRID 운영 노트 CUBRID 11.4 기준

CUBRID 전환 후 성능 이슈 분석:
SQL 문법보다 실행 패턴이 중요하다

Oracle/MySQL에서 CUBRID로 마이그레이션한 뒤 성능이 저하됐을 때 확인해야 할 실행 계획, 통계 정보, 페이징 SQL, 대량 JOIN, DBLink, 배치 SQL, Broker CAS 재산정 기준을 정리한다.

개요
전환 후 성능 저하가 발생하는 이유
전환 후 성능 분석 기본 흐름
Oracle/MySQL과 CUBRID 실행 방식 차이
1. 같은 SQL, 다른 실행 계획
2. 우선 점검 대상 SQL 유형
통계 정보 점검
실행 계획 확인
페이징 SQL 점검
대량 JOIN SQL 점검
DBLink 사용 SQL 점검
배치 SQL 수행 시간 비교
커넥션 풀과 Broker CAS 재산정
실무 사례: Oracle 0.5초 SQL이 CUBRID에서 8초
마이그레이션 후 성능 안정화 체크리스트
핵심 정리

1. 개요

DB 마이그레이션 프로젝트에서 자주 하는 착각이 있다.

데이터 이관이 끝났다.
SQL 문법 변환도 끝났다.
애플리케이션도 정상 기동된다.
그러면 마이그레이션은 끝난 것인가?

운영 관점에서는 아직 끝난 것이 아니다. 마이그레이션은 데이터가 들어갔다고 끝나지 않는다. 운영 트래픽에서 기존 수준의 응답 시간과 처리량이 나와야 완료된 것이다.

핵심 메시지

마이그레이션은 데이터 이관이 끝이 아니라 운영 성능이 안정화되어야 완료된다.

Oracle 또는 MySQL에서 CUBRID로 전환한 뒤 다음과 같은 문제가 발생할 수 있다.

→ Oracle에서는 0.5초였던 SQL이 CUBRID에서 8초 이상 수행
→ MySQL에서는 빠르던 페이징 SQL이 CUBRID에서 정렬 비용 증가
→ 인덱스는 이관되었지만 실행 계획이 기대와 다르게 선택
→ 통계 정보 미갱신으로 옵티마이저가 잘못된 실행 계획 선택
→ 대량 JOIN SQL에서 Hash Join, Nested Loop Join 선택 차이 발생
→ DBLink SQL이 원격 호출 비용 때문에 느려짐
→ 배치 SQL 수행 시간이 기존보다 길어짐
→ WAS connection pool은 그대로인데 Broker CAS가 부족해짐

전환 후 성능 이슈는 SQL 문법 문제가 아니라 실행 패턴 문제인 경우가 많다.

2. 전환 후 성능 저하가 발생하는 이유

마이그레이션 후 성능이 느려지는 이유는 단순하지 않다. 같은 SQL처럼 보여도 DBMS가 SQL을 실행하는 방식은 다르다.

WARN

주의사항

Oracle에서 빠른 SQL이 CUBRID에서도 반드시 빠른 것은 아니다. MySQL에서 빠른 페이징 SQL이 CUBRID에서도 같은 방식으로 빠르게 동작한다고 보장할 수 없다.

성능 저하 원인은 보통 다음 범주 중 하나다.

실행 계획 차이

통계 정보 미갱신, 인덱스 구조 차이로 옵티마이저가 비효율적인 실행 계획 선택

페이징 · 정렬 비용

OFFSET 기반 페이징, ORDER BY 정렬 인덱스 미활용으로 인한 정렬 비용 증가

JOIN 방식 차이

Hash Join, Nested Loop Join 선택 차이. CUBRID 11.4에서 Hash Join이 추가됨

DBLink · 배치 비용

원격 호출 비용, 처리 단위와 COMMIT 단위 차이로 인한 배치 수행 시간 증가

커넥션 풀 불일치

WAS connection pool 합계와 Broker CAS 수 불일치로 피크 시 JQ 증가

데이터 분포 차이

이관 후 데이터 분포가 반영되지 않아 옵티마이저 비용 판단 오류

TIP

운영 팁

마이그레이션 후 성능 문제는 "SQL이 맞다/틀리다"가 아니라 "CUBRID에서 어떤 실행 계획으로 수행되는가"를 기준으로 봐야 한다.

3. 전환 후 성능 분석 기본 흐름

성능 이슈가 발생하면 아래 순서로 확인한다.

1

느린 SQL을 찾는다. Broker SQL Log에서 execute_time이 긴 SQL을 추출한다.

2

전환 전 DBMS의 수행 시간과 비교한다. 수치로 차이를 명확히 한다.

3

실행 계획을 확인한다. Full Scan, Sort, JOIN 방식, 인덱스 사용 여부를 본다.

4

통계 정보를 갱신한다. 데이터 이관 후 반드시 UPDATE STATISTICS를 수행한다.

5

페이징, JOIN, 정렬, GROUP BY 패턴을 확인한다.

6

배치 SQL은 처리 단위와 COMMIT 단위를 확인한다.

7

Broker CAS와 WAS connection pool을 재산정하고 변경 전후 지표를 비교한다.

WARN

표현 방식

나쁜 표현: "전환 후 SQL이 느려졌습니다."

좋은 표현: "Oracle에서 평균 0.5초였던 주문 이력 조회 SQL이 CUBRID 전환 후 평균 8초, 최대 15초까지 증가했습니다. Broker SQL Log 기준 execute_time이 증가했고, 동일 시간대 LONG-Q와 BUSY CAS가 함께 증가했습니다."

4. Oracle/MySQL과 CUBRID 실행 방식 차이

4.1 같은 SQL, 다른 실행 계획

DBMS마다 옵티마이저, 통계 정보, 인덱스 처리 방식, JOIN 방식이 다르다. 다음 SQL을 보자.

SELECT *
FROM order_history
WHERE member_id = ?
ORDER BY order_dt DESC
LIMIT 20;

Oracle, MySQL, CUBRID에서 SQL 문법은 비슷하게 보이지만, 실제 실행 방식은 다를 수 있다.

→ 어떤 인덱스를 사용하는가?
→ 정렬을 인덱스로 처리하는가, 아니면 별도 Sort가 발생하는가?
→ 먼저 필터링하는가, 먼저 정렬하는가?
→ 필요한 row만 읽는가, 중간 결과를 많이 만드는가?

실행 계획이 다르면 같은 SQL도 수행 시간이 크게 달라질 수 있다.

4.2 우선 점검 대상 SQL 유형

전환 후에는 모든 SQL을 한 번에 볼 수 없다. 우선순위를 정해야 한다.

사용자 요청이 많은 API SQL
응답 시간 SLA가 있는 SQL
대량 테이블을 조회하는 SQL
페이징 SQL, ORDER BY / GROUP BY가 있는 SQL
3개 이상 테이블 JOIN SQL
배치 SQL (마감, 정산, 통계)
DBLink 또는 원격 테이블 조회 SQL
기존 DB에서 Hint를 사용하던 SQL

TIP

운영 팁

마이그레이션 후 성능 검증은 전체 SQL을 동일하게 보지 않는다. 트래픽이 많거나 장애 영향이 큰 SQL부터 본다.

5. 통계 정보 점검

5.1 인덱스가 있어도 느릴 수 있다

마이그레이션 후 흔한 상황이다.

🟡 상황 — 인덱스가 있는데 Full Scan이 발생

현상: 인덱스는 모두 생성했지만 실행 계획에서 Full Scan이 선택된다.

원인: 데이터 이관 후 통계 정보를 갱신하지 않아 옵티마이저가 현재 데이터 분포를 반영하지 못하고 잘못된 실행 계획을 선택한다.

CUBRID는 통계 정보를 기반으로 비용 기반 최적화(Cost-Based Optimization)를 수행한다. 테이블과 인덱스 통계 정보는 실행 계획 선택에 직접적인 영향을 준다. 따라서 데이터 이관 후 통계 정보 갱신은 필수다.

5.2 통계 정보 갱신 방법

전체 클래스 통계 갱신 (샘플 기반, 기본 5000 페이지):

UPDATE STATISTICS ON ALL CLASSES;

전체 클래스 통계 갱신 (전체 페이지 스캔):

전체 페이지 대상 — 서비스가 적은 시간대 수행 권고

UPDATE STATISTICS ON ALL CLASSES WITH FULLSCAN;

특정 테이블 통계 갱신:

UPDATE STATISTICS ON order_history WITH FULLSCAN;

여러 테이블 통계 갱신:

UPDATE STATISTICS ON order_history, order_master, member WITH FULLSCAN;

마이그레이션 후 다음 시점에 통계 정보를 갱신한다.

대량 데이터 이관 직후
인덱스 생성 후
대량 INSERT/UPDATE/DELETE 후
운영 전환 전 성능 검증 전
주요 배치 데이터 적재 후

WARN

WITH FULLSCAN 주의

WITH FULLSCAN 옵션은 전체 페이지를 대상으로 통계를 수집하므로 서비스 부하가 적은 시간대에 수행하는 것을 권고한다. 대용량 테이블에서는 수행 시간이 길어질 수 있다.

5.3 통계 갱신 전후 비교 예시

전환 전 Oracle에서 0.5초였던 주문 이력 조회 SQL이 CUBRID 전환 후 8초로 증가한 케이스다. 인덱스는 생성되어 있었지만 데이터 이관 후 통계 정보를 갱신하지 않았다.

UPDATE STATISTICS ON order_history;

항목	통계 갱신 전	통계 갱신 후
수행 시간	8.0초	0.7초
실행 방식	Full Scan + Sort	Index Scan
Broker LONG-Q	증가	정상
CAS BUSY 유지 시간	길음	짧음

인덱스는 존재했지만 통계 정보가 갱신되지 않아 옵티마이저가 비효율적인 실행 계획을 선택했다. 통계 갱신 후 인덱스 기반 실행 계획으로 변경되면서 수행 시간이 정상화되었다.

6. 실행 계획 확인

전환 후 성능 분석에서 가장 중요한 것은 실행 계획이다. 다음 두 실행 계획은 결과는 같아도 성능은 완전히 다르다.

실행 계획 A

→ Index Scan → 적은 row 조회 → 빠른 응답

실행 계획 B

→ Full Scan → 전체 테이블 조회 → Sort → 느린 응답

6.1 실행 계획 확인 방법

CUBRID에서는 SET OPTIMIZATION LEVEL 또는 CUBRID Manager를 통해 실행 계획을 확인할 수 있다. csql에서 쿼리 실행 전 다음 명령을 사용한다.

csql — 실행 계획 출력 설정

-- 실행 계획 출력 ON
SET OPTIMIZATION LEVEL 513;

-- 실행 계획 확인할 SQL 실행
SELECT * FROM order_history WHERE member_id = 1 ORDER BY order_dt DESC LIMIT 20;

-- 실행 계획 출력 OFF
SET OPTIMIZATION LEVEL 1;

6.2 확인할 실행 계획 포인트

→ Full Scan 여부 — Index Scan으로 대체 가능한지 검토
→ Index Scan 여부 — 어떤 인덱스를 사용하는지 확인
→ JOIN 순서 — 가장 많이 줄일 수 있는 테이블이 먼저 처리되는지 확인
→ JOIN 방식 — Nested Loop Join, Hash Join 선택 적합성
→ Sort 발생 여부 — ORDER BY, GROUP BY 처리 방식
→ 중간 결과 row 수 — 과도한 중간 결과 생성 여부
→ 인덱스 컬럼 순서 적합 여부 — 복합 인덱스 선두 컬럼 일치 여부

TIP

운영 팁

전환 후 SQL이 느리면 먼저 실행 계획을 저장한다. 튜닝 후 실행 계획도 함께 저장해야 개선 근거가 남는다.

7. 페이징 SQL 점검

웹 서비스에서 페이징 SQL은 매우 자주 호출된다. OFFSET이 커지면 앞의 데이터를 건너뛰기 위해 많은 row를 읽고 정렬해야 할 수 있다. 이로 인해 전환 후 페이징 SQL 성능 문제가 자주 발생한다.

7.1 위험한 페이징 패턴

→ OFFSET 값이 큰 페이징 SQL
→ ORDER BY 컬럼에 인덱스 없음
→ WHERE 조건과 ORDER BY가 같은 인덱스를 활용하지 못하는 경우
→ 대량 테이블에서 최신순 정렬
→ 조건 없이 전체 목록 페이징
→ LIKE 검색 + ORDER BY + OFFSET 조합

7.2 실무 예시: 주문 이력 페이징

기존 SQL (문제 패턴):

SELECT *
FROM order_history
WHERE member_id = ?
ORDER BY order_dt DESC
LIMIT 20 OFFSET 10000;

OFFSET이 10,000이면 앞의 10,000건을 건너뛰기 위해 많은 row를 읽고 정렬해야 한다. OFFSET이 커질수록 수행 시간이 선형 증가한다.

점검할 인덱스:

CREATE INDEX idx_order_history_member_dt
ON order_history(member_id, order_dt);

개선 방향 — Keyset Pagination:

마지막으로 조회한 값을 기준으로 다음 페이지를 조회하는 방식으로 변경한다.

SELECT *
FROM order_history
WHERE member_id = ?
  AND order_dt < ?   -- 마지막으로 조회한 order_dt
ORDER BY order_dt DESC
LIMIT 20;

OFFSET 기반 페이징

→ OFFSET이 커질수록 앞 페이지를 계속 건너뜀. 대량 데이터에서 성능 저하

Keyset Pagination

→ 마지막 조회 값 이후 데이터만 읽음. OFFSET이 커져도 성능 유지

TIP

운영 팁

마이그레이션 후 페이징 SQL은 반드시 별도 점검한다. 특히 OFFSET이 큰 SQL은 전환 후 성능 문제가 자주 발생한다.

8. 대량 JOIN SQL 점검

대량 JOIN SQL은 DBMS마다 실행 방식 차이가 크게 나타날 수 있다. CUBRID 11.4에서는 대용량 처리를 위한 Hash Join이 추가되었고, 옵티마이저와 인덱스 처리 개선도 포함되었다. 따라서 CUBRID 버전에 따라 JOIN 성능과 실행 계획이 달라질 수 있다.

8.1 점검 대상 JOIN SQL

→ 3개 이상 테이블 JOIN
→ 대량 테이블과 대량 테이블 JOIN
→ 조건절이 약한 JOIN
→ JOIN 컬럼에 인덱스가 없는 SQL
→ GROUP BY 또는 ORDER BY가 함께 있는 JOIN
→ 통계성 배치 SQL, 정산 SQL

8.2 실무 예시: 주문/회원/결제 JOIN

SELECT
    o.order_id,
    o.order_dt,
    m.member_name,
    p.payment_amount
FROM order_master o
JOIN member m
  ON o.member_id = m.member_id
JOIN payment p
  ON o.order_id = p.order_id
WHERE o.order_dt >= '2026-05-01'
  AND o.order_dt < '2026-06-01';

점검할 인덱스:

CREATE INDEX idx_order_master_01
ON order_master(order_dt, member_id, order_id);

CREATE INDEX idx_member_01
ON member(member_id);

CREATE INDEX idx_payment_01
ON payment(order_id);

8.3 JOIN SQL 튜닝 체크리스트

JOIN SQL 점검 항목

JOIN 컬럼에 인덱스가 있는가?

먼저 줄일 수 있는 조건이 있는가? (기간 조건, 상태 조건)

기간 조건 컬럼에 인덱스가 있는가?

JOIN 순서가 비효율적이지 않은가?

통계 정보가 최신인가?

GROUP BY 또는 ORDER BY 때문에 정렬 비용이 커지지 않는가?

대량 결과를 애플리케이션으로 모두 가져오고 있지 않은가?

TIP

운영 팁

대량 JOIN SQL은 인덱스 하나만 추가해서 해결되지 않을 수 있다. JOIN 순서, 조건절 선택도, 통계 정보, 정렬 비용을 함께 봐야 한다.

9. DBLink 사용 SQL 점검

DBLink는 CUBRID에서 원격 데이터베이스의 데이터를 조회하거나, 마이그레이션 전환 기간 동안 기존 시스템과 신규 시스템을 함께 운영할 때 유용하게 사용할 수 있는 기능이다. 다만 원격 데이터베이스를 조회하는 SQL은 로컬 테이블만 조회하는 SQL보다 네트워크 왕복, 원격 데이터 전송, 데이터 타입 변환 비용이 추가로 발생한다.

DBLink 주요 활용 시나리오

이기종 DBMS 간 데이터 조회, 마이그레이션 전환 기간 병행 운영, 원격 CUBRID 또는 외부 데이터베이스와의 조회 연동에 사용할 수 있다.

9.1 DBLink SQL 성능 특성 이해

DBLink 원격 DBMS와 네트워크 통신이 포함되므로, 로컬 테이블 조회와 실행 방식이 다르다. 따라서 DBLink SQL은 원격에서 가져오는 데이터 범위와 조회 시점을 기준으로 설계해야 한다.

→ 원격 호출 비용이 포함되므로 로컬 조회보다 응답 시간이 길 수 있다.
→ 조건 없이 원격 테이블 전체를 조회하면 데이터 전송량이 많아질 수 있다.
→ 네트워크 지연 시간이 SQL 응답 시간에 직접 반영된다.
→ 원격 DBMS와 CUBRID 간 데이터 타입 변환 비용이 발생할 수 있다.

9.2 DBLink SQL 올바른 작성 방법

1. 조건을 원격 조회 시점에 명시한다.

-- 비효율: 조건 없이 원격 전체 테이블을 가져온 뒤 로컬 필터링
SELECT *
FROM remote_member@dblink;

-- 권장: 원격 조회 시점에 조건을 포함해 전송량 최소화
SELECT member_id, member_name, member_status
FROM remote_member@dblink
WHERE member_status = 'A'
  AND join_dt >= '2025-01-01';

2. 대량 JOIN이 필요한 경우 임시 테이블 방식을 활용한다.

-- 1단계: 필요한 원격 데이터만 로컬 임시 테이블에 적재
CREATE TABLE tmp_remote_member AS
SELECT member_id, member_name
FROM remote_member@dblink
WHERE member_status = 'A';

-- 2단계: 로컬 테이블과 JOIN. 인덱스 활용 가능
SELECT o.order_id, o.order_dt, m.member_name
FROM local_order o
JOIN tmp_remote_member m
  ON o.member_id = m.member_id
WHERE o.order_dt >= '2026-05-01';

3. 배치 처리에서 DBLink를 활용해 데이터를 동기화한다.

-- 주기적으로 원격 데이터를 로컬에 동기화해 온라인 API 응답 안정화
DELETE FROM sync_member
WHERE sync_dt < CURRENT_TIMESTAMP - 1;

INSERT INTO sync_member (member_id, member_name, member_status, sync_dt)
SELECT member_id, member_name, member_status, CURRENT_TIMESTAMP
FROM remote_member@dblink
WHERE updated_dt >= CURRENT_TIMESTAMP - 1;

9.3 마이그레이션 전환 기간 활용 패턴

Oracle 또는 MySQL에서 CUBRID로 전환하는 과정에서 시스템이 단계적으로 이관될 때, DBLink는 전환 완료 전까지 양쪽 데이터를 연결하는 수단이 된다.

온라인 API 조회	→ 배치로 동기화된 로컬 테이블 조회. 응답 시간 안정적
배치 집계 / 정산	→ DBLink로 원격 데이터 직접 참조. 별도 적재 없이 최신 데이터 활용
전환 기간 병행 운영	→ DBLink로 구 시스템 데이터 참조하며 신규 시스템 검증

운영 팁

DBLink는 원격 데이터베이스 연계에 유용한 수단이다. 성능 특성을 이해하고 조건 범위와 조회 시점을 설계하면, 마이그레이션 전환 기간뿐 아니라 이기종 시스템을 함께 운영하는 환경에서도 안정적으로 활용할 수 있다.

10. 배치 SQL 수행 시간 비교

마이그레이션 프로젝트에서 온라인 API만 검증하고 배치 SQL을 놓치는 경우가 많다. 하지만 운영 장애는 야간 배치에서 자주 발생한다. 전환 후 배치 SQL은 반드시 기존 DBMS와 수행 시간을 비교해야 한다.

배치명	전환 전 수행 시간	CUBRID 수행 시간	차이	조치
주문 정산	10분	35분	+25분	JOIN 튜닝
접속 로그 삭제	5분	40분	+35분	DELETE 분할
회원 상태 변경	3분	15분	+12분	인덱스 추가
통계 생성	20분	18분	-2분	정상

10.1 대량 DELETE 배치 개선 예시

기존 SQL (문제 패턴):

DELETE FROM access_log
WHERE log_dt < '2025-01-01';

한 번에 수천만 건 삭제하면 Archive Log가 급증하고, CAS가 장시간 BUSY 상태를 유지하며 API 조회와 Lock 경합이 발생할 수 있다.

개선 — 월 단위 분할 처리:

-- 1월 처리
DELETE FROM access_log
WHERE log_dt >= '2024-01-01'
  AND log_dt < '2024-02-01';
COMMIT;

-- 2월 처리
DELETE FROM access_log
WHERE log_dt >= '2024-02-01'
  AND log_dt < '2024-03-01';
COMMIT;

TIP

운영 팁

마이그레이션 후 배치 SQL은 빠른지보다 운영 시간 안에 안정적으로 끝나는지가 중요하다.

11. 커넥션 풀과 Broker CAS 재산정

Oracle이나 MySQL에서 사용하던 WAS connection pool 설정을 CUBRID 전환 후 그대로 사용하는 경우가 많다. 하지만 CUBRID는 애플리케이션이 Broker를 통해 DB Server에 접근하는 구조이므로, WAS connection pool과 Broker CAS 수를 함께 계산해야 한다.

11.1 기본 계산 예시

WAS 서버 수
4대

WAS당 connection pool max
30

총 최대 DB 연결 수 = 4 × 30
= 120

cubrid_broker.conf

[%broker1]
MIN_NUM_APPL_SERVER = 10
MAX_NUM_APPL_SERVER = 80

DANGER

문제 상황

WAS 전체 최대 연결 수는 120인데 Broker CAS 최대 수는 80이다. 피크 시간대에 WAS가 최대 연결을 사용하면 Broker에서 CAS 부족 또는 JQ 증가가 발생할 수 있다.

11.2 Broker CAS 재산정 기준

필요 CAS 수 =
  실제 동시 SQL 수행 수
+ 피크 시간 여유
+ 배치 접속 수
+ 장애 대응 여유

확인할 항목:

→ 실제 동시 SQL 수행 수 및 평균 SQL 수행 시간
→ 피크 시간대 QPS
→ 배치 시간대 동시 접속 수
→ DB Server의 max_clients 파라미터
→ 서버 메모리 및 OS file descriptor 한도

11.3 CAS 부족 판단 지표

Broker 상태 모니터링

cubrid broker status -b -s 1

AS = MAX_NUM_APPL_SERVER + JQ 증가

→ CAS 부족. MAX_NUM_APPL_SERVER 증가 검토

AS = 최대치 + LONG-Q 증가

→ 단순 CAS 부족이 아니라 SQL 지연으로 CAS가 점유되는 상태

JQ 증가 + LONG-Q 정상

→ 짧은 피크 트래픽. CAS 수 증가 또는 MIN 값 조정 검토

CLIENT_WAIT 증가

→ 클라이언트가 CAS를 기다리는 상태. 연결 대기 발생

WARN

주의사항

JQ가 증가한다고 무조건 CAS를 늘리면 안 된다. 먼저 CAS를 오래 점유하는 SQL이 무엇인지 Broker SQL Log에서 확인해야 한다.

12. 실무 사례: Oracle 0.5초 SQL이 CUBRID에서 8초

12.1 상황

🔴 주문 이력 조회 API 응답 지연

전환 전: Oracle에서 주문 이력 조회 SQL 평균 0.5초

전환 후: CUBRID에서 동일 API 평균 8초, 최대 15초

영향: 주문 이력 API 응답 지연 / Broker LONG-Q 증가 / CAS BUSY 증가

12.2 SQL

SELECT *
FROM order_history
WHERE member_id = ?
ORDER BY order_dt DESC
LIMIT 20;

12.3 원인 분석

1

Broker SQL Log 확인 → execute_time 8.2초, fetch_time 0.1초. DB 실행 구간 문제 확인

2

실행 계획 확인 → 기대: member_id + order_dt 인덱스 사용. 실제: Full Scan 후 Sort

3

원인 확정 → 인덱스는 생성되었지만 통계 정보가 갱신되지 않아 옵티마이저가 잘못된 실행 계획 선택

12.4 조치

-- 통계 정보 갱신
UPDATE STATISTICS ON order_history WITH FULLSCAN;

-- 복합 인덱스 생성 (member_id + order_dt)
CREATE INDEX idx_order_history_member_dt
ON order_history(member_id, order_dt);

12.5 결과

항목	조치 전	조치 후
API 응답 시간	8초	0.7초
SQL execute_time	8.2초	0.5초
LONG-Q	증가	정상
BUSY CAS	증가	정상
실행 계획	Full Scan + Sort	Index Scan

장애 보고서 문장 예시

Oracle에서 평균 0.5초 수행되던 주문 이력 조회 SQL이 CUBRID 전환 후 평균 8초로 증가했다. Broker SQL Log 기준 execute_time이 증가했으며 fetch_time은 짧았다. 실행 계획 확인 결과 order_history 테이블에서 Full Scan 후 Sort가 발생했다. 데이터 이관 후 통계 정보가 갱신되지 않아 옵티마이저가 비효율적인 실행 계획을 선택한 것으로 판단된다. UPDATE STATISTICS 수행 및 member_id, order_dt 복합 인덱스 검토 후 평균 응답 시간이 0.7초로 개선되었다.

13. 마이그레이션 후 성능 안정화 체크리스트

SQL 기준

전환 전 주요 SQL 수행 시간 확보

CUBRID 전환 후 SQL 수행 시간 측정

Broker SQL Log 기준 execute_time 확인

실행 계획 확인 — Full Scan, Sort, JOIN 방식

인덱스 사용 여부 확인

통계 정보 갱신 (UPDATE STATISTICS)

인덱스 기준

PK 인덱스 정상 생성 여부

FK 성격의 JOIN 컬럼 인덱스 확인

WHERE 조건 컬럼 인덱스 확인

ORDER BY 컬럼 인덱스 확인

복합 인덱스 컬럼 순서 확인

페이징 SQL 기준

OFFSET이 큰 SQL 확인

WHERE + ORDER BY 복합 인덱스 확인

Keyset Pagination 적용 가능 여부

전체 건수 COUNT SQL 비용 확인

배치 SQL 기준

전환 전 배치 수행 시간 확보 및 비교

COMMIT 단위 확인

Archive Log 증가량 확인

대량 UPDATE/DELETE 분할 여부 확인

배치 시간대 API 영향 여부 확인

Broker / CAS 기준

WAS connection pool 합계 확인

Broker MAX_NUM_APPL_SERVER 확인

DB Server max_clients 확인

피크 시간 AS (Active Server) 확인

JQ, BUSY CAS, CLIENT_WAIT, LONG-Q 증가 여부 확인

14. 핵심 정리

핵심 메시지

마이그레이션은 데이터 이관이 끝이 아니라 운영 성능이 안정화되어야 완료된다.

실행 패턴이 핵심

전환 후 성능 문제는 SQL 문법보다 실행 계획, 통계 정보, 인덱스, 호출 패턴에서 발생하는 경우가 많다.

인덱스 사용 여부가 중요

인덱스는 생성 여부보다 실제 실행 계획에서 사용되는지가 중요하다.

CAS 재산정

WAS connection pool과 CUBRID Broker CAS를 함께 계산하지 않으면 전환 후 피크 시간대에 JQ와 응답 지연이 발생할 수 있다.

전환 후 반드시 수행할 작업:

주요 SQL 수행 시간 비교
통계 정보 갱신 (UPDATE STATISTICS ON ALL CLASSES WITH FULLSCAN)
실행 계획 확인 및 인덱스 사용 여부 확인
페이징 SQL 점검
대량 JOIN SQL 점검
DBLink SQL 점검
배치 SQL 수행 시간 비교
Broker CAS 재산정
운영 지표 기준 성능 안정화 확인

참고 자료

↗ CUBRID 11.4 SQL 튜닝 — 쿼리 실행 계획 ↗ CUBRID 11.4 — Broker 상태 확인 및 제어 ↗ CUBRID 11.4 Release Notes ↗ CUBRID Migration Toolkit ↗ CUBRID Migration Toolkit 11.4.0 Release

CUBRID 장애 대응 Runbook

큐브리드_김주현 — Thu, 14 May 2026 18:10:47 +0900

CUBRID 운영 가이드 CUBRID 11.4 기준

CUBRID 장애 대응 Runbook

(알람 발생 후 10분 안에 확인해야 할 것들)

장애 상황에서 중요한 것은 명령어를 얼마나 많이 아는가가 아니라, 발생 직후 어떤 순서로 확인하느냐이다. 이 Runbook은 CUBRID 운영 환경에서 10분 안에 원인 영역을 분리하고, 서비스 담당자에게 정확한 상황을 공유하기 위한 실무 대응 가이드이다.

개요 및 목표
장애 대응 기본 원칙
10분 대응 타임라인
기본 명령어 세트
1차 분류표
DB 접속 실패 대응
Broker / DB Server 계층 구분
CAS 전체 BUSY 대응
로그 디스크 Full 대응
Archive Log 증가 대응
실무 시나리오
장애 유형별 Runbook
증거 수집 스크립트
서비스 담당자 공유 템플릿
조치 기준 및 에스컬레이션
장애 대응 체크리스트
핵심 정리

1. 개요 및 목표

DB 장애 발생 시 DBA, 개발자, 인프라 담당자, 업무 담당자가 동시에 질문을 쏟아낸다. "DB가 죽었나요?", "디스크가 찼나요?", "서비스 영향 범위가 어디까지인가요?" 등이다. 명확한 Runbook이 없으면 각자 익숙한 명령어부터 실행하게 되고, 원인 파악은 늦어지며 서비스 담당자에게 전달되는 메시지도 흔들린다.

CUBRID는 애플리케이션이 Broker를 통해 DB Server에 접근하는 구조이다. 접속 실패의 원인은 Broker, CAS, DB Server, 네트워크, 계정, 디스크, 로그 중 하나일 수 있다.

Application / WAS
↓
TCP 연결
Broker (cub_broker)
↓
요청 분배

        cub_cas 1
        cub_cas 2
        cub_cas 3
        cub_cas N
      
↓
DB Server (cub_server)

목표 1 원인 분리

장애 발생 후 10분 안에 1차 원인 영역을 분리한다.

목표 2 계층 구분

Broker 문제인지 DB Server 문제인지 구분한다.

목표 3 빠른 식별

SQL 지연, CAS 부족, 디스크 Full, 로그 증가를 빠르게 식별한다.

목표 4 커뮤니케이션

서비스 담당자에게 공유할 수 있는 중간 상황 메시지를 만든다.

2. 장애 대응 기본 원칙

장애 발생 직후에는 원인을 단정하지 않는다. 애플리케이션에서 "DB 접속 실패"가 발생했다고 해서 DB Server가 죽었다고 바로 판단하면 안 된다.

1

증상과 원인을 분리한다. "접속 안 됨"은 증상이고, 원인은 Broker, 네트워크, 디스크 등 여러 곳일 수 있다.

2

서비스 영향 범위를 먼저 확인한다. 전체 장애인지, 특정 API만 영향받는지 파악한다.

3

Broker와 DB Server 상태를 분리해서 본다. 둘을 혼동하면 불필요한 재기동으로 장애를 키울 수 있다.

4

디스크 사용률을 초기에 확인한다. 디스크 Full은 모든 계층에 동시에 영향을 줄 수 있다.

5

장시간 SQL과 CAS 점유 상태를 확인한다. 응답 지연의 가장 흔한 원인이다.

6

복구에 영향을 주는 로그 파일을 임의로 삭제하지 않는다. Active Log와 Archive Log는 복구의 핵심이다.

7

조치 전 현재 상태를 로그로 남긴다. 재기동 후에는 중요한 흔적이 사라질 수 있다.

TIP

운영 Tip

장애 대응 초반에는 "해결"보다 "분류"가 먼저다. 접속 장애인지, 응답 지연인지, 디스크 장애인지, SQL 장애인지 10분 안에 분류하면 이후 대응 속도가 크게 빨라진다.

3. 10분 대응 타임라인

장애 발생 후 10분 안에 원인 영역을 분리하기 위한 순서이다. 각 단계를 순서대로 진행하되, 결정적인 원인이 확인되면 즉시 공유 단계로 이동한다.

T+0~1분

알람 수신 및 장애 시간 기록
영향 서비스 파악 (전체 / 일부)
최근 배포, 배치, DB 작업 여부 확인

T+1~3분

cubrid service / server / broker status 확인
Broker Port Listen 여부 확인
OS 프로세스 확인 (ps -ef | grep cub)

T+3~5분

Broker 상세 상태 확인 (cubrid broker status -b -s 1)
AS, JQ, TPS, QPS, LONG-Q, ERR-Q 확인
CAS 상세 상태 확인 (cubrid broker status -f broker1)

T+5~7분

디스크 사용률 확인 (df -h, df -i)
Data, Log, Backup, SQL Log 경로 별도 확인
Active Log / Archive Log 증가 여부 확인

T+7~10분

Broker SQL Log / Error Log 확인
장시간 SQL 또는 반복 오류 확인
1차 판단 메시지 서비스 담당자에게 공유

4. 기본 명령어 세트

장애 상황에서 가장 먼저 실행할 명령어는 복잡할 필요가 없다. 아래 순서대로 실행한다.

현재 상태 기록

date       # 장애 분석 로그의 기준점
hostname
whoami

CUBRID 프로세스 상태

cubrid service status
cubrid server status
cubrid broker status

Broker 상세 상태

cubrid broker status -b          # Broker 요약
cubrid broker status -b -s 1     # 1초 단위 반복 출력
cubrid broker status -f broker1  # 특정 Broker의 CAS 상세

디스크 및 프로세스

df -h                        # 디스크 사용률
df -i                        # inode 사용률
ps -ef | grep cub            # CUBRID 프로세스 확인
netstat -an | grep 33000     # Broker Port 확인

로그 확인

tail -100 $CUBRID/log/broker/error_log/*
tail -100 $CUBRID/log/server/*

5. 1차 분류표

장애 초반에는 아래 기준으로 원인 영역을 나눈다. 증상을 보고 우선 확인 대상을 결정하는 것이 핵심이다.

증상	우선 확인 대상	의심 원인
DB 접속 실패	Broker, Port, DB Server	Broker 중지, CAS 부족, DB Server 중지, 네트워크
API 응답 지연	Broker CAS, SQL Log	장시간 SQL, Lock 대기, DB 부하
모든 CAS BUSY	Broker 상태, SQL Log	SQL 지연, 배치 폭주, Lock 대기
JQ 증가	Broker 상태	CAS 부족, SQL 처리 지연
LONG-Q 증가	SQL Log	느린 SQL, Full Scan, 대량 Join
ERR-Q 증가	Broker Error Log, SQL Log	SQL 오류, 제약조건 오류, 접속 오류
디스크 100%	df, log 경로	Archive Log 증가, SQL Log 증가, 백업 파일 증가
DB Server 기동 실패	Server Log, 볼륨, 로그	데이터 볼륨 문제, 로그 문제, 권한 문제
특정 시간대 반복 장애	배치, 로그, QPS 추이	야간 배치, 대량 DML, 백업 시간 충돌

6. DB 접속 실패 대응

DB 접속 실패는 장애 문의 중 가장 자주 발생하는 유형이다. 애플리케이션 로그에는 Cannot connect to CUBRID, Connection timeout, Broker connection failed, DB connection pool exhausted 같은 형태로 남는다.

DANGER

경고

접속 실패 발생 시 바로 DB Server 재기동을 시도하면 안 된다. 반드시 Broker와 DB Server를 분리해서 먼저 확인한다.

6.1 Broker 상태 확인

cubrid broker status
cubrid broker status -b

→ Broker가 ON 상태인가?
→ Broker PID가 존재하는가?
→ Broker Port가 설정값과 일치하는가?
→ AS 값이 정상적으로 표시되는가?
→ JQ가 증가하고 있는가?
→ #REJECT가 증가하고 있는가?

6.2 Port Listen 확인

netstat -an | grep 33000
# 또는
ss -lntp | grep 33000

6.3 DB Server 상태 확인

cubrid server status
cubrid server status demodb

6.4 접속 실패 판단 흐름

Broker OFF

→ Broker 기동 여부, broker log 확인

Broker ON, Port Listen X

→ Broker Port 설정, 프로세스, 방화벽 확인

Broker ON, Port 정상, DB Server DOWN

→ DB Server log, volume, log disk 확인

Broker ON, DB Server ON, JQ 증가

→ CAS 부족 또는 SQL 지연 확인

특정 App만 실패

→ App connection pool, 방화벽, 계정, 접속 URL 확인

7. Broker / DB Server 계층 구분

CUBRID 장애 대응에서 가장 중요한 판단은 Broker 계층 문제인지 DB Server 계층 문제인지를 구분하는 것이다. 둘을 혼동하면 불필요한 재기동으로 장애를 키울 수 있다.

Broker 문제 가능성이 높은 경우

→ cubrid broker status에서 Broker가 OFF
→ Broker Port가 LISTEN 상태가 아님
→ CAS가 생성되지 않음
→ JQ가 계속 증가
→ 모든 CAS가 CLIENT_WAIT 또는 BUSY 상태
→ Broker Error Log에 접속 오류 반복

cubrid broker status
cubrid broker status -b -s 1
cubrid broker status -f broker1
tail -100 $CUBRID/log/broker/error_log/*

DB Server 문제 가능성이 높은 경우

→ cubrid server status에서 대상 DB가 보이지 않음
→ cub_server 프로세스가 없음
→ Server Log에 database volume, log volume 관련 오류 존재
→ Data Volume 또는 Log Volume 경로 디스크 Full
→ 모든 Broker에서 동일 DB 접속 실패

cubrid server status
ps -ef | grep cub_server
df -h
tail -100 $CUBRID/log/server/*

8. CAS 전체 BUSY 대응

CAS 전체 BUSY는 CUBRID 운영에서 자주 발생하는 장애 패턴이다. Broker는 정상이고 DB Server도 살아 있지만, 애플리케이션 응답이 느려지거나 신규 요청이 대기한다.

CAS 전체 BUSY 판단 흐름

LONG-Q 증가

→ 느린 SQL 또는 대량 SQL 가능성. SQL Log에서 장시간 SQL 확인

JQ 증가

→ CAS가 요청을 처리하지 못해 대기 발생. CAS 상태 및 SQL 확인

QPS 급증

→ 트래픽 급증 또는 배치 폭주 가능성. 특정 Client IP 확인

DB CPU/I/O 높음

→ DB Server 처리 병목 가능성. 실행 계획 및 인덱스 확인

WARN

주의사항

CAS 전체 BUSY 상황에서 무조건 Broker 재기동을 먼저 하면 원인 SQL 증거가 사라질 수 있다. 재기동 전 broker status, SQL Log, Error Log를 반드시 먼저 확보한다.

9. 로그 디스크 Full 대응

DB 장애에서 디스크 Full은 매우 위험하다. DB 데이터 파일, Active Log, Archive Log, Broker SQL Log, 백업 파일이 같은 파일시스템에 있으면 하나의 경로 Full이 전체 서비스 장애로 이어질 수 있다.

df -h
df -i
du -sh $CUBRID/log/*
du -sh /backup/*

DANGER

절대 삭제 금지 항목

Active Log와 Archive Log는 장애 복구에 사용된다. 삭제 금지: Active Log / Archive Log / Database Volume / Control File / 현재 사용 중인 Broker Log / 현재 수행 중인 Backup 파일

10. Archive Log 증가 대응

Archive Log 증가는 단순 용량 문제가 아니다. 복구 가능성과 직접 연결된다.

주요 증가 원인

→ 대량 INSERT / UPDATE / DELETE
→ 장시간 트랜잭션 또는 Commit 지연
→ 야간 배치 또는 인덱스 생성 대량 작업
→ 백업 정책 부재 또는 로그 정리 정책 부재
→ HA 구성 환경에서 복제 지연

핵심 원칙

Archive Log는 "불필요한 파일"이 아니라 "복구 시점 선택권"이다. 삭제 전에는 항상 백업본, 복구 목표, 보관 정책을 확인한다.

11. 실무 시나리오: 새벽 배치 후 API 응답 시간 급증

발생 시간 02:10

주문 API 응답 시간이 1초에서 20초로 증가. 일부 요청 timeout 발생.

최근 작업 배치

02:00부터 야간 정산 배치 수행 중.

DB Server 장애가 아니라 배치 SQL로 인한 SQL 처리 지연이다. CAS가 배치 SQL에 점유되면서 API 요청이 대기하고 있으며, Archive Log 증가도 대량 UPDATE 영향이다.

12. 장애 유형별 Runbook

12.1 DB 접속 실패

cubrid service status
cubrid broker status
cubrid server status
netstat -an | grep 
df -h

12.2 응답 지연

cubrid broker status -b -s 1
cubrid broker status -f broker1
df -h
tail -100 $CUBRID/log/broker/error_log/*

12.3 CAS 부족

cubrid broker status -b -s 1
cubrid broker status -f broker1

12.4 로그 디스크 Full

df -h
df -i
du -sh $CUBRID/log/*
du -sh /backup/*

13. 증거 수집 스크립트

장애 대응 중에는 조치를 서두르기 전에 최소한의 증거를 확보해야 한다. 아래 스크립트를 평상시에 만들어두고 장애 발생 시 즉시 실행한다.

#!/bin/bash
BROKER_NAME="$1"
DB_NAME="$2"
BASE_DIR="/tmp/cubrid_incident"
TS=$(date +%Y%m%d_%H%M%S)
OUT_DIR="${BASE_DIR}/${DB_NAME}_${TS}"
mkdir -p "${OUT_DIR}"

date > "${OUT_DIR}/date.txt"
hostname > "${OUT_DIR}/hostname.txt"
cubrid service status > "${OUT_DIR}/cubrid_service_status.txt" 2>&1
cubrid server status "${DB_NAME}" > "${OUT_DIR}/cubrid_server_status.txt" 2>&1
cubrid broker status > "${OUT_DIR}/cubrid_broker_status.txt" 2>&1
cubrid broker status -b > "${OUT_DIR}/cubrid_broker_status_b.txt" 2>&1
cubrid broker status -f "${BROKER_NAME}" > "${OUT_DIR}/cubrid_broker_status_f.txt" 2>&1
df -h > "${OUT_DIR}/df_h.txt"
df -i > "${OUT_DIR}/df_i.txt"
ps -ef | grep cub > "${OUT_DIR}/ps_cub.txt"
netstat -an > "${OUT_DIR}/netstat_an.txt"

14. 서비스 담당자 공유 템플릿

장애 상황에서는 기술 분석만큼 커뮤니케이션이 중요하다. 서비스 담당자는 DB가 죽었는지, 어떤 서비스가 영향받는지, 복구 예상이 가능한지, 다음 조치가 무엇인지를 필요로 한다.

[CUBRID 장애 1차 상황 공유]
발생 시간:    YYYY-MM-DD HH:MM
인지 경로:    모니터링 알람 / 서비스 담당자 문의 / WAS 로그 확인
영향 서비스:  예: 주문 API, 관리자 로그인, 배치 처리
현재 증상:    예: DB 접속 실패 / API 응답 지연 / 일부 SQL timeout

현재 확인 결과:
  Broker 상태:
  DB Server 상태:
  디스크 사용률:
  CAS 상태:
  Error Log 특이사항:

1차 판단:  Broker 프로세스는 정상이나 CAS BUSY 증가로 SQL 처리 지연 발생
현재 조치: 장시간 SQL 확인 중, 배치 담당자에게 작업 중단 여부 확인 중
다음 공유: 10분 후 추가 상황 공유 예정

15. 조치 기준 및 에스컬레이션

1차 조치 — 안정화

→ 현재 상태 수집 (증거 확보)
→ Broker / DB Server 상태 확인
→ 디스크 Full 여부 확인
→ 장시간 SQL 확인
→ 서비스 담당자에게 영향 범위 공유

DANGER

1차 조치에서 피해야 할 작업

원인 확인 전 DB Server 재기동 / Active Log·Archive Log 임의 삭제 / 운영 DB에 restoredb 직접 수행 / SQL Log 전체 삭제 / 원인 미확인 상태에서 MAX_NUM_APPL_SERVER 무조건 증가

16. 장애 대응 체크리스트

기본 정보

장애 발생 시간 확인

영향 서비스 확인

최근 배포 또는 배치 여부 확인

CUBRID 상태

cubrid service status 확인

cubrid server status 확인

cubrid broker status 확인

Broker

Broker ON 여부 확인

Broker Port LISTEN 확인

AS / JQ / QPS / LONG-Q / ERR-Q 확인

17. 핵심 정리

핵심 원칙

CUBRID 장애 대응의 핵심은 명령어를 많이 아는 것이 아니라 장애 발생 후 10분 안에 원인 영역을 분리하는 것이다. 접속 실패는 Broker부터, 응답 지연은 CAS와 SQL Log, 디스크 장애는 Data·Log·Backup 경로를 분리해서 본다.

재기동 전 필수

DB 재기동은 마지막 수단이다. 재기동 전에 반드시 broker status, SQL Log, Error Log를 확보한다.

로그 삭제 금지

장애 시간대 SQL Log와 Archive Log는 삭제하지 않는다. 원인 분석과 복구의 핵심 증거이다.

참고 자료

↗ CUBRID 11.4 공식 매뉴얼 ↗ CUBRID 서비스 제어 (cubrid 유틸리티) ↗ CUBRID Broker 구성 및 관리 ↗ CUBRID 로그 관리 ↗ CUBRID 백업 및 복구

CUBRID Broker 튜닝 가이드

큐브리드_김주현 — Thu, 14 May 2026 17:59:47 +0900

CUBRID 운영 가이드CUBRID 11.4 기준

CUBRID Broker 튜닝 가이드
CAS, 동시 접속, 응답 지연 분석

CUBRID 운영에서 자주 마주치는 성능 문제와 접속 장애의 핵심에는 Broker가 있다. Broker 구조 이해부터 파라미터 설정, 상태 분석, 장애 대응까지 운영자 관점에서 정리한 가이드이다.

개요
Broker란 무엇인가
CAS 프로세스 개념
Broker와 CAS의 처리 흐름
cubrid_broker.conf 주요 파라미터
Broker 상태 확인 방법
CAS 상태별 해석
접속 지연 분석
응답 지연 분석
CAS 부족 현상 분석
운영 환경별 설정 예시
max_clients 계산 방법
장애 상황별 분석 시나리오
Broker 운영 체크리스트
튜닝 권장 접근 방식

1. 개요

CUBRID는 애플리케이션이 Database Server에 직접 접속하는 구조가 아니라, Broker를 통해 Database Server에 접근하는 구조를 사용한다. Broker는 단순한 포트 중계 역할이 아니라, 애플리케이션 연결 관리, CAS 프로세스 관리, SQL 로그 기록, 접속 제한, 동시 접속 제어, 응답 지연 분석의 핵심 지점이 된다.

Broker 유틸리티는 broker process와 application server, 즉 CAS process를 운영하고 관리하는 유틸리티이다.

Application
↓
JDBC / ODBC / CCI / PHP / Python 등
↓
CUBRID Broker
↓

cub_cas 1
cub_cas 2
cub_cas 3
cub_cas N
↓
CUBRID Database Server

운영자 관점에서 Broker를 잘 이해하면 다음 문제를 더 빠르게 분석할 수 있다.

→애플리케이션 DB 접속 실패
→순간적인 접속 지연
→동시 접속 증가에 따른 CAS 부족
→특정 SQL로 인한 CAS 점유
→장시간 BUSY 상태의 CAS
→DB Server는 정상인데 애플리케이션 응답이 느린 상황

2. Broker란 무엇인가

Broker는 CUBRID에서 애플리케이션과 Database Server 사이에 위치하는 중간 계층이다. 애플리케이션은 CUBRID JDBC, CCI, ODBC 등의 드라이버를 통해 Broker에 접속하고, Broker는 내부적으로 CAS를 통해 Database Server와 통신한다.

Broker가 실제로 제공하는 기능은 다음과 같다.

Connection Pool 관리

CAS 프로세스를 미리 생성해두고 앱 요청이 오면 가용 CAS를 즉시 할당한다. 연결 생성 비용이 줄어 응답 시간이 개선된다.

SQL 로그 추적

CAS별로 SQL 로그 파일(broker_name_N.sql.log)이 생성된다. 슬로우 쿼리나 에러 쿼리를 CAS 단위로 추적할 수 있어 성능 분석에 유용하다.

동시 접속 제어

MAX_NUM_APPL_SERVER로 CAS 상한을 제한해 DB Server에 가해지는 부하를 예측 가능하게 제어한다.

접속 제한 (ACL)

IP, DB 사용자, 데이터베이스 단위로 접속을 허용하거나 차단하는 접근 제어 기능을 제공한다.

브로커 없이 애플리케이션이 DB에 직접 붙는다면

→동시 접속 수가 급증하면 DB 서버 부하가 그대로 직격된다.
→연결을 맺고 끊는 비용이 계속 발생해 성능이 떨어진다.
→어떤 앱이 어떤 쿼리를 날리는지 추적하기 어렵다.
→CAS 단위로 세분화된 SQL 로그가 없으면 슬로우 쿼리 분석이 불편해진다.
→서비스별로 DB 접속 정책을 분리하기 어렵다.

3. CAS 프로세스 개념

CUBRID Broker를 이해할 때 가장 중요한 개념이 CAS(CUBRID Application Server)이다. 애플리케이션이 Broker에 접속하면 Broker는 실제 SQL 처리를 담당할 CAS를 할당하고, CAS는 Database Server에 SQL을 전달한 뒤 결과를 애플리케이션으로 반환한다.

항목	의미
`CAS 수`	Broker가 동시에 처리할 수 있는 애플리케이션 연결 수와 직접 관련
`CAS 상태`	현재 SQL 수행 중인지, 대기 중인지, 클라이언트 대기 상태인지 확인 가능
`CAS PID`	OS 프로세스 단위로 추적 가능
`CAS 메모리`	특정 SQL 또는 세션으로 인한 메모리 증가 확인 가능
`CAS SQL 로그`	어떤 SQL이 실행되었는지 추적 가능

cubrid broker status 출력에서 각 CAS는 ID, PID, QPS, LQS, PSIZE, STATUS 정보를 가지며, STATUS에는 BUSY, IDLE, CLIENT_WAIT, CLOSE_WAIT 등이 표시된다.

cubrid broker status 출력 예시

@ cubrid broker status
% query_editor
----------------------------------------
ID   PID   QPS   LQS PSIZE STATUS
----------------------------------------
 1 28434     0     0 50144 IDLE
 2 28435     0     0 50144 IDLE
 3 28436     0     0 50144 IDLE
 4 28437     0     0 50140 IDLE
 5 28438     0     0 50144 IDLE

% broker1 OFF

4. Broker와 CAS의 처리 흐름

애플리케이션에서 SQL을 실행하면 다음 순서로 처리된다.

1

애플리케이션이 Broker Port로 접속한다.

2

Broker는 사용 가능한 CAS를 찾는다.

3

사용 가능한 CAS가 있으면 해당 CAS에 연결을 할당한다.

4

CAS는 DB Server에 접속한다.

5

SQL 요청이 DB Server로 전달된다.

6

DB Server가 SQL을 실행한다.

7

실행 결과가 CAS와 Broker를 거쳐 애플리케이션으로 반환된다.

운영 포인트

CAS가 모두 사용 중이면 신규 요청은 대기하거나 지연될 수 있다. 특정 CAS가 장시간 SQL을 수행하면 해당 CAS는 계속 BUSY 상태가 된다. SQL 수행 시간이 길어지면 Broker 응답 지연처럼 보일 수 있으며, Broker 상태만 봐도 접속 계층 문제인지 DB Server 문제인지 1차 분리가 가능하다.

5. cubrid_broker.conf 주요 파라미터

Broker 설정은 cubrid_broker.conf 파일에서 관리한다. 기본 구성은 [broker] 공통 영역과 Broker별 영역으로 나뉜다.

cubrid_broker.conf — 기본 구조

[broker]
MASTER_SHM_ID           =30001
ADMIN_LOG_FILE          =log/broker/cubrid_broker.log

[%query_editor]
SERVICE                 =ON
BROKER_PORT             =30000
MIN_NUM_APPL_SERVER     =5
MAX_NUM_APPL_SERVER     =40
SQL_LOG                 =ON
TIME_TO_KILL            =120
SESSION_TIMEOUT         =300
KEEP_CONNECTION         =AUTO

5.1 SERVICE

SERVICE기본값: ON

Broker의 기동 여부를 제어한다. 사용하지 않는 Broker는 SERVICE=OFF로 명확하게 관리하는 것이 좋다.

값	의미
`ON`	Broker 기동 대상
`OFF`	Broker 미기동

5.2 BROKER_PORT

BROKER_PORT예: 33000

애플리케이션이 접속하는 Broker Port이다. 운영 시 포트 일치, 방화벽, 중복 여부, HA 접속 설계를 확인해야 한다.

5.3 MIN_NUM_APPL_SERVER

MIN_NUM_APPL_SERVER기본값: 5

Broker에 접속 요청이 없더라도 유지되는 최소 CAS 수를 설정하는 파라미터이다. 평상시 최소 동시 접속량을 기준으로 설정하는 것이 좋다.

5.4 MAX_NUM_APPL_SERVER

MAX_NUM_APPL_SERVER기본값: 40

허용 가능한 최대 동시 접속 수를 설정하는 파라미터이다. HA 환경에서는 같은 DB에 접속하는 모든 Broker 노드의 MAX_NUM_APPL_SERVER 합이 max_clients보다 작아야 한다.

무조건 크게 설정하면 안 되는 이유

CAS가 증가하면 OS 프로세스 수, 메모리 사용량, DB Server 접속 수, 파일 디스크립터 사용량이 함께 증가한다. max_clients 값이 커지면 실제 접속 여부와 관계없이 메모리 사용량도 증가한다.

5.5 TIME_TO_KILL

TIME_TO_KILL기본값: 120 (초)

동적으로 추가된 CAS 중 IDLE 상태의 CAS를 제거하는 시간을 설정하는 파라미터이다. 피크가 반복되는 서비스에서는 너무 짧게 설정하지 않는 것이 좋다.

5.6 SESSION_TIMEOUT

SESSION_TIMEOUT기본값: 300 (초)

세션이 장시간 유지될 때 정리 기준이 되는 파라미터이다. 애플리케이션 커넥션 풀 설정과 함께 봐야 한다.

5.7 SQL_LOG

SQL_LOG기본값: ON

Broker SQL 로그 기록 여부를 설정한다. SQL 로그는 장애 분석과 성능 분석에 유용하지만 로그 증가량과 I/O 부하를 함께 관리해야 한다.

5.8 KEEP_CONNECTION

KEEP_CONNECTION기본값: AUTO

Broker와 DB Server 간 연결 유지 정책과 관련된 파라미터이다. 방화벽이 있는 환경에서는 커넥션 풀, Broker 설정, OS TCP keepalive를 함께 검토하는 것이 좋다.

6. Broker 상태 확인 방법

CUBRID Broker 상태는 cubrid broker status 명령으로 확인한다.

기본 상태 확인

cubrid broker status

Broker 요약 상태 확인 (−b 옵션)

cubrid broker status -b

컬럼	의미	운영 관점
`AS`	현재 CAS 개수	MAX에 근접하면 CAS 부족 위험
`JQ`	Job Queue 대기 작업 수	0보다 크면 병목 신호
`TPS / QPS`	초당 트랜잭션/쿼리 수	처리량 추세 확인
`LONG-T / LONG-Q`	Long Transaction / Query	장시간 처리 추적
`ERR-Q`	Error Query	오류 SQL 증가 여부
`#REJECT`	접속 거부 수	ACL 또는 접속 제한 확인

주기적 모니터링 / 파일 저장

# 장애 분석 시 — 1초 주기
cubrid broker status -b -s 1

# 파일로 저장
cubrid broker status -b -t -s 1 > broker_status.log

상세 상태 확인 (−f 옵션)

cubrid broker status -f broker1

7. CAS 상태별 해석

Broker 상태에서 가장 먼저 봐야 할 항목은 CAS의 STATUS이다.

STATUS	의미	운영 해석
IDLE	대기 상태	사용 가능한 CAS
BUSY	SQL 또는 작업 처리 중	장시간 유지되면 SQL 지연 또는 Lock 대기 가능성
CLIENT_WAIT	클라이언트 요청 대기	애플리케이션 연결 유지 상태
CLOSE_WAIT	연결 종료 대기	네트워크 또는 애플리케이션 연결 종료 문제 가능성

CLIENT_WAIT 다수 발생 시 확인 사항

애플리케이션 커넥션 풀에서 연결을 오래 잡고 있지 않은지, commit/rollback 없이 대기 중인지, AutoCommit 설정 문제나 Connection close 누락이 있는지 확인해야 한다.

BUSY 상태 분석 순서

BUSY CAS 수 확인 → LONG-Q 증가 여부 → Broker SQL Log → DB Server CPU/I/O/Lock → 실행 계획 순으로 확인한다.

8. 접속 지연 분석

접속 지연은 애플리케이션에서 DB 연결을 가져오는 시간이 오래 걸리는 상황이다.

1차 확인 — Broker 기동 여부

cubrid broker status

2차 확인 — Job Queue

cubrid broker status -b -s 1

조건	해석
JQ↑ + AS ≈ MAX	CAS 부족 가능성. MAX_NUM_APPL_SERVER 확인 필요
JQ↑ + BUSY CAS 多	SQL 처리 지연 또는 DB Server 병목
JQ↑ + CLIENT_WAIT 多	애플리케이션 연결 반환 문제

3차 확인 — MAX_NUM_APPL_SERVER 및 연관 설정

동시 접속 수가 MAX_NUM_APPL_SERVER보다 많아지면 신규 요청이 지연될 수 있다. max_clients와 ulimit -n도 함께 확인한다.

9. 응답 지연 분석

응답 지연은 접속은 되지만 SQL 결과가 늦게 반환되는 상황이다.

Broker 관점 확인

cubrid broker status -b -s 1

CAS 상세 확인

cubrid broker status -f broker1

SQL Log 확인

cd $CUBRID/log/broker/sql_log && ls -lh

특정 SQL 반복 실행 여부, 대량 SELECT, 조건 없는 UPDATE/DELETE, Full Scan 가능성이 높은 SQL, 에러 발생 SQL 등을 확인한다.

10. CAS 부족 현상 분석

CAS 부족은 Broker 튜닝에서 가장 자주 발생하는 문제 중 하나이다.

CAS 부족 의심 증상

JQ 값 증가 / AS 값이 MAX_NUM_APPL_SERVER에 근접 / 모든 CAS가 BUSY 또는 CLIENT_WAIT / connection timeout / 특정 시간대 접속 지연

원인	설명
실제 동시 접속 증가	트래픽 증가로 CAS 수가 부족
SQL 지연	CAS가 SQL 수행에 오래 점유됨
Lock 대기	트랜잭션 대기로 CAS 반환 지연
애플리케이션 연결 미반환	Connection close 누락
커넥션 풀 과다 설정	App 서버 전체 pool 합이 Broker 한계를 초과
배치 작업	대량 SQL이 CAS를 장시간 점유

CAS 부족 분석 흐름

1

cubrid broker status -b -s 1 실행

2

cubrid broker status -f broker1 실행

3

SQL Log에서 장시간 SQL 확인

4

애플리케이션 connection pool 설정 확인

5

DB Server max_clients 확인

6

필요 시 MAX_NUM_APPL_SERVER 조정

11. 운영 환경별 설정 예시

아래 예시는 운영 설계 방향을 설명하기 위한 참고 예시이다. 실제 운영 서버에서는 트래픽, 메모리, DB Server max_clients, 애플리케이션 pool 크기, HA 구성 여부를 기준으로 조정해야 한다.

개발 환경

DEV — 소규모, SQL 로그 분석 중심

[%DEV_BROKER]
MIN_NUM_APPL_SERVER     =3
MAX_NUM_APPL_SERVER     =10
SQL_LOG                 =ON
TIME_TO_KILL            =120
SESSION_TIMEOUT         =300

일반 운영 환경

SERVICE — 다수 WAS 접속, 커넥션 풀 사용

[%SERVICE_BROKER]
MIN_NUM_APPL_SERVER     =10
MAX_NUM_APPL_SERVER     =80
SQL_LOG                 =ON
TIME_TO_KILL            =300
SESSION_TIMEOUT         =300

대규모 트래픽 환경 (Read/Write 분리)

LARGE SCALE — Broker Read/Write 분리 운영

[%APP_READ_BROKER]
BROKER_PORT             =33000
MIN_NUM_APPL_SERVER     =20
MAX_NUM_APPL_SERVER     =150
SQL_LOG                 =OFF

[%APP_WRITE_BROKER]
BROKER_PORT             =33100
MIN_NUM_APPL_SERVER     =10
MAX_NUM_APPL_SERVER     =80
SQL_LOG                 =ON

분리 운영 포인트

Read / Write Broker를 분리하면 장애 분석과 부하 관리가 쉬워진다. 두 Broker의 MAX_NUM_APPL_SERVER 합은 반드시 DB Server max_clients와 함께 계산해야 한다.

12. max_clients 계산 방법

Broker 튜닝에서 가장 중요한 것은 애플리케이션 connection pool, Broker CAS, DB Server max_clients를 함께 계산하는 것이다.

각 브로커 노드 당 MAX_NUM_APPL_SERVER50
브로커 노드 수2
CUBRID 내부 프로세스 여유분10
권장 max_clients = (50 × 2) + 10= 110

Linux ulimit 확인 필수

Linux에서는 max_clients가 파일 디스크립터 수와도 관련되므로, ulimit -n 값이 max_clients보다 커야 한다.

13. 장애 상황별 분석 시나리오

🔴 시나리오 1 — 애플리케이션에서 DB 접속이 안 되는 경우

cubrid broker status
cubrid broker status -b
netstat -an | grep 33000
ps -ef | grep cub_broker
ps -ef | grep cub_cas

분석 포인트: Broker 기동 여부 → SERVICE ON 여부 → BROKER_PORT 일치 여부 → 방화벽 포트 개방 여부 → CAS 생성 여부

🟡 시나리오 2 — 특정 시간대에만 접속이 느린 경우

cubrid broker status -b -s 1
cubrid broker status -f broker1

분석 포인트: JQ 증가 여부 → AS가 MAX에 도달했는지 → BUSY CAS 수 → CLIENT_WAIT CAS 수

🟡 시나리오 3 — SQL 응답이 느린 경우

cubrid broker status -b -s 1
cubrid broker status -f broker1
cd $CUBRID/log/broker/sql_log && ls -lh

분석 포인트: LONG-Q 증가 여부 → 특정 CAS 장시간 BUSY 여부 → SQL 로그에 반복되는 느린 SQL

🟠 시나리오 4 — CAS 메모리가 계속 증가하는 경우

cubrid broker status
ps -o pid,rss,vsz,cmd -p

분석 포인트: 특정 CAS의 PSIZE 지속 증가 여부 → 대량 조회 SQL 반복 여부 → APPL_SERVER_MAX_SIZE 설정 필요 여부

14. Broker 운영 체크리스트

Broker 상태

Broker SERVICE가 ON 상태인가?

Broker Port가 정상 Listen 중인가?

CAS 수가 평상시 기준 대비 과도하게 증가하지 않았는가?

JQ가 지속적으로 증가하지 않는가?

CAS 상태

BUSY 상태 CAS가 장시간 유지되지 않는가?

CLIENT_WAIT 상태 CAS가 과도하게 많지 않은가?

CLOSE_WAIT 상태가 반복적으로 발생하지 않는가?

특정 CAS의 PSIZE가 계속 증가하지 않는가?

성능 지표

QPS/TPS가 평소 대비 급증하지 않았는가?

LONG-Q가 증가하지 않는가?

ERR-Q가 증가하지 않는가?

#REJECT가 발생하지 않는가?

로그

Broker error log에 반복 에러가 없는가?

SQL log가 과도하게 증가하지 않는가?

로그 파일시스템 사용률이 안전한가?

설정

MAX_NUM_APPL_SERVER와 max_clients가 함께 계산되어 있는가?

WAS connection pool 합이 Broker/CUBRID 한계를 초과하지 않는가?

ulimit -n 값이 충분한가?

HA 환경에서 전체 Broker 노드의 CAS 합을 고려했는가?

15. 튜닝 권장 접근 방식

Broker 튜닝은 단순히 CAS 수를 늘리는 작업이 아니다. 올바른 접근 순서는 다음과 같다.

1

현재 Broker 상태를 수집한다.

2

평상시와 장애 시의 AS, JQ, QPS, LONG-Q, BUSY 상태를 비교한다.

3

애플리케이션 connection pool 설정을 확인한다.

4

DB Server max_clients와 OS ulimit을 확인한다.

5

SQL 로그에서 CAS를 오래 점유하는 SQL을 찾는다.

6

CAS 부족 / SQL 지연 / 애플리케이션 연결 반환 문제 중 어느 것인지 분류한다.

7

필요한 경우 MIN/MAX_NUM_APPL_SERVER를 조정한다.

8

변경 후 동일 지표를 다시 수집해 개선 여부를 확인한다.

피해야 할 방식

접속이 느리다고 무조건 MAX_NUM_APPL_SERVER만 증가 / SQL이 느린데 Broker 문제로만 판단 / WAS connection pool 합을 계산하지 않고 Broker 설정 / DB Server max_clients를 고려하지 않고 CAS 수 증가 / SQL_LOG를 켜놓고 로그 증가량을 관리하지 않음

핵심 정리

→Broker는 애플리케이션 접속의 첫 번째 관문이다.
→CAS는 실제 SQL 요청을 처리하는 Broker Application Server이다.
→MAX_NUM_APPL_SERVER는 동시 접속 처리량과 직접 관련된다.
→JQ 증가는 CAS 부족 또는 SQL 처리 지연의 신호일 수 있다.
→BUSY CAS가 많으면 SQL, Lock, DB Server 부하를 함께 봐야 한다.
→CLIENT_WAIT이 많으면 애플리케이션 connection 관리 문제를 의심해야 한다.
→Broker 튜닝은 DB Server max_clients, OS ulimit, WAS connection pool과 함께 설계해야 한다.

장애 시 필수 확인 명령어

장애 상황에서는 cubrid broker status -b -s 1, cubrid broker status -f , Broker SQL Log ($CUBRID/log/broker/sql_log)를 함께 확인하는 습관이 중요하다.

참고 자료

↗ CUBRID 11.4 사용자 매뉴얼 ↗ CUBRID 프로세스 제어 — Broker 제어 명령어 ↗ 시스템 설정 — cubrid_broker.conf 파라미터

CUBRID 아키텍처 이해

큐브리드_김주현 — Thu, 14 May 2026 16:38:50 +0900

CUBRID 아키텍처 Broker DBA 운영

CUBRID 아키텍처 이해:
(DB Server와 Broker는 어떻게 동작하는가)

처음 CUBRID를 접하는 DBA와 개발자를 위한 핵심 구조 가이드. cub_master, cub_broker, cub_cas, cub_server가 각자 어떤 역할을 맡고 있는지, 그리고 실제 장애 상황에서 어디부터 봐야 하는지 설명합니다.

CUBRID 11.4 기준

시작하기 전에: 왜 구조를 먼저 알아야 하는가
CUBRID 전체 구성 한눈에 보기
DB Server(cub_server)의 역할
Broker가 하는 일, 그리고 왜 중요한가
cub_broker와 cub_cas는 어떻게 다른가
Client에서 DB까지, 실제 연결 흐름
데이터베이스 볼륨 구조
다른 DBMS와 비교했을 때 CUBRID 구조의 특징
장애 분석 시 어떤 프로세스를 먼저 확인할까
운영 현장에서 자주 쓰는 기본 명령어
정리

1. 시작하기 전에: 왜 구조를 먼저 알아야 하는가

CUBRID를 처음 맡았을 때 가장 당황스러웠던 점은 "DB 접속이 안 된다"는 장애 신고를 받고 cub_server를 아무리 들여다봐도 문제가 없는데 접속이 안 됐던 경우였습니다. 알고 보니 브로커가 내려가 있었습니다. MySQL이나 PostgreSQL에서 넘어온 분들이라면 한 번쯤 겪는 혼란입니다.

CUBRID는 구조적으로 다른 DBMS와 다릅니다. 애플리케이션이 DB 서버에 직접 접속하는 게 아니라, 반드시 브로커(Broker)를 경유해야 합니다. CUBRID는 "데이터베이스 서버, 브로커, CUBRID 매니저로 구성되는 객체 관계형 DBMS"로 정의하고, 이 세 가지 구성요소 중 브로커가 빠지면 사실상 애플리케이션이 DB에 붙을 수 없습니다.

INFO

핵심 메시지: CUBRID 운영에서 장애 분석, 성능 문제, 접속 실패를 제대로 다루려면 DB 서버뿐만 아니라 브로커 계층을 함께 이해해야 합니다. 이 글은 그 구조를 실제 운영 관점에서 설명합니다.

2. CUBRID 전체 구성 한눈에 보기

CUBRID의 전체 흐름은 크게 세 계층으로 나뉩니다. 애플리케이션이 있는 클라이언트 계층, 브로커 계층, 그리고 실제 DB 서버 계층입니다. 프로세스 이름으로 보면 이렇습니다.

Application Layer

        Application Client
        JDBC / ODBC / CCI / PHP / Python / Node.js 등
      
        ↓
        BROKER_PORT 경유
      
Broker Layer

        cub_broker
        공유 메모리로 CAS 상태 확인 후 가용 CAS 선택
      
        ↓
      
        cub_cas #1
        ·
        cub_cas #2
        ·
        cub_cas #N
        MAX_NUM_APPL_SERVER 수만큼 생성
      
        ↓
      
Database Server Layer

        cub_master
        포트 감청, cub_server로 라우팅
      
        ↓
      
        cub_server
        데이터베이스별 1개 프로세스, 실제 데이터 처리
      
        ↓
      
Storage Layer

        Permanent Volume
        ·
        Temp Volume
        ·
        Active Log
        ·
        Archive Log

각 프로세스의 역할을 간략히 정리하면 다음과 같습니다.

프로세스	분류	핵심 역할
`cub_master`	DB Server Layer	TCP/IP 포트 감청, CAS 연결 요청을 cub_server로 중계
`cub_server`	DB Server Layer	SQL 실행, 트랜잭션, 잠금 관리, 데이터 저장·조회, 복구
`cub_broker`	Broker Layer	앱 연결 수신, 공유 메모리 조회, 가용 CAS 선택 및 전달
`cub_cas`	Broker Layer	앱과 DB Server 사이 실질적 중개, DB Server 관점에서는 클라이언트

3. DB Server(cub_server)의 역할

cub_server는 CUBRID에서 가장 핵심적인 프로세스입니다. 데이터를 실제로 저장하고 질의를 처리하며, 트랜잭션과 복구를 담당합니다. 이 서버 프로세스는 "데이터베이스 저장 구조를 관리하고 동시성과 트랜잭션 기능을 제공"하고 있습니다.

중요한 특징 하나는 데이터베이스마다 cub_server 프로세스가 하나씩 기동된다는 점입니다. 여러 데이터베이스를 운영 중이라면 각각의 cub_server가 별도로 떠 있습니다. cubrid server status를 실행해보면 각 DB별 서버 프로세스 상태를 확인할 수 있습니다.

cub_server가 처리하는 것들

→ 사용자 쿼리를 받아 실행 계획을 세우고 실제 SQL을 처리합니다.
→ 필요한 데이터 페이지를 데이터 볼륨에서 읽어 버퍼 풀에 캐싱합니다.
→ INSERT, UPDATE, DELETE 같은 변경 작업이 발생하면 Active Log에 먼저 기록합니다.
→ COMMIT 또는 ROLLBACK을 처리하고 트랜잭션 정합성을 보장합니다.
→ 동시 접속 사용자 간 충돌을 잠금(Lock)으로 제어합니다.
→ 장애가 발생하면 로그 파일을 기반으로 데이터를 복구합니다.

WARN

주의: cub_server가 정상 기동 중이어도 Broker가 내려가 있으면 애플리케이션은 DB에 접속할 수 없습니다. 접속 장애가 발생했을 때 DB 서버만 확인하다 시간을 낭비하는 경우가 많습니다. Broker 상태를 먼저 확인하는 습관을 들이는 것이 좋습니다.

4. Broker가 하는 일, 그리고 왜 중요한가

CUBRID 브로커란 "서버와 외부 응용 프로그램 간의 통신을 중계하는 CUBRID 전용 미들웨어"로 정의하며, 커넥션 풀링, 모니터링, 로그 추적 및 분석 기능을 제공하고 있습니다.

실제 운영 관점에서 브로커가 없으면 어떤 문제가 생기는지 생각해보면 왜 이 계층이 필요한지 이해하기 쉽습니다.

브로커 없이 애플리케이션이 DB에 직접 붙는다면

→ 동시 접속 수가 급증하면 DB 서버 부하가 그대로 직격됩니다.
→ 연결을 맺고 끊는 비용이 계속 발생해 성능이 떨어집니다.
→ 어떤 앱이 어떤 쿼리를 날리는지 추적하기 어렵습니다.
→ CAS 단위로 세분화된 SQL 로그가 없으면 슬로우 쿼리 분석이 불편해집니다.
→ 서비스별로 DB 접속 정책을 분리하기 어렵습니다.

브로커가 실제로 제공하는 것들

Connection Pool 관리 Broker

CAS 프로세스를 미리 생성해두고 앱 요청이 오면 가용 CAS를 즉시 할당합니다. 연결 생성 비용이 줄어 응답 시간이 개선됩니다.

SQL 로그 추적 Broker

CAS별로 SQL 로그 파일(broker_name_N.sql.log)이 생성됩니다. 슬로우 쿼리나 에러 쿼리를 CAS 단위로 추적할 수 있어 성능 분석에 유용합니다.

접속 제어 (ACL) Broker

cubrid_broker.conf의 ACCESS_CONTROL 파라미터를 ON으로 설정하면 IP 주소와 DB 이름 단위로 접속을 허용하거나 차단할 수 있습니다.

HA 페일오버 지원 Broker

HA 환경에서 접속 중인 서버에 장애가 발생하면 브로커가 미리 정의된 우선순위에 따라 다른 서버로 자동 전환합니다. 앱 코드 수정 없이 동작합니다.

TIP

운영 팁: 브로커는 단순 연결 중계기가 아닙니다. 접속 관리, 부하 제어, 장애 분석의 핵심 지점이므로 cubrid broker status -b를 주기적으로 확인하는 모니터링 루틴을 만들어두는 것을 권장합니다.

5. cub_broker와 cub_cas는 어떻게 다른가

브로커 계층 안에 프로세스가 두 종류 있다는 사실이 처음에는 헷갈릴 수 있습니다. cub_broker와 cub_cas는 역할이 명확히 다릅니다.

cub_broker 중계자

앱의 접속 요청을 최초로 받는 프로세스입니다. 공유 메모리에 저장된 CAS 상태를 확인하고, 현재 유휴 상태인 CAS를 찾아서 연결을 넘겨줍니다. 직접 SQL을 처리하지는 않습니다.

cub_cas 실행자

CUBRID Common Application Server의 약자입니다. 앱으로부터 SQL 요청을 받아 cub_server에 전달하고 결과를 돌려줍니다. cub_server 입장에서는 CAS가 클라이언트입니다.

공유 메모리(Shared Memory)는 이 둘 사이의 통신 수단입니다. cub_broker는 공유 메모리를 통해 각 CAS의 현재 상태(IDLE / BUSY)를 파악하고, 요청을 처리할 수 있는 CAS를 선택합니다. 운영자가 cubrid broker status로 확인하는 정보도 이 공유 메모리에서 읽어오는 것입니다.

병목이 발생하는 전형적인 패턴

브로커 계층에서 성능 문제가 생기는 경우는 대부분 다음 중 하나입니다.

→ MAX_NUM_APPL_SERVER 값이 실제 동시 접속 수보다 작아서 CAS가 부족한 경우
→ 특정 CAS가 무거운 쿼리를 오래 실행 중이라 BUSY 상태가 지속되는 경우
→ DB 서버 응답이 느려서 CAS들이 결과를 기다리며 대기하는 경우
→ 브로커 설정 값이 현재 트래픽 수준과 맞지 않는 경우

INFO

참고: HA 환경에서는 여러 브로커 노드가 하나의 DB 서버로 몰릴 수 있습니다. 이때는 모든 브로커 노드의 MAX_NUM_APPL_SERVER 합계가 cubrid.conf의 max_clients보다 작도록 설정해 주어야 합니다.

6. Client에서 DB까지, 실제 연결 흐름

앱에서 JDBC 드라이버로 쿼리 하나를 실행할 때 내부적으로 어떤 일이 벌어지는지 단계별로 살펴보겠습니다.

앱이 브로커에 접속 요청

JDBC, ODBC, CCI, PHP 등 어떤 인터페이스를 사용하든 접속 요청은 cubrid_broker.conf에 설정된 BROKER_PORT로 향합니다. CUBRID는 모든 클라이언트 인터페이스가 브로커를 통해 DB 서버에 접근하는 구조입니다.

cub_broker가 가용 CAS 선택

cub_broker는 공유 메모리를 조회해 IDLE 상태인 CAS를 찾습니다. 가용 CAS가 있으면 해당 CAS로 요청을 전달합니다. 모든 CAS가 BUSY 상태이면 대기 큐에서 기다리거나 연결이 실패할 수 있습니다.

cub_cas가 cub_master를 통해 DB 서버에 연결

선택된 CAS는 cubrid.conf에 설정된 cubrid_port_id 포트를 통해 cub_master에 연결 요청을 보냅니다. cub_master는 접속 정보를 보고 대상 cub_server에 연결합니다.

CAS ↔ cub_server 직접 통신

연결이 맺어지면 이후 SQL 요청과 응답은 CAS와 cub_server 사이에서 직접 처리됩니다. Linux 환경에서는 Unix Domain Socket을, Windows 환경에서는 랜덤 TCP 포트를 사용합니다.

결과 반환

cub_server가 SQL을 처리하고 결과를 CAS로 보냅니다. CAS는 이를 브로커를 통해 앱에 전달합니다. 트랜잭션이 완료되면 CAS는 다시 IDLE 상태로 돌아가 다음 요청을 기다립니다.

7. 데이터베이스 볼륨 구조

프로세스 구조를 이해했다면, 데이터가 실제로 어디에 저장되는지도 함께 알아두는 것이 좋습니다. CUBRID 데이터베이스는 크게 세 가지 볼륨으로 구성됩니다.

볼륨 유형	설명	운영 시 주의점
Permanent Volume	테이블 데이터(heap file), 인덱스(b-tree), 시스템 데이터 저장. DB 재시작 후에도 유지됩니다.	디스크 여유 공간 부족 시 서버가 중단될 수 있습니다. `cubrid spacedb`로 주기적으로 확인하세요.
Temporary Volume	정렬, GROUP BY, ORDER BY, Subquery, Sort-Merge Join 등의 중간 결과 저장 공간.	대량 정렬 작업이 많으면 갑자기 증가할 수 있습니다. 급증 시 해당 쿼리를 튜닝하거나 `temp_file_memory_size_in_pages` 조정을 고려합니다.
Backup Volume	`cubrid backupdb` 수행 시 생성되는 백업 데이터.	백업 볼륨과 DB 볼륨을 같은 디스크에 두면 의미가 없습니다. 별도 경로나 외부 스토리지를 사용하세요.
Active Log	최근 변경 트랜잭션 로그. DB 장애 시 복구에 사용됩니다.	로그 볼륨 크기는 DB 생성 시 `--log-volume-size`로 정해집니다. 이후 변경은 어렵습니다.
Archive Log	Active Log가 순환되기 전 보관되는 로그. HA 복제 및 특정 시점 복구에 활용됩니다.	HA 환경에서 복제 지연이 생기면 Archive Log가 쌓여 디스크를 가득 채울 수 있습니다. 보관 정책을 반드시 설정하세요.

WARN

흔한 장애 패턴: Archive Log 보관 정책을 설정하지 않으면 로그가 계속 쌓여 디스크를 꽉 채우는 경우가 있습니다. 특히 HA 구성에서 슬레이브 노드의 복제가 지연되고 있을 때 이 문제가 자주 발생합니다. DB 볼륨, Temporary Volume, Archive Log를 묶어서 모니터링하는 것을 권장합니다.

8. 다른 DBMS와 비교했을 때 CUBRID 구조의 특징

MySQL이나 PostgreSQL에서 CUBRID로 넘어올 때 가장 먼저 적응이 필요한 부분이 바로 이 브로커 구조입니다. 일반적인 DBMS에서는 앱이 DB 서버의 Listener에 직접 접속하는 반면, CUBRID는 브로커가 명확히 중간에 자리합니다.

항목	CUBRID	MySQL / PostgreSQL
기본 연결 구조	앱 → Broker(cub_broker → cub_cas) → cub_server	앱 → DB 서버 직접 연결
커넥션 풀링	Broker 기본 내장 (CAS pool)	별도 솔루션 필요 (PgBouncer, ProxySQL 등)
SQL 로그 추적	CAS별 SQL 로그 파일 자동 생성	slow query log 또는 general log 별도 설정 필요
다중 인터페이스 지원	JDBC, ODBC, CCI, PHP, Python, Node.js 등 모두 브로커 경유	드라이버별로 DB 서버에 직접 연결
HA 페일오버	브로커가 우선순위에 따라 자동 서버 전환	별도 미들웨어(HAProxy 등) 또는 앱 레벨 처리 필요
접속 제어 (ACL)	cubrid_broker.conf에서 IP/DB 단위 제어	DB 레벨 사용자 권한으로 제어
장애 분석 지점	Broker 계층과 DB 서버 계층을 분리해서 봐야 함	대체로 DB 서버 한 곳만 확인하면 됨

CUBRID 구조의 가장 큰 장점은 브로커 덕분에 커넥션 풀링, SQL 추적, 접속 제어, HA 페일오버를 별도 솔루션 없이 내장으로 처리할 수 있다는 점입니다. 반대로 익혀야 할 개념이 하나 더 늘고, 장애 분석 시 확인해야 할 계층도 하나 더 있습니다. 이를 알고 있으면 CUBRID를 훨씬 빠르게 다룰 수 있습니다.

9. 장애 분석 시 어떤 프로세스를 먼저 확인할까

CUBRID 장애 분석에서 가장 중요한 원칙은 "문제가 브로커 계층인가, DB 서버 계층인가"를 먼저 구분하는 것입니다. CUBRID 매뉴얼 트러블슈팅 챕터에서도 슬로우 쿼리 원인을 파악할 때 "앱-브로커 구간인지, 브로커-DB 구간인지 먼저 확인하라"고 명시합니다.

시나리오별 확인 순서

접속 자체가 안 될 때

Broker 프로세스 기동 여부 확인

cubrid broker status로 브로커가 살아 있는지 먼저 확인합니다. 브로커가 내려가 있으면 cub_server가 정상이어도 접속이 불가합니다.

CAS 상태 확인

cubrid broker status -b로 CAS 개수와 상태를 확인합니다. 모든 CAS가 BUSY 상태이면 MAX_NUM_APPL_SERVER 값을 늘려야 합니다.

DB 서버 프로세스 기동 여부 확인

브로커가 정상이라면 cubrid server status 으로 cub_server 상태를 확인합니다.

네트워크·방화벽 확인

위 세 가지가 모두 정상이라면 브로커 포트(BROKER_PORT) 접근 가능 여부와 방화벽 설정을 확인합니다.

SQL 응답이 느릴 때

→ 앱 로그에는 슬로우 쿼리가 있는데 CAS SQL 로그($CUBRID/log/broker/)에는 없으면 → 앱-브로커 구간 문제(네트워크 지연, CAS 재시작 등)
→ 양쪽에 모두 기록되어 있으면 → DB 서버 레벨 문제(실행 계획 불량, 인덱스 미사용, Lock 경합 등)
→ BUSY CAS 수가 비정상적으로 많으면 → CAS 수 부족 또는 DB 서버 응답 지연으로 CAS 대기 중

INFO

CAS ID로 SQL 로그 추적하는 방법: JDBC 사용 시 CUBRIDConnection.toString()을 호출하면 127.0.0.1:33000,1,12916 형태로 브로커 호스트, CAS ID, CAS PID가 반환됩니다. CAS ID가 1이라면 SQL 로그 파일은 broker_name_1.sql.log에 있습니다. 에러가 발생한 쿼리를 빠르게 추적할 때 유용합니다.

HA 환경에서 페일오버가 발생했을 때

→ 페일오버 이벤트는 $CUBRID/log/.cub_master.err에 기록됩니다. 이 로그를 가장 먼저 확인하세요.
→ 스플릿 브레인(Split-Brain) 상황이면 마스터 노드가 여러 개 감지되어 하나가 스스로 종료됩니다. 마스터 에러 로그에서 확인할 수 있습니다.
→ 복제 지연이 심하면 Archive Log가 삭제되기 전에 반영되지 못해 복구 불가 상황이 생길 수 있습니다. Replication 지연 모니터링을 함께 구성하는 것을 권장합니다.

10. 운영 현장에서 자주 쓰는 기본 명령어

아래 명령어는 CUBRID 11.4 기준이며, 실제 운영 환경에 따라 옵션과 출력 형태가 다를 수 있습니다. 상세 내용은 공식 매뉴얼 프로세스 제어 챕터를 참고하세요.

# 전체 서비스 상태 한 번에 확인
cubrid service status

# 특정 DB 서버 상태 확인
cubrid server status 

# 브로커 기본 상태 (CAS 수, 포트, 상태 등)
cubrid broker status

# 브로커 상세 상태 (-b: BUSY CAS 수, 처리 쿼리 수 포함)
cubrid broker status -b

# 현재 실행 중인 브로커 파라미터 설정 확인
cubrid broker info

# DB 볼륨 여유 공간 확인
cubrid spacedb

실제 운영에서 cubrid broker status -b 결과를 해석할 때는 아래 항목을 중심으로 봅니다.

→ AS(Ns-B): N초 이상 BUSY 상태인 CAS 수. 이 숫자가 많으면 장시간 쿼리 또는 CAS 부족 상황입니다.
→ ERR-Q: 에러가 발생한 쿼리 수. 급증하면 특정 쿼리나 연결 문제를 의심합니다.
→ #CONNECT / #REJECT: 브로커 기동 후 총 접속 수와 ACL로 거부된 접속 수.
→ JQ: Job Queue 대기 수. 이 값이 높으면 처리할 CAS가 없어서 요청이 쌓이는 것입니다.

11. 정리

여기까지 읽으셨다면 CUBRID 구조의 핵심을 이해하셨을 겁니다. 마지막으로 한 문장으로 정리하면 이렇습니다.

TIP

CUBRID는 애플리케이션 클라이언트 → Broker(cub_broker + cub_cas) → DB 서버(cub_master + cub_server)의 3계층 구조로 동작합니다. Broker는 연결 관리와 요청 중계를 담당하고, DB 서버는 실제 데이터 저장, SQL 처리, 트랜잭션과 복구를 담당합니다.

계층	프로세스	핵심 역할
Client	JDBC / ODBC / CCI 등	애플리케이션에서 DB 접속 요청
Broker	`cub_broker`	앱 연결 수신, 공유 메모리 조회, 가용 CAS에 전달
Broker	`cub_cas`	DB 서버 클라이언트 역할, SQL 처리 요청 전달
DB Server	`cub_master`	포트 감청, cub_server로 연결 라우팅
DB Server	`cub_server`	SQL 실행, 트랜잭션, 잠금, 복구
Storage	Volume / Log	데이터, 임시 데이터, 트랜잭션 로그, 백업 저장

장애 분석의 출발점은 항상 동일합니다. 접속 문제는 Broker부터, SQL 지연은 Broker와 DB 서버를 함께, 데이터 정합성 문제는 Log와 트랜잭션 관점으로 접근하세요. 이 세 가지 원칙을 머릿속에 넣어두면 어떤 장애가 오더라도 빠르게 원인을 좁혀나갈 수 있습니다.

이 글은 CUBRID 11.4 공식 매뉴얼의 시스템 아키텍처, 시스템 설정, 프로세스 제어, 트러블슈팅 챕터를 기반으로 작성하였습니다.
더 깊은 내용은 공식 매뉴얼의 각 챕터를 직접 참고하시고, 실제 운영 사례나 궁금한 점은 CUBRID 커뮤니티를 활용해보세요.

CUBRID DBeaver External 플러그인: DBeaver에서 CUBRID 전용 기능 확장

hwanyseo — Fri, 08 May 2026 15:50:15 +0900

CUBRID DBeaver External 플러그인 : DBeaver에서 CUBRID 전용 기능 확장

DBeaver Community Edition은 다양한 데이터베이스를 하나의 도구에서 다룰 수 있게 해 주는 범용 클라이언트입니다.

이 글에서는 DBeaver에서 추가 설치를 하여 CUBRID 전용 추가 기능을 제공하는 CUBRID DBeaver External 플러그인 (https://github.com/CUBRID/cubrid-dbeaver-plugins) 패키지를 소개합니다.

설치 시 필요한 모듈만 골라 설치할 수 있으며,

설치 후에는 DBeaver UI에 바로 통합되어 테이블 정의 Excel 내보내기, LoadDB 형식 내보내기, CUBRID Manager·Admin 연결 정보 가져오기의 작업을 할 수 있습니다.
추후 필요한 기능을 추가적으로 확장 할 계획을 가지고 있습니다.

지원 버전

- DBeaver Community Edition 25.3.5 이상 권장

- CUBRID Server (10.2, 11.0, 11.2, 11.3 그리고 11.4)

플러그인 설치 방법

DBeaver가 설치되어 있어야 합니다. 설치되어 있지 않다면 DBeaver 공식 사이트(https://dbeaver.io/)에서 Community Edition을 받을 수 있습니다.

1. Update Site로 설치

1. DBeaver를 실행합니다.

2. 메뉴에서 Help → Install New Software... 를 선택합니다.

3. Add... 를 누르고, 아래 주소를 Update Site로 등록합니다.

`https://ftp.cubrid.org/cubrid_labs/cubrid-dbeaver-external/latest/`

4. 목록에서 원하는 CUBRID 기능(플러그인)을 선택합니다.

5. Next 를 누르고 안내에 따라 설치를 완료합니다.

6. 설치 후 DBeaver를 재시작합니다.

2. ZIP으로 오프라인 설치

GitHub Releases(https://github.com/CUBRID/cubrid-dbeaver-plugins/releases)에 제공되는 `CUBRID-DBeaver-external-*.zip` 를 사용할 수도 있습니다.
Help → Install New Software... 에서 Add... 에서 로컬 파일을 지정하여 설치합니다.

이후 Update site 설치와 동일하게 진행하면 됩니다.

설치가 끝나면 이후 섹션에서 설명하는 기능들이 DBeaver UI에서 바로 사용 가능합니다.

자세한 설치 방법은 Wiki HOME(https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki)을 참고하세요.

기능 1: 테이블 정의를 Excel로 내보내기 (테이블 명세서 Excel 출력)

CUBRID 테이블 목록, 컬럼 정의, 키·인덱스, DDL 등을 Excel 파일로 문서화할 수 있습니다.

기존 CA/CM에서 제공하는 기능으로 동일한 Format을 지원합니다.

실행 방법

1. DBeaver에서 CUBRID 데이터베이스에 연결합니다.

2. Database Navigator에서 해당 CUBRID 데이터베이스를 우클릭합니다.

3. Export table definitions to Excel 메뉴를 선택합니다.

마법사에서 할 일

1. 내보낼 경로: Browse... 로 로컬 저장 위치를 지정합니다.

2. 파일 이름: 원하는 Excel 파일 이름을 입력하거나 기본값을 사용합니다.

3. 문서 스타일: Simple 또는 Generic 중 형식을 선택합니다.

4. Finish 를 눌러 내보내기를 실행합니다.

완료되면 확인 메시지가 표시되고, 지정한 위치에 Excel 파일이 생성됩니다.
자세한 화면 예시는 Wiki - Export Excel Feature (https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki/Export-Excel-Feature)를 참고하세요.

기능 2: LoadDB 형식으로 내보내기

스키마·데이터를 CUBRID LoadDB 형식으로 내보내 다른 CUBRID 환경으로 이전하거나 백업 용도로 활용할 수 있습니다.

실행 방법

아래 중 필요한 범위만 골라 같은 메뉴로 진입할 수 있습니다.

- 전체 DB : 연결된 CUBRID 데이터베이스를 우클릭 → Export to LoadDB

- 스키마 폴더 : Schemas 폴더를 우클릭 → Export to LoadDB

- 특정 스키마 : 해당 스키마를 우클릭 → Export to LoadDB (해당 스키마 테이블만)

마법사 흐름

1. 테이블 선택: 내보낼 테이블을 고르거나 Select All 로 전체 선택 후 Next.

2. 옵션 설정

- Export Options: 스키마, 인덱스, 트리거, 데이터 포함 여부 (기본은 모두 선택).

- Export Location: 결과 파일을 둘 디렉터리.

- Data Options: 문자 집합(Charset), 스키마 파일 분할(Split Schema File), Auto-increment 값 반영 등.

3. 확인 화면에서 설정을 검토한 뒤 Finish. 작업은 백그라운드에서 진행됩니다.

지정한 위치에 LoadDB 형식으로 파일이 생성되며, 다른 CUBRID 환경에 적재할 수 있는 상태로 준비됩니다.
더 자세한 설명은 Wiki - Export LoadDB Feature (https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki/Export-LoadDB-Feature)를 참고하세요.

기능 3: CUBRID Manager·Admin에서 연결정보 가져오기

CUBRID Manager(CM) 또는 CUBRID Admin(CA) 에 저장된 연결 설정을 DBeaver로 옮겨, 호스트·포트·사용자 등을 다시 입력하지 않아도 됩니다.
CA의 연결정보에 경우 포트정보가 없어 '33000'포트가 자동 입력됩니다.

지원 파일 형식

- 확장자: `.prefs`

CA/CM에서 사용하는 설정 파일 위치 예시는 다음과 같습니다.

- CA·CM Admin 모드:

`$WORKSPACE/.metadata/org.eclipse.core.runtime/com.cubrid.cubridmanager.ui.prefs`

- CM Query 모드:

`$WORKSPACE/.metadata/org.eclipse.core.runtime/com.cubrid.cubridquery.ui.prefs`

실행 방법 (Wizard 열기)

다음 중 편한 방법을 선택하면 Import CUBRID Connection 마법사가 열립니다.

1. File → Import 에서 CUBRID 를 펼치고 Import Connection 선택.

2. 툴바에서 Add Database Connection 옆 화살표 → Import CUBRID Connection.

3. Database Navigator 빈 곳을 우클릭 → 관련 메뉴 선택.

4. 기존 CUBRID 연결을 우클릭 → 관련 메뉴 선택.

5. Browse... 로 위 `.prefs` 파일을 선택하고 Next.

6. 파일에 들어 있는 연결 목록에서 가져올 항목에 체크합니다.

7. Finish 로 완료합니다.

가져온 연결은 Database Navigator 에 표시되며, 호스트·포트·사용자 정보는 유지됩니다.

안내: 비밀번호는 가져오지 않습니다. 처음 연결할 때 비밀번호를 입력하면 됩니다.

상세 안내는 Wiki - Import connections from CM-CA (https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki/Import-connections-from-CM-CA)를 참고하세요.

마무리

CUBRID DBeaver External은 DBeaver에서 CUBRID 전용 기능(테이블 명세서 Excel 출력, LoadDB 이전, CM/CA 연결 이관)을 한곳에서 처리하도록 돕는 플러그인 모음입니다.

설치는 공개 Update Site 또는 GitHub Releases를 통해 할 수 있으며,

기능별 세부 단계와 스크린샷은 프로젝트 Wiki(https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki)에서 확인 할 수 있습니다.

참고 URL

- CUBRID DBeaver 플러그인 GitHub : https://github.com/CUBRID/cubrid-dbeaver-plugins

- 플러그인 Wiki (기능별 상세 안내) : https://github.com/CUBRID/cubrid-dbeaver-plugins/wiki

- Offline용 ZIP file : https://github.com/CUBRID/cubrid-dbeaver-plugins/releases

Kubernetes 환...

airnet — Wed, 06 May 2026 23:53:30 +0900

Kubernetes 환경에서 CUBRID 운영하기: CUBRID Operator 가이드

이 글은 Kubernetes 환경에서 CUBRID 데이터베이스를 배포하고 운영하는 방법을 설명하며, CUBRID Operator의 기본 개념부터 실제 배포와 운영 흐름까지 단계적으로 다룹니다.

1. CUBRID Operator란?

Kubernetes와 Operator

Kubernetes는 컨테이너 애플리케이션을 선언적으로 배포하고 운영하는 플랫폼입니다. Operator는 특정 애플리케이션의 운영 방식을 Kubernetes 컨트롤러로 자동화한 도구입니다.

Kubernetes와 Operator에 대한 자세한 내용은 Kubernetes 공식 문서의 Kubernetes 개요와 Operator pattern을 참고하세요.

CUBRID Operator의 역할

CUBRID Operator는 Kubernetes에서 CUBRID 데이터베이스의 배포와 운영을 자동화합니다. 사용자는 CubridDB 리소스에 원하는 구성을 선언하고, Operator는 필요한 Kubernetes 리소스를 생성하고 관리합니다.

CubridDB 리소스

이 글에서는 CUBRID 서버를 정의하는 CubridDB 리소스를 중심으로 설명합니다.

• CubridDB: CUBRID 서버(브로커, 스토리지, HA·CMS 노출 방식 등)를 정의합니다.

Operator는 선언한 “원하는 상태”에 맞춰 CUBRID 파드를 실행하고, StatefulSet, 외부 접속용 Service, 필요 시 Ingress, 데이터 보관용 PVC 등을 관리합니다.

데이터베이스 컨테이너, 네트워크, 스토리지, 서비스 설정도 CubridDB 리소스로 함께 관리할 수 있습니다. 예를 들어 HA를 활성화하면 복제 구성이 반영되고, 브로커를 정의하면 클라이언트 접속용 서비스가 생성됩니다. CMS(CUBRID Manager Server)는 NodePort 또는 Ingress 방식으로 노출할 수 있습니다.

Operator의 동작 방식

Operator의 핵심은 Kubernetes의 reconciliation loop입니다. 사용자가 CubridDB 같은 커스텀 리소스를 생성하거나 수정하면 Operator가 이를 감지하고, 실제 클러스터 상태가 선언한 원하는 상태와 일치하도록 필요한 리소스를 계속 조정합니다. 이 과정에서 CUBRID 파드, 서비스, 스토리지, Ingress, HA 관련 리소스가 자동으로 생성되거나 갱신됩니다.

2. 주요 기능과 특징

CUBRID Operator의 주요 기능은 다음과 같이 정리할 수 있습니다.

데이터베이스 배포 사용할 CUBRID 이미지, CPU·메모리 리소스, 업데이트 방식, 브로커, 스토리지, CMS 설정을 CubridDB 리소스에 선언할 수 있습니다. Operator는 이 설정을 바탕으로 CUBRID 파드와 필요한 Kubernetes 리소스를 생성하고 관리합니다.

고가용성(HA) replication 설정을 통해 복제를 활성화하고 replica 수와 HA 모드를 지정할 수 있습니다. master-slave 모드는 하나의 CubridDB 안에서 마스터·슬레이브 구성을 만들고, replica 모드는 다른 CubridDB 인스턴스를 cubridRef로 참조해 확장하는 방식으로 사용할 수 있습니다.

서비스 설정 관리 브로커, HA용 Headless Service, CMS 관련 서비스는 CubridDB 설정을 기준으로 관리됩니다. Kubernetes Service를 직접 수정하더라도 Operator가 다시 CubridDB에 선언된 상태로 조정할 수 있으므로, 운영 변경은 CubridDB 리소스를 수정하는 방식으로 관리하는 것이 좋습니다.

스토리지 데이터, 로그, 백업, 설정 영역을 목적별 스토리지로 나누어 구성할 수 있습니다. StorageClass를 사용하면 동적으로 볼륨을 생성할 수 있고, 미리 준비한 PV에 연결하는 정적 프로비저닝 방식도 사용할 수 있습니다.

브로커 상태 반영 파드가 실행 중이어도 브로커 프로세스가 준비되지 않았을 수 있습니다. Operator는 실제로 요청을 처리할 준비가 된 브로커 파드만 트래픽 대상에 포함되도록 Endpoints를 조정하고, 상태를 주기적으로 확인합니다.

3. CUBRID Operator 설치하기

Operator는 Helm 차트로 설치하는 방법과 Kubernetes 매니페스트를 직접 적용하는 방법을 제공합니다. 빠른 검증에는 매니페스트 설치가 간단하고, 운영 환경처럼 네임스페이스, 권한, Webhook 인증서 등 설치 옵션

kubectl get nodes

을 조정해야 하는 경우에는 Helm 설치가 더 적합합니다.

Kubernetes, Helm, kubectl의 지원 버전은 Operator 버전에 따라 달라질 수 있으므로, 실제 설치 시에는 사용하는 Operator 버전의 설치 문서를 함께 확인하는 것이 좋습니다.

아래 예제는 동적 PVC 생성을 위한 StorageClass로 Longhorn을 사용하고, CMS를 Ingress로 노출하는 경우를 기준으로 설명합니다. 이미 클러스터에 사용할 StorageClass나 Ingress Controller가 준비되어 있다면 해당 단계는 환경에 맞게 대체하거나 생략할 수 있습니다.

3.1 예제 환경 준비: Helm, StorageClass, Ingress Controller

Helm 설치

이 글에서는 Operator, Longhorn, ingress-nginx를 Helm으로 설치하는 흐름을 사용합니다. 작업 환경에 helm 명령이 준비되어 있어야 합니다.

Linux 환경에서는 Helm 공식 설치 스크립트를 사용할 수 있습니다.

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

설치 후 버전을 확인합니다.

helm version

Helm은 kubectl과 같은 클러스터 접속 설정(kubeconfig) 을 사용합니다. 아래 명령이 동작하는지 확인후 다음 단계로 진행해야 합니다.

kubectl get nodes

Longhorn 설치 (테스트용 동적 PVC 예시)

PVC(PersistentVolumeClaim)를 자동으로 만들려면 클러스터에 StorageClass를 제공하는 구성이 필요합니다. 테스트 환경에서는 Longhorn을 쓰면 longhorn이라는 StorageClass를 쉽게 쓸 수 있습니다.

helm repo add longhorn https://charts.longhorn.io

helm repo update

kubectl create namespace longhorn-system

helm install longhorn longhorn/longhorn \

  --namespace longhorn-system

설치가 되었는지 확인합니다.

kubectl get pods -n longhorn-system

kubectl get storageclass

목록에 longhorn이 보이면, 아래 CubridDB 예제의 storageClassName: longhorn이 동작합니다. 운영 환경에서는 클라우드 또는 사내 표준 StorageClass를 사용하고, 아래 예제의 storageClassName만 해당 이름으로 변경하면 됩니다.

ingress-nginx 설치 (Ingress 방식 CMS 예시)

CMS를 Ingress로 노출하려면 클러스터에 Ingress Controller가 설치되어 있어야 합니다. 아래의 내용은 ingress-nginx를 Helm으로 설치하는 예입니다.

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

helm repo update

kubectl create namespace ingress-nginx

helm install ingress-nginx ingress-nginx/ingress-nginx \

  --namespace ingress-nginx

설치 후 컨트롤러와 외부로 열린 포트를 확인합니다.

kubectl get pods -n ingress-nginx

kubectl get svc ingress-nginx-controller -n ingress-nginx

3.2 Helm으로 Operator 설치

CRD(커스텀 리소스 정의) 차트와 Operator 본체 차트를 순서대로 설치합니다. 운영 환경에서는 필요에 따라 --version 으로 설치할 차트 버전을 고정할 수 있습니다.

helm repo add cubrid https://helm.cubrid.org/cubrid-operator

helm repo update

helm install cubrid-operator-crds cubrid/cubrid-operator-crds

kubectl get crds | grep cubrid

helm install cubrid-operator cubrid/cubrid-operator \

  --namespace cubrid \

  --create-namespace

설치가 끝났는지 확인합니다.

kubectl get pods -n cubrid

kubectl get services -n cubrid

helm list -n cubrid

Webhook 인증서는 기본적으로 Operator 내부 방식으로 관리됩니다. 클러스터에 외부 cert-manager가 이미 설치되어 있고 이를 사용하려면, Operator를 처음 설치할 때 Helm 값으로 지정합니다.

helm install cubrid-operator cubrid/cubrid-operator \

  --namespace cubrid \

  --create-namespace \

  --set webhook.certManagerType=external

3.3 매니페스트로 Operator 설치

Kubernetes 매니페스트를 직접 적용하는 방식입니다. 별도 Helm 값 조정 없이 한 번에 설치할 수 있어 빠른 검증에 적합합니다. 아래 예시는 v1.0 매니페스트를 사용합니다.

kubectl apply -f https://raw.githubusercontent.com/CUBRID/cubrid-operator/v1.0/deploy/manifests/cubrid-operator.yaml

설치 상태를 확인합니다.

kubectl get crd | grep cubrid

kubectl get pods -n cubrid

kubectl get services -n cubrid

설치가 정상적으로 진행되지 않으면 Operator와 Webhook 로그를 확인합니다.

kubectl logs -n cubrid deployments/cubrid-operator-dep

kubectl logs -n cubrid deployments/cubrid-operator-webhook-dep

매니페스트 설치는 기본 설정으로 빠르게 검증할 때 적합합니다. Webhook 인증서 방식이나 RBAC 같은 세부 옵션을 조정해야 하거나 외부 cert-manager를 사용하려면 Helm 설치를 권장합니다.

4. 단일 CubridDB 배포와 기본 접속

Operator가 준비되었으면 CubridDB 리소스를 생성해 CUBRID 인스턴스를 배포할 수 있습니다. 아래는 Longhorn StorageClass로 PVC를 생성하고, 브로커를 NodePort로 노출하는 단일 인스턴스 예시입니다.

apiVersion: k8s.cubrid.com/v1

kind: CubridDB

metadata:

  name: my-cubrid-db

spec:

  image: cubrid/cubrid

  initContainerImage: busybox

  replication:

    enable: false

  broker:

    - name: broker-svc

      port: 30000

      servicePort: 30100

      serviceType: NodePort

  storage:

    - mountPath: /home/cubrid/CUBRID/databases

      name: database-storage

      type: database-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/log

      name: logs-storage

      type: logs-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/backupdb

      name: backupdb-storage

      type: backup-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/conf

      name: conf-storage

      type: conf-storage-type

      size: 100Mi

      storageClassName: longhorn

이 예제에서 broker.port는 CUBRID 컨테이너 안에서 사용하는 브로커 포트이고, broker.servicePort는 클러스터 밖에서 접속할 때 사용할 NodePort입니다. storageClassName: longhorn은 Longhorn StorageClass를 사용해 데이터, 로그, 백업, 설정 영역의 PVC를 동적으로 생성하겠다는 의미입니다.

위 내용을 my-cubrid-db.yaml 파일로 저장한 뒤 적용합니다.

kubectl apply -f my-cubrid-db.yaml

kubectl get cubriddb

kubectl get pods

kubectl get svc

kubectl get pvc

위 명령은 CubridDB를 적용한 네임스페이스 기준으로 실행합니다. 다른 네임스페이스에 생성했다면 -n 옵션을 함께 사용합니다.

4.1 애플리케이션에서 브로커로 접속하기

애플리케이션은 브로커 서비스를 통해 CUBRID 데이터베이스에 접속합니다. CubridDB의 broker 설정에는 브로커 서비스 이름, 컨테이너 내부 브로커 포트, 외부 접속에 사용할 NodePort를 지정합니다.

broker:

  - name: s-broker1-svc

    port: 30000

    servicePort: 30300

    serviceType: NodePort

  - name: s-broker2-svc

    port: 33000

    servicePort: 30301

    serviceType: NodePort

port는 CUBRID 컨테이너 내부에서 브로커가 사용하는 포트이고, servicePort는 serviceType: NodePort일 때 클러스터 외부에서 접속할 포트입니다. 위 예라면 첫 번째 브로커는 <노드 IP>:30300, 두 번째 브로커는 <노드 IP>:30301로 접속할 수 있습니다.

kubectl get svc s-broker1-svc

kubectl describe svc s-broker1-svc

CUBRID JDBC를 사용할 때는 대략 다음 형태입니다.

jdbc:cubrid::30300::::

예를 들어 노드 IP가 192.168.10.20, DB 이름이 demodb라면 다음과 같습니다.

jdbc:cubrid:192.168.10.20:30300:demodb:::

DBeaver에서는 아래처럼 URL 방식으로 위 문자열을 넣어 연결할 수 있습니다.

4.2 CUBRID Admin에서 CMS 접속하기

CMS는 CUBRID 서버를 관리하기 위한 관리 인터페이스입니다. CubridDB의 cmsService 설정에서 NodePort 또는 Ingress 방식으로 노출할 수 있습니다. 운영 중 노출 방식을 변경하면 서비스와 접속 정보가 함께 바뀔 수 있으므로, 초기 배포 시 접속 방식을 미리 정하는 것이 좋습니다.

NodePort 방식

별도 도메인 없이 노드 IP와 포트로 CMS에 접속합니다.

cmsService:

  type: NodePort

  startPort: 31000

  port: 8001

HA 구성처럼 파드가 여러 개이면 파드마다 CMS용 서비스가 생성되고, startPort부터 포트 번호가 순차적으로 배정됩니다.

kubectl get svc | grep cms

CUBRID Admin에서 예시는 다음과 같습니다.

• 호스트 이름: 구분하기 쉬운 이름(예: ha-ms-0)

• 호스트 주소: Kubernetes 노드 IP(예: 192.168.10.20)

• 연결 포트: CMS용 NodePort(예: 31000)

• 사용자 이름·CM 비밀번호: 초기에는 보통 admin / admin(환경에 따라 변경됨)

Ingress 방식

도메인 형태로 CMS에 접속하는 방식입니다. 클러스터에 Ingress Controller가 준비되어 있어야 합니다.

cmsService:

  type: Ingress

파드별 CMS 호스트 이름은 대략 다음 규칙으로 생성됩니다.

{pod-name}.{namespace}.cms.cubrid.com

예를 들어 기본 네임스페이스의 ha-ms-0 파드라면 CUBRID Admin에 다음과 같이 입력할 수 있습니다.

• 호스트 이름: ha-ms-0

• 호스트 주소: ha-ms-0.default.cms.cubrid.com

• 연결 포트: Ingress Controller의 HTTPS NodePort 또는 외부 HTTPS 포트, 예: 31586

• 사용자 이름: admin

• CM 비밀번호: admin 또는 운영자가 변경한 CMS 비밀번호

Ingress 방식에서는 접속하는 PC가 위 호스트 이름을 Ingress Controller가 있는 주소로 해석할 수 있어야 합니다. 테스트 환경에서는 DNS 대신 hosts 파일을 사용할 수도 있습니다.

kubectl get ingress

# Ingress에 등록된 CMS 호스트 확인

kubectl get ingress --cms-ingress \

  -o jsonpath='{.spec.rules[*].host}'

# Ingress Controller HTTPS NodePort 확인

kubectl get svc ingress-nginx-controller -n ingress-nginx \

  -o jsonpath='{.spec.ports[?(@.name=="https")].nodePort}'

Windows에서 CUBRID Admin을 쓰신다면 보통 아래 파일을 수정합니다.

C:\Windows\System32\drivers\etc\hosts

메모장을 관리자 권한으로 실행한 뒤, 파일 열기에서 “모든 파일”을 선택해 hosts를 엽니다. Ingress Controller가 위치한 노드 IP가 192.168.10.20이라면 예시는 다음과 같습니다.

168.10.20  ha-ms-0.default.cms.cubrid.com

168.10.20  ha-ms-1.default.cms.cubrid.com

168.10.20  ha-ms-2.default.cms.cubrid.com

168.10.20  ha-rep-0.default.cms.cubrid.com

저장한 뒤 이름이 기대한 IP로 나오는지 확인해 보세요.

ping ha-ms-0.default.cms.cubrid.com

ping 응답이 막혀 있어도, 표시되는 IP가 Ingress Controller 주소와 같으면 hosts 설정은 적용된 경우가 많습니다. 운영 환경에서는 PC마다 hosts 파일을 수정하기보다 사내 DNS에 호스트를 등록하는 편이 관리하기 쉽습니다.

4.3 HA와 스토리지 설정 개요

HA가 필요하면 replication.enable을 켜고 replica 수와 HA 모드를 지정합니다. master-slave 모드는 하나의 CubridDB 안에서 HA 그룹을 구성하고, replica 모드는 master-slave로 구성된 다른 CubridDB를 cubridRef로 참조해 확장하는 방식입니다.

데이터, 로그, 백업, 설정 영역은 목적별 스토리지로 나누어 두면 용량 관리와 백업 정책을 정리하기 쉽습니다.

storage:

  - mountPath: /home/cubrid/CUBRID/databases

    name: database-storage

    type: database-storage-type

    size: 10Gi

    storageClassName: longhorn

  - mountPath: /home/cubrid/CUBRID/backupdb

    name: backupdb-storage

    type: backup-storage-type

    size: 10Gi

    storageClassName: longhorn

구체적인 master-slave와 replica 배포 예시는 다음 절에서 단계별로 다룹니다.

5. HA 배포 예제: Master-Slave와 Replica

이 절에서는 replication.enable: true를 사용해 master-slave 그룹과 replica 그룹을 구성하는 예제를 살펴봅니다. 예제는 ha-ms를 먼저 배포한 뒤, ha-rep가 cubridRef로 ha-ms를 참조하도록 구성합니다.

• ha-ms를 먼저 배포해 master-slave 그룹을 구성

• ha-rep를 배포해 ha-ms를 참조하는 replica 그룹 구성

• 상태 확인, 브로커 접속 확인, CMS 접속 확인

5.1 Master-Slave 배포 예시 (ha-ms)

아래 내용을 cubrid_ha_ms.yaml 파일로 저장합니다. 이 예제의 replicas: 2는 ha-ms-0, ha-ms-1 두 파드로 master-slave 그룹을 구성하는 설정입니다.

apiVersion: k8s.cubrid.com/v1

kind: CubridDB

metadata:

  name: ha-ms

spec:

  image: cubrid/cubrid:latest

  initContainerImage: busybox

  replication:

    enable: true

    replicas: 2

    hamodeType:

      type: master-slave

  cmsService:

    type: Ingress

  broker:

    - name: ms-broker1-svc

      port: 30000

      servicePort: 30100

      serviceType: NodePort

  storage:

    - mountPath: /home/cubrid/CUBRID/databases

      name: database-storage

      type: database-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/log

      name: logs-storage

      type: logs-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/backupdb

      name: backupdb-storage

      type: backup-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/conf

      name: conf-storage

      type: conf-storage-type

      size: 100Mi

      storageClassName: longhorn

적용:

kubectl apply -f cubrid_ha_ms.yaml

5.2 Replica 배포 예시 (ha-rep)

아래 내용을 cubrid_ha_rep.yaml 파일로 저장합니다. ha-rep는 cubridRef로 앞에서 만든 ha-ms를 참조합니다.

apiVersion: k8s.cubrid.com/v1

kind: CubridDB

metadata:

  name: ha-rep

spec:

  image: cubrid/cubrid:latest

  initContainerImage: busybox

  replication:

    enable: true

    replicas: 1

    hamodeType:

      type: replica

      cubridRef:

        name: ha-ms

  cmsService:

    type: Ingress

    port: 8001

  broker:

    - name: rep-broker1-svc

      port: 30000

      servicePort: 30200

      serviceType: NodePort

  storage:

    - mountPath: /home/cubrid/CUBRID/databases

      name: database-storage

      type: database-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/log

      name: logs-storage

      type: logs-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/backupdb

      name: backupdb-storage

      type: backup-storage-type

      size: 10Gi

      storageClassName: longhorn

    - mountPath: /home/cubrid/CUBRID/conf

      name: conf-storage

      type: conf-storage-type

      size: 100Mi

      storageClassName: longhorn

적용:

kubectl apply -f cubrid_ha_rep.yaml

5.3 배포 및 HA 상태 확인

먼저 리소스와 파드가 기대한 개수로 올라왔는지 확인합니다.

kubectl get cubriddb

kubectl get pods -o wide

kubectl get svc

kubectl get ingress

HA 상태를 더 자세히 보려면 describe와 yaml 출력을 함께 보는 것이 좋습니다.

kubectl describe cubriddb ha-ms

kubectl describe cubriddb ha-rep

kubectl get cubriddb ha-ms -o yaml

kubectl get cubriddb ha-rep -o yaml

확인 포인트:

• ha-ms는 master-slave 모드로 생성되었는지

• ha-rep는 replica 모드이며 cubridRef.name: ha-ms를 정확히 참조하는지

• 브로커/서비스/Ingress가 함께 생성되었는지

5.4 HA 환경설정 및 CUBRID 실행

ha-ms, ha-rep 파드가 모두 Running 상태라면 실제 DB를 생성하고 HA 모드로 실행해 볼 수 있습니다. 아래 예시는 demodb를 기준으로 진행합니다. 이 절의 CUBRID 명령은 각 파드 안에서 실행합니다. 먼저 kubectl exec로 대상 파드에 접속한 뒤, 파드 내부에서 DB 생성과 HA 프로세스 시작 명령을 실행합니다.

• ha-ms-0에서 demodb 생성 후 HA 설정 반영

kubectl exec -it ha-ms-0 -- /bin/bash

cd $CUBRID_DATABASES

sh ../demo/make_cubrid_demo.sh

cubrid_ha.conf에서 아래 항목을 확인 또는 추가합니다.

cd $CUBRID/conf

vi cubrid_ha.conf

ha_db_list=demodb

• HA 프로세스 시작

cubrid hb start

• ha-ms-1, ha-rep-0에서도 동일하게 cubrid_ha.conf를 확인하고 cubrid hb start를 실행합니다.

• Heartbeat 상태 확인 (ha-ms-0 예시)

cubrid hb status

출력 예시:

@ cubrid heartbeat status

HA-Node Info (current ha-ms-0, state master)

  Node ha-rep-0.ha-rep-headless (priority 32767, state replica)

  Node ha-ms-1.ha-ms-headless (priority 2, state slave)

  Node ha-ms-0.ha-ms-headless (priority 1, state master)

HA-Process Info (master 1112, state master)

  Applylogdb demodb@localhost:/home/cubrid/CUBRID/databases/demodb_ha-ms-1.ha-ms-headless (pid 1402, state registered)

  Copylogdb demodb@ha-ms-1.ha-ms-headless:/home/cubrid/CUBRID/databases/demodb_ha-ms-1.ha-ms-headless (pid 1400, state registered)

  Server demodb (pid 1121, state registered_and_active)

• Kubernetes 리소스 기준 상태 확인

상태 정보:

kubectl get cubriddb

# 또는

kubectl get cubriddbs.k8s.cubrid.com

출력 예시:

NAME            HA MODE   MASTER SERVER   AGE

ha-ms           ON        ha-ms-0         7d

ha-rep          ON        ha-ms-0         7d

상태 상세 정보:

kubectl describe cubriddb ha-ms

출력 예시:

Name:         ha-ms

Namespace:    default

Labels:       

Annotations:  

API Version:  k8s.cubrid.com/v1

Kind:         CubridDB

Metadata:

  Creation Timestamp:  2026-04-23T06:58:27Z

.

.

.

status:

  currentMaster: ha-ms-0

  hamode: "ON"

  lastUpdated: "2026-04-27T20:18:21Z"

  nodeLists:

  - 'ha-ms-0: master'

  - 'ha-ms-1: slave'

  - 'ha-rep-0: replica'

5.5 배포 후 접속 확인

브로커 접속은 앞의 4.1 절에서 설명한 JDBC URL 방식으로 확인할 수 있습니다. CMS 접속은 4.2 절의 NodePort 또는 Ingress 방식에 맞춰 CUBRID Admin에서 확인합니다.

5.6 체크리스트

• ha-rep의 cubridRef.name이 앞에서 만든 master-slave CubridDB 이름(ha-ms)과 일치하는지 확인합니다.

• replication.enable, replication.replicas, hamodeType.type 값이 의도한 HA 구성과 맞는지 확인합니다.

• storageClassName이 클러스터에 존재하고, 생성된 PVC가 Bound 상태인지 확인합니다.

• 브로커와 CMS의 NodePort가 다른 서비스와 충돌하지 않는지 확인합니다.

• Ingress 방식으로 CMS를 사용한다면 DNS 또는 hosts 설정이 Ingress Controller 주소를 가리키는지 확인합니다.

• cubrid_ha.conf의 ha_db_list에 실제 생성한 DB 이름이 들어 있는지 확인합니다.

• 각 HA 파드에서 cubrid hb status로 master, slave, replica 상태를 확인합니다.

kubectl get pvc

kubectl get svc

kubectl get ingress

kubectl get cubriddb

6. 운영 시 고려사항

• 장기 운영 환경에서는 Helm 설치를 기준으로 네임스페이스, RBAC 권한, Webhook 인증서 관리 방식을 명확히 정해 두는 것이 좋습니다.

• 예제의 Longhorn은 테스트용 StorageClass 예시입니다. 운영 환경에서는 클라우드 또는 사내 표준 StorageClass로 변경하세요.

• CMS를 Ingress로 노출한다면 Ingress Controller와 DNS 또는 hosts 설정을 먼저 준비해야 합니다.

• 스토리지는 환경에 맞게 동적 프로비저닝 또는 정적 PV 방식을 선택하고, 데이터·로그·백업·설정 영역의 용량을 분리해 계획하는 것이 좋습니다.

• 브로커와 CMS 서비스는 Kubernetes Service를 직접 수정하기보다 CubridDB 설정을 변경하는 방식으로 관리하세요.

• HA와 브로커 NodePort 번호는 다른 서비스와 충돌하지 않도록 미리 계획하세요.

마무리

이 글에서는 CUBRID Operator의 기본 개념부터 설치, 단일 CubridDB 배포, 브로커와 CMS 접속, HA 구성까지 살펴봤습니다. CUBRID Operator를 사용하면 CUBRID 운영에 필요한 파드, 서비스, 스토리지, Ingress, HA 관련 리소스를 Kubernetes 리소스로 선언하고 일관되게 관리할 수 있습니다.

처음 적용할 때는 단일 인스턴스로 PVC와 브로커 접속을 먼저 확인하고, 이후 운영 요구에 맞춰 HA와 CMS 노출 방식을 단계적으로 확장하는 흐름을 권장합니다. 버전별 세부 옵션과 필드 설명은 CUBRID Operator 공식 문서와 Helm 차트 문서를 함께 확인해 주세요.

CloudBeaver Community에서 CUBRID 사용하기

hwanyseo — Tue, 17 Mar 2026 15:12:34 +0900

CloudBeaver Community에서 CUBRID 사용하기

CloudBeaver는 SQL, NoSQL, 클라우드 데이터베이스를 포함한 다양한 데이터베이스를 지원하며, 웹 브라우저를 통해 모든 데이터베이스에 접근할 수 있습니다.

팀워크에 최적화된 CloudBeaver는 데이터베이스 작업을 간소화하고 클라우드 기반 환경에서 여러 사용자가 원활하게 협업할 수 있도록 지원합니다.

간단한 라이브 데모는 아래 URL에서 경험해 볼 수 있습니다.

https://demo.cloudbeaver.io/#/

이 글에서는 CloudBeaver Community버전에서

1. CUBRID를 활성화 할 수 있는 Script를 설치하는 방법과

2. CloudBeaver를 설치 할 수 있는 방법을 간략하게 소개합니다.

참고 URL :

CUBRID DBEAVER관련 GitHub : https://github.com/CUBRID/cubrid-dbeaver-plugins

CloudBeaver Docker Hub : https://hub.docker.com/r/dbeaver/cloudbeaver/

CloudBeaver 설치 가이드 : https://github.com/dbeaver/cloudbeaver/wiki/CloudBeaver-Community-deployment-from-docker-image

CloudBeaver Community에서 CUBRID 활성화 하기

CUBRID는 CloudBeaver Enterprise버전에서는 활성화 되어 있지만, CloudBeaver Community버전에서는 기본적으로 비활성화 되어 있습니다.

https://github.com/CUBRID/cubrid-dbeaver-plugins/releases를 공개된 script를 이용해 간단하게 CUBRID를 활성화 할 수 있습니다.

CloudBeaver Community 버전이 설치되어 있어야 하므로 설치되어 있지 않다면 본 글의 'CloudBeaver Community 설치'를 참고하세요.

1. https://github.com/CUBRID/cubrid-dbeaver-plugins/releases에서 cubrid-enabler.sh를 다운로드 받습니다.

2. cubrid-enabler.sh를 Docker container 내부의 /opt/cloudbeaver폴더에 복사합니다.

(Docker Image를 사용하지 않는 경우 cloudbeaver가 설치된 root 폴더에 복사하면 됩니다.)

예) docker cp c:\cubrid-enabler.sh (my-container-name):/opt/cloudbeaver

Docker Desktop UI를 이용하는 경우 컨테이너의 "Files" 탭에서 파일을 우클릭하여 직접 다운로드하거나, 파일을 드래그 앤 드롭하여 업로드할 수도 있습니다.

3. 복사된 폴더로 이동하여 Script를 실행합니다.

chmod +x cubrid-enabler.sh  //실행권한이 없는 경우

./cubrid-enabler.sh

4. 실행 후 아래와 같이 정상적으로 설치완료 메시지를 확인 할 수 있습니다.

./cubrid-enabler.sh

Created folder: /opt/cloudbeaver/drivers/cubrid

CUBRID JDBC driver extracted

Backup original file: /opt/cloudbeaver/server/plugins/io.cloudbeaver.resources.drivers.base_1.0.141.202603020941.jar

Backup successful: /opt/cloudbeaver/server/plugins/io.cloudbeaver.resources.drivers.base_1.0.141.202603020941.jar.1773182108.bak

Bundle replaced successfully

** 참고 **

패치 설치 후 문제가 발생될 경우 백업파일(.bak)을 이용하여 원본 파일로 다시 변경 후 재시작하면 됩니다.

e.g.) cp /opt/cloudbeaver/server/plugins/io.cloudbeaver.resources.drivers.base_1.0.141.202603020941.jar.1773182108.bak /opt/cloudbeaver/server/plugins/io.cloudbeaver.resources.drivers.base_1.0.141.202603020941.jar

5. Docker Container 재부팅

아래와 같은 명령어를 통해 Container를 재시작하거나 Docker Desktop 사용자는 UI에서 Container를 재시작합니다.

docker restart (my-container-name)

6. 활성화 확인

기본 포트인 8978을 사용하는 경우 브라우저에서 ip:8978을 입력하여 CloudBeaver에 접속하여 활성화 상태를 확인 합니다.

New Connection 메뉴로 이동하면 아래 그림과 같이 CUBRID 활성화가 확인됩니다.

CloudBeaver Community 설치

Cloudbeaver Docker Hub에 공개된 정보를 통해 Windows와 Linux에서의 설치 방법을 소개합니다.

[Windows]

Windows의 경우 Docker Desktop(https://www.docker.com/products/docker-desktop/)설치 후에

1. CloudBeaver Docker Hub에서 [Run in Docker Desktop] 버튼을 클릭하여 간단하게 설치 할 수 있습니다.

특정 버전을 사용하고 싶은 경우 Tags Tab으로 이동 후 특정 버전의 Run in Docker Desktop 아이콘으로 설치 할 수도 있습니다.

2. Docker Desktop 실행 팝업이 실행 되고 아래 화면에서 Confirm을 눌러 Image를 Download 받습니다.

3. Container name을 입력하고 Default로 사용할 경우 바로 실행하거나 포트변경예정일 경우 추후 이용할 Port번호를 입력 후 실행을 합니다.

[Linux]

Linux의 경우 Docker 사용을 위해 docker-ce docker-ce-cli containerd.io가 설치가 필요합니다.
Docker의 설치 방법은 다양한 정보를 통해 설치가 가능하므로 Cloudbeaver 설치에 대해서만 설명하겠습니다.

1. 아래와 같이 command를 이용하여 docker image를 download할 수 있습니다.

특정 버전을 이용하고자 하는 경우 ':latest' 부분을 ':25.3.5'와 같이 특정 버전으로 변경하여 download 받습니다.

docker pull dbeaver/cloudbeaver:latest

2. Docker Container를 생성 및 실행

아래와 같은 명령어를 통해 Container 생성 및 실행이 가능합니다.

-p 옵션의 경우 추후 포트를 변경할 예정이라면 다른 포트를 입력하여야 합니다. CloudBeaver 기본 포트는 8978입니다.
-v 옵션의 경우 추후 업데이트를 위해 내부 /opt/cloudbeaver/workspace를 Host 저장소(/var/cloudbeaver/workspace)에 연결하게 되어 docker를 삭제하여도 추후 업데이트시 데이터를 그대로 사용할 수 있습니다. (필요에 따라 위치를 다르게 설정하세요.)

network등 다른 추가 설정이 필요한 경우 reference site를 참고하세요.

docker run -d --name (my-container-name) \

  -p 8978:8978 \

  -v /var/cloudbeaver/workspace:/opt/cloudbeaver/workspace \

  --restart always \

  dbeaver/cloudbeaver:latest

HA 다중화 구성에서 loadBalance를 활용해 읽기 분산해 보기

큐브02 — Tue, 24 Dec 2024 09:35:12 +0900

* HA 다중화 구성에서 loadBalance를 활용해 읽기 분산해 보기

먼저, CUBRID HA와 loadBalance를 잘 이해할 수 있도록 CUBRID HA 특징과 CUBRID Broker의 특징에 대해 정리해 본다.

CUBRID HA는 마스터 노드(master node), 슬레이브 노드(slave node), 레플리카 노드(replica node)로 나눌 수 있다.

마스터 노드 : 액티브 서버를 사용한 읽기, 쓰기 등 모든 서비스를 제공한다.
슬레이브 노드 : 스탠바이 서버를 사용한 읽기 서비스를 제공하며 마스터 노드 장애 시 failover가 일어난다.
레플리카 노드 : 스탠바이 서버를 사용한 읽기 서비스를 제공하며 마스터 노드 장애 시 failover가 일어나지 않는다.

CUBRID Broker의 ACCESS_MODE는 RW(Read Write), RO(Read Only), SO(Standby Only)로 나눌 수 있다.

RW : 읽기, 쓰기 서비스를 제공하는 브로커이다. 일반적으로 액티브 서버에 연결하며, 연결 가능한 액티브 서버가 없으면 일시적으로 스탠바이 서버에 연결한다.
RO : 읽기 서비스를 제공하는 브로커이다. 가능한 스탠바이 서버에 연결하며, 스탠바이 서버가 없으면 액티브 서버에 연결한다.
SO : 읽기 서비스를 제공하는 브로커이다. 스탠바이 서버에 연결하며, 스탠바이 서버가 없으면 서비스를 제공하지 않는다.

이 외에 레플리카로 접속 할 수 있는 파라미터인 REPLICA_ONLY가 존재한다.

REPLICA_ONLY : 레플리카 서버에 접속된다. 이 때의 ACCESS_MODE 값이 RW이면 레플리카 DB에도 쓰기 작업을 수행할 수 있고 이를 허용하지 않으려면 ACCESS_MODE 값을 RO로 설정해야 한다.

또한 CUBRID 브로커에서 QUERY의 종류를 구분하지 않기 때문에 읽기 부산을 위한 브로커에는 SELECT QUERY 만을 수행해야 한다.

이제 마스터-슬레이브-레플리카로 구성 되어 있을 때 loadbalance 읽기 부하 분산을 어떻게 할 수 있을지 살펴본다.

위 그림과 같이 마스터 브로커는 ACCESS_MODE=RW로 설정하여 기본적으로 마스터에 연결되도록 하고, 슬레이브브로커는 ACCESS_MODE=RO로 설정하여 슬레이브에 연결되도록 한다.

(이 때 주의할 점은 마스터, 슬레이브 노드에 부하분산을 위한 브로커는 별도 구성을 해야한다는 점이다. 기본적으로 RW브로커는 마스터, 슬레이브 양 쪽에 구성이 되어 있어야 한다.)

레플리카의 경우 REPLICA_ONLY=ON으로 설정하고, ACCESS_MODE=RO로 설정하여 레플리카 서버에만 접속을 허용하되, 쓰기 작업은 허용하지 않는다.

이 때 마스터 노드 액티브 서버의 장애 발생으로 DB 프로세스가 Down되면 fail-over가 발생되어 기존의 슬레이브 노드가 마스터 노드로 변경된다.

위와 같이 기존 마스터 노드였던 1번 서버에 장애가 발생되더라도, 새로운 마스터 서버(기존 슬레이브)로 연결이 되어 서비스가 정상적으로 동작한다.

이 때 접속량이 기존의 두 배로 발생될 수 있기 때문에 이를 고려하여 각 DB의 max_clients를 설정해야 한다.

위와 같이 기존에 마스터 노드였던 1번 서버의 DB 프로세스가 정상적으로 올라온다면, 슬레이브 노드로 상태가 변경되며, 기존 구성과는 브로커-노드가 CROSS(교차)로 연결 된다.

다만 이 구성에서 고려해야할 점은 REPLICA_ONLY를 설정해둔 경우 레플리카 노드 외에 다른 노드로는 접속 시도를 하지 않기 때문에 레플리카 노드에 장애가 날 경우 서비스 안정성에 문제가 있을 수 있다는 점이다.

레플리카 노드의 장애에 대비하여 레플리카 노드 역시 다중화 할 수 있다.

위와 같은 구성에서는 어떤 서버에서 장애가 발생하더라도, 서비스 안정성을 보장할 수 있으며 읽기 부하 분산도 가장 이상적으로 가능하다.

위 구성에서 각 레플리카 노드의 databases.txt 내 db-host는 각각 자신을 우선순위로 두어야 의도에 맞게 사용할 수 있다. REPLICA1의 경우 REPLICA1:REPLICA2로 설정하고, REPLICA2의 경우 REPLICA2:REPLICA1로 설정 하여야 한다.

각 노드의 databases.txt는 아래와 같이 되어야 한다.

노드	마스터	슬레이브	레플리카1	레플리카2
db-host	마스터:슬레이브	마스터:슬레이브	레플리카1:레플리카2	레플리카2:레플리카1

이렇게 CUBRID HA는 여러가지 구성을 유동적으로 제공하기 때문에 안정성과 성능 모두 만족할 수 있도록 각 사이트에 맞는 구성을 고려하면 좋다.

참고 매뉴얼

- CUBRID HA 구성 형태 : https://www.cubrid.org/manual/ko/11.3/ha.html#id32

- 브로커 모드 : https://www.cubrid.org/manual/ko/11.3/ha.html#broker-mode

- HA 관련 환경 설정 : https://www.cubrid.org/manual/ko/11.3/ha.html#ha-configuration

DBMS와 효과적인 SQL 처리

박세훈 — Fri, 29 Dec 2023 09:13:05 +0900

DBMS는 SQL을 효과적으로 처리하기 위해서 어떠한 노력을 하고 있을까요?

- 질의 재작성기(Query Rewriter)
여러 개발자에게 동일한 요구사항을 주고 질의를 작성하게 하면 서로 다른 형태로 작성할 수 있습니다. 질의를 어떻게 작성하느냐에 따라서 성능에 차이가 발생할 수 있기 때문에 개발자가 질의를 효과적으로 작성하는 것은 중요한 일이지만, DBMS가 상당부분 그 일을 대신하고 있습니다.

위 질의를 작성한 그대로 수행하게 되면 부질의 결과를 임시파일에 저장하고 그것을 재가공해야 합니다. 하지만 오른쪽 질의처럼 작성되어 있다면, 따로 부질의를 수행해서 저장할 필요도 없고, 인덱스의 사용도 가능합니다. 위와 같이 부질의를 제거하고 주질의에 합병하는 것을 뷰머징이라고 합니다. DBMS는 가능한 경우 뷰머징을 진행하며, 인라인 뷰와 뷰 객체에 대해서도 동일하게 합병을 진행합니다.

부질의가 뷰머지가 불가능한 경우에 주질의에 있는 조회조건을 부질의로 넣는 것을 predicate push라고 합니다. 조회시 스캔하는 양을 줄일 수 있기 때문에 상당히 성능을 향상시킬 수 있습니다.

필요 없는 select list와 조인 테이블 그리고 order by절등을 제거하여, 필요없는 처리과정을 진행하지 않을 수 있습니다. 해당 항목을 조회 하지 않아도 동일한 결과가 보장될 때 제거가 가능합니다. 테이블은 외부 조인되거나 외례키 관계에서 조인 조건의 컬럼이 유니크한 경우 제거가 가능합니다.

위에서 소개한 재작성 이외에도 DBMS는 다양한 재작성을 진행합니다. CUBRID는 이러한 재작성된 질의를 실행계획에서 직접 확인할 수 있습니다.

- 질의 최적화기(Query Optimizer)
SQL은 어떻게 데이터를 조회할 것인가에 대한 정보를 포함하고 있지 않습니다. 질의 최적화기가 이러한 정보인 실행계획을 생성합니다.

위 질의의 조회조건으로 얼마나 데이터가 필터링될지 예측할 수 있을까요? 만약 'COLUMN'의 값이 고유하다면 한건이 조회 될 것이고, 모두 '1'이라면 전체 데이터가 조회 될 것입니다. 이렇게 조회조건을 평가했을 때 전체 데이터 대비 조회되는 양의 비율을 선택도(selectivity)라고 합니다. 선택도를 통해서 읽어야하는 페이지수와 결과 행수를 예측할 수 있습니다. 예를 들어 'table'의 전체 페이지수는 1000개, 데이터 건수는 10,000개이고 조회조건의 선택도가 0.01이면, 읽어야 하는 페이지수는 10개, 결과 행수는 100건으로 예측할 수 있습니다. 비용계산 공식은 스캔 방법에 따라 다르고 복잡하지만, 기본적인 원리는 선택도를 활용하여 결과 행수와 읽어야 하는 페이지를 예측하는 것입니다.

위와 같이 조인된 질의는 각테이블 별로 분리해서 비용을 산출합니다. 첫번째 테이블의 선택도와 전체 페이지수로 비용을 계산하고 두번째 테이블역시 같은 방법으로 비용을 산정합니다. nested loop 조인 방법이라면 첫번째 결과 행수만큼 두번째 테이블 조회를 반복하게 됩니다. 이 경우 전체 비용은 첫번째 비용 + (첫번째 행수 * 두번째 비용) 으로 계산할 수 있습니다. 질의 최적화기는 각각 테이블 순열의 비용을 계산하고, 비교하여 최적의 실행계획을 선택합니다.

실행계획을 보면 최적화시에 사용된 정보들을 확인할 수 있습니다. 테이블의 전체 건수와 페이지수 그리고 조회조건의 선택도가 얼마인지 확인 할수 있습니다. 실행계획의 card는 cardnality의 약자로 예측되는 결과 행수를 의미합니다. 각각의 정보를 알고 있으면 실행계획을 정확하게 이해하는데 도움이 될 것입니다.

- 질의 실행기(Query Executor)

질의 실행기에서는 성능 향상을 위해 진행 단계를 생략하는 최적화를 진행합니다. 인덱스를 활용하여 정렬과정을 생략하거나 인덱스의 정보만으로도 조회가 가능하면 데이터영역에 접근하는 과정을 생략합니다. 다중 키 범위 최적화와 SORT-LIMIT 최적화와 같이 필요한 양의 데이터만 조회하여 나머지 데이터의 스캔 과정을 생략하기도 합니다.

TRACE 정보를 확인하면 질의 실행기가 어떤 최적화를 진행했는지 알 수 있습니다. 또한 실제로 읽은 페이지수와 결과 행수도 확인 가능합니다.

- 마치며

DBMS는 성능향상을 위해 다양한 최적화를 진행하고 있으며, 사용자는 실행계획과 TRACE 정보를 통해 이것을 확인할 수 있습니다. CUBRID는 이러한 성능 향상을 위한 개선 작업을 지속적으로 진행하고 있습니다. 질의가 더 효과적으로 재작성되도록 다양한 사례의 재작성을 추가하고 보완하였습니다. 효과적인 실행계획을 생성하기 위해서 선택도관련 통계정보의 대상을 인덱스에서 테이블로 확대하고, 규칙기반 최적화는 최소화하는 작업을 진행하고 있습니다. CUBRID는 아직 병렬 질의를 지원하지 않지만 2024년을 목표로 개발을 진행하고 있습니다. 조금씩 꾸준히 사용자 관점에서 개선되는 CUBRID를 기대해 주시기를 바랍니다.

CUBRID Internal: B+ 트리의 노드(=페이지)와 노드 분할 방법

주영진 — Wed, 27 Dec 2023 19:55:37 +0900

개요

큐브리드는 B+ 트리 인덱스를 사용하고 있습니다. B+ 트리 인덱스는 새로운 키가 입력되거나 기존 레코드가 변경될 때, B+ 트리를 유지하기 위해서 노드의 분할 또는 병합이 발생할 수 있습니다. 노드는 B+ 트리를 구성하는 가장 작은 단위로, 하나의 노드는 데이터베이스에서 하나의 페이지에 해당합니다. 이 글에서는 노드가 되는 페이지에 대해서 살펴보고, 노드 분할이 발생하는 경우와 그 과정에 대해서 알아보겠습니다.

예시의 모든 질의는 11.3.0.1089-bd31bd5 버전에서 실행했습니다.

B+ 트리의 노드(= 페이지)

데이터베이스의 모든 데이터는 페이지에 저장되며, 모든 페이지는 슬롯 페이지 구조(Slotted Page Structure)로 되어 있습니다. 슬롯 페이지 구조에 대해 더 알고 싶다면 "CUBRID 슬랏 페이지(slotted page) 구조 살펴보기" 글을 참고해주세요. 모든 페이지는 페이지 헤더(SPAGE_HEADER)를 포함하고 있습니다. 페이지는 페이지 헤더의 페이지 타입(PAGE_TYPE)을 통해 어떤 테이터를 저장하고 있는지를 구분할 수 있습니다. 페이지 타입에 따라 추가로 필요한 헤더를 가질 수 있습니다. B+ 트리의 노드는 페이지 타입이 PAGE_BTREE인 페이지입니다. PAGE_BTREE 페이지는 페이지 헤더와 페이지 타입에 필요한 노드 헤더(BTREE_NODE_HEADER) 또는 오버플로 헤더(BTREE_OVERFLOW_HEADER)를 가지고 있습니다.

일반적으로 B+ 트리는 노드를 3 계층으로 구분합니다. 가장 상위 노드를 루트(Root) 노드, 가장 하위 노드를 리프(Leaf) 노드, 루트와 리프 사이에 있는 노드를 브랜치(Branch) 노드라고 합니다. 노드가 어느 계층의 노드인지는 노드 헤더가 가지고 있는 노드 레벨 (node_level)로 확인할 수 있습니다. 리프 노드의 노드 레벨은 항상 1이며, 루트 노드의 노드 레벨은 B+ 트리의 높이입니다. B+ 트리의 높이가 3인 경우, 브랜치 노드의 노드 레벨은 2가 되고, 루트 노드의 노드 레벨은 3이 됩니다.

노드 레벨에 따라서 노드 타입을 구분하고 있습니다. 노드 타입은 리프가 아닌 노드(BTREE_NON_LEAF_NODE), 리프 노드(BTREE_LEAF_NODE), 오버플로 노드(BTREE_OVERFLOW_NODE) 등 3가지가 있습니다. 노드 레벨이 1인 경우 노드의 노드 타입은 BTREE_LEAF_NODE(리프 노드)가 되며, 노드 레벨이 1보다 큰 경우 BTREE_NON_LEAF_NODE(리프가 아닌 노드)가 됩니다. B+ 트리의 높이가 1인 경우에는 인덱스를 구성하는 페이지가 1개이고, 루트 노드의 노드 레벨이 1이기 때문에 루트 노드의 노드 타입이 BTREE_LEAF_NODE(리프 노드)가 됩니다. 오버플로 노드에 대해서는 좀 더 아래에서 알아보겠습니다.

	
			1
2
3
4
5
6
7
8

			/* src/storage/btree.h */
 
typedef enum
{
  BTREE_LEAF_NODE = 0,
  BTREE_NON_LEAF_NODE,
  BTREE_OVERFLOW_NODE
} BTREE_NODE_TYPE;

		

루트 노드는 루트 헤더(BTREE_ROOT_HEADER)를 가지고 있습니다. 루트 헤더는 노드 헤더를 포함하고 있고, 인덱스 전체에 대한 메타 정보를 저장하고 있습니다. 브랜치 노드와 리프 노드는 노드 헤더만 가지고 있습니다.

페이지의 0번 슬롯이 루트 헤더 또는 노드 헤더를 가리키고 있습니다. 루트 노드와 브랜치 노드의 레코드는 다음 계층 노드의 VPID를 저장하고 있고, VPID는 페이지에 접근할 수 있는 주소입니다. VPID는 볼륨 아이디, 페이지 아이디로 구성되어 있습니다. 리프 노드의 레코드는 테이블 레코드들의 OID를 저장하고 있고, OID는 레코드에 접근할 수 있는 주소입니다. OID는 볼륨 아이디, 페이지 아이디, 슬롯 아이디로 구성되어 있습니다.

오버플로 노드 (BTREE_OVERFLOW_NODE)

리프 노드에 동일한 키가 여러 번 입력되면 해당 키는 한 번만 저장하고 테이블 레코드들의 OID를 모아서 저장합니다. 이러한 구조는 같은 키를 가지는 테이블 레코드들을 빠르게 찾을 수 있도록 하는 장점이 있습니다. 그러나 OID 목록에서 특정 OID를 찾는 것은 어려울 수 있습니다. OID 목록의 크기는 페이지 크기의 1/8을 초과할 수 없으며, 페이지 크기의 1/8을 초과하는 OID들은 오버플로 노드에 저장됩니다.

	
			1
2
3

			/* src/storage/btree_load.h */
 
#define BTREE_MAX_OIDLEN_INPAGE ((int) (DB_PAGESIZE / 8))

오버플로 노드에는 2개의 슬롯만 존재합니다. 0번 슬롯은 오버플로 헤더를 가리키고 있으며, 1번 슬롯은 OID 목록을 가리키고 있습니다. 하나의 오버플로 노드에 OID 목록을 모두 저장할 수 없는 경우에는 오버플로 헤더가 다음 오버플로 노드의 VPID를 저장하고 있습니다.

리프 노드의 레코드가 오버플로 노드에 OID 목록을 저장하고 있는 경우에는 첫 번째 OID의 슬롯 아이디에 BTREE_LEAF_RECORD_OVERFLOW_OIDS 플래그를 설정하며, 레코드 마지막에는 첫 번째 오버플로 노드의 VPID가 저장되어 있습니다.

	
			1
2
3
4
5
6
7
8
9
10

			/* src/storage/btree.c */
 
if (btree_leaf_is_flaged (rec, BTREE_LEAF_RECORD_OVERFLOW_OIDS))
  {
    btree_leaf_get_vpid_for_overflow_oids (rec, &leaf_rec->ovfl);
  }
else
  {
    VPID_SET_NULL (&leaf_rec->ovfl);
  }

		

PAGE_OVERFLOW 페이지

사용자가 입력하는 키의 크기가 너무 커서 하나의 페이지에 저장할 수 없는 경우가 있습니다. 리프 노드에 저장할 수 있는 키의 크기는 페이지 크기의 1/8을 초과할 수 없습니다. 페이지 크기의 1/8을 초과하는 키는 리프 노드에 저장되지 않고, 하나 이상의 PAGE_OVERFLOW 페이지에 나누어 저장됩니다.

	
			1
2
3

			/* src/storage/btree_load.h */
 
#define BTREE_MAX_KEYLEN_INPAGE ((int) (DB_PAGESIZE / 8))

PAGE_OVERFLOW 페이지는 페이지 타입이 PAGE_OVERFLOW인 페이지입니다. 이 페이지는 페이지 헤더가 없으며, 슬롯 페이지 구조도 아닙니다. 첫 번째 PAGE_OVERFLOW 페이지는 OVERFLOW_FIRST_PART를 저장하고 있고, 두 번째 PAGE_OVERFLOW 페이지부터는 OVERFLOW_REST_PART를 저장하고 있습니다. 전체 키의 길이는 OVERFLOW_FIRST_PART에만 저장되어 있습니다.

리프 노드의 레코드가 PAGE_OVERFLOW 페이지에 키를 저장하고 있는 경우에는 첫 번째 OID의 슬롯 아이디에 BTREE_LEAF_RECORD_OVERFLOW_KEY 플래그를 설정하며, 레코드 마지막에는 첫 번째 PAGE_OVERFLOW 페이지의 VPID가 저장되어 있습니다.

	
			1
2
3
4
5
6

			/* src/storage/btree.c */
 
if (btree_leaf_is_flaged (rec, BTREE_LEAF_RECORD_OVERFLOW_KEY))
  {
    key_type = BTREE_OVERFLOW_KEY;
  }

		

PAGE_OVERFLOW 페이지는 인덱스 페이지가 아니라 데이터 페이지입니다. PAGE_BTREE 페이지는 인덱스 페이지로 개수를 세고 있지만, PAGE_OVERFLOW 페이지는 데이터 페이지로 개수를 세고 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13

			/* src/storage/page_buffer.c - pgbuf_scan_bcb_table () */
 
switch (page_type)
  {
  case PAGE_BTREE:
    show_status_snapshot->num_index_pages++;
    break;
  case PAGE_OVERFLOW:
  case PAGE_HEAP:
    show_status_snapshot->num_data_pages++;
    break;
  ...
}

		

노드 분할

노드 분할이 발생하는 경우

새로운 키를 저장하기 위한 공간이 부족하거나 기존 레코드의 크기가 증가하는 경우에는 노드 분할이 발생할 수 있습니다. 이를 좀 더 자세히 살펴보면 다음과 같은 경우가 있습니다:

1. 새로운 키가 입력되는 경우

2. 기존 키의 크기가 증가하는 경우

3. 기존 레코드에 테이블 레코드의 OID가 추가되는 경우

4. 기존 레코드에 MVCC 아이디가 추가되는 경우

1. 새로운 키가 입력되는 경우

새로운 키의 입력은 충분한 여유 공간을 필요로 합니다. 해당 페이지에 여유 공간이 부족하면 노드 분할이 발생할 수 있습니다. 노드 분할이 발생하기 전까지 1978개의 키를 입력했습니다. 이 상태에서 새로운 키를 입력하면 노드 분할이 발생한 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
drop table if exists t1;
create table t1 (c1 int, index i1 (c1));
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 1978
  )
select n from cte;
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
insert into t1 values (1979);
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
/*
<00001> Table_name                       : 'dba.t1'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 1983 (1980 -> 1983)
        Total_value                      : 1983 (1980 -> 1983)
        ...
        Num_leaf_page                    : 3 (2 -> 3)
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 4 (3 -> 4)
        Height                           : 2
        ...
*/

		

2. 기존 키의 크기가 증가하는 경우

기존 키의 크기가 증가하면 레코드의 크기도 증가하게 됩니다. 해당 페이지에 여유 공간이 부족하면 노드 분할이 발생할 수 있습니다. 가변 길이 문자열 타입(VARCHAR)에서는 기존 키의 크기를 변경할 수 있습니다. 노드 분할이 발생하기 전까지 1581개의 키를 입력했습니. 이 상태에서 기존에 입력했던 키의 크기를 크게 변경하면 노드 분할이 발생한 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
drop table if exists t1;
create table t1 (c1 varchar, index i1 (c1));
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 1581
  )
select lpad (n, 4, '0') from cte;
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
update t1 set c1 = lpad (c1, 20 /* 4 -> 20 */, '9') where c1 = 1581;
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
/*
<00001> Table_name                       : 'dba.t1'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 1585 (1583 -> 1585)
        Total_value                      : 1585 (1583 -> 1585)
        ...
        Num_leaf_page                    : 3 (2 -> 3)
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 4 (3 -> 4)
        Height                           : 2
        ...
*/

		

3. 기존 레코드에 테이블 레코드의 OID가 추가되는 경우

같은 키가 입력되면 중복된 키를 저장하지 않고, 기존 키 뒤에 테이블 레코드의 OID를 추가합니다. 추가된 OID의 크기만큼 레코드의 크기도 증가하게 됩니다. 해당 페이지에 여유 공간이 부족하면 노드 분할이 발생할 수 있습니다. 노드 분할이 발생하기 전까지 1977개의 키를 입력했습니다. 이 상태에서 기존에 입력했던 키와 같은 키를 몇 번 더 입력하면 노드 분할이 발생한 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
drop table if exists t1;
create table t1 (c1 int, index i1 (c1));
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 1977
  )
select n from cte;
 
select count (*) from t1 where c1 = 1977;
/* <00001> count(*): 1 */
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
insert into t1 values (1977);
insert into t1 values (1977);
insert into t1 values (1977);
 
select count (*) from t1 where c1 = 1977;
/* <00001> count(*): 4 */
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
/*
<00001> Table_name                       : 'dba.t1'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 1981 (1979 -> 1981)
        Total_value                      : 1984 (1979 -> 1984)
        ...
        Num_leaf_page                    : 3 (2 -> 3)
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 4 (3 -> 4)
        Height                           : 2
        ...
*/

		

4. 기존 레코드에 MVCC 아이디가 추가되는 경우

레코드를 변경할 때 MVCC 아이디가 추가되도록 하려면 클라이언트/서버 모드에서 AUTO COMMIT을 비활성화하고 질의를 실행해야 합니다. 이 상태에서 질의를 실행하면 트랜잭션을 시작합니다. 트랜잭션 중에는 키를 삭제해도 물리적으로 삭제하지 않고, DELETE MVCC 아이디를 추가합니다. 추가되는 DELETE MVCC 아이디의 크기만큼 레코드의 크기도 증가하게 됩니다. 해당 페이지에 여유 공간이 부족하면 노드 분할이 발생할 수 있습니다. 노드 분할이 발생하기 전까지 1318개의 키를 입력했습니다. 이 상태에서 AUTO COMMIT을 비활성화하고 몇 개의 기존 키를 삭제하면 노드 분할이 발생한 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

			/**
 * client-server mode
 *   $ cubrid server start 
 *   $ csql -u dba 
 */
 
drop table if exists t1;
create table t1 (c1 int, index i1 (c1));
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 1318
  )
select n from cte;
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
/* csql> ;autocommit off */
delete from t1 where c1 = 1318;
delete from t1 where c1 = 1317;
delete from t1 where c1 = 1316;
delete from t1 where c1 = 1315;
delete from t1 where c1 = 1314;
delete from t1 where c1 = 1313;
 
/* csql> ;line-output on */
show index capacity of t1.i1;
 
/*
<00001> Table_name                       : 'dba.t1'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 1322 (1320 -> 1322)
        Total_value                      : 1322 (1320 -> 1322)
        ...
        Num_leaf_page                    : 3 (2 -> 3)
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 4 (3 -> 4)
        Height                           : 2
        ...
*/

		

사용자가 키를 입력하는 패턴에 따라 달라지는 노드 분할 #1

B+ 트리의 키가 항상 정렬되어 있기 때문에 사용자가 어떤 패턴으로 키를 입력하더라도 B+ 트리의 상태는 항상 동일하다고 착각할 수 있습니다. University of San Francisco의 B+ Tree Visualization을 사용하여 아래 2개의 시나리오 결과를 비교해 보았습니다.

1. 시나리오 #1 - 1부터 27까지 오름차순으로 증가하는 패턴으로 키를 입력하는 경우

2. 시나리오 #2 - 1부터 27까지 불규칙 패턴으로 키를 입력하는 경우

Max. Degree는 7로 설정했습니다. 페이지에 7번째 키가 입력될 때 노드의 레코드가 반으로 분할됩니다.

시나리오 #1 - 1부터 27까지 오름차순으로 증가하는 패턴으로 키를 입력하는 경우

1→2→3→4→5→6→7→8→9→10→11→12→13→14→15→16→17→18→19→20→21→22→23→24→25→26→27 순서로 키를 입력했습니다.

시나리오 #2 - 1부터 27까지 불규칙 패턴으로 키를 입력하는 경우

14→13→26→12→24→11→22→10→20→9→18→27→8→16→7→21→6→5→15→25→4→3→2→1→17→19→23 순서로 키를 입력했습니다.

비교 결과

B+ 트리의 높이가 시나리오 #1은 3이고, 시나리오 #2는 2입니다. B+ 트리의 높이가 높아지면 키를 탐색할 때 더 많은 노드에 접근해야 하므로 성능 저하가 발생 수 있습니다. 사용하는 페이지 수도 시나리오 #1은 11개이고, 시나리오 #2는 8개입니다. 시나리오 #1에서는 가장 오른쪽 리프 노드를 제외하고는 키를 4개 이상 저장하고 있는 리프 노드가 없습니다. 오름차순으로 증가하는 패턴으로 키를 입력하기 때문에 새로운 키는 가장 오른쪽 리프 노드에만 입력되고, 나머지 리프 노드에서는 저장 공간이 낭비됩니다. 시나리오 #1과 시나리오 #2는 키를 입력하는 패턴만 다르고, 나머지는 동일합니다. 사용자가 불규칙 패턴으로 키를 입력할 때는 성능 저하와 저장 공간의 낭비가 발생하지 않았습니다. 그러나 사용자가 항상 같은 패턴으로 키를 입력하는 것을 기대하는 것은 불가능합니다. 사용자는 서비스하고 있는 데이터의 성격에 따라 오름차순, 내림차순 또는 불규칙한 패턴으로 키를 삽입합니다.

똑똑하게 노드 분할하기

B+ 트리에서는 키가 정렬된 위치에 입력되기 때문에 키가 입력되는 슬롯 아이디의 변화를 통계적으로 분석하면 사용자가 키를 입력하는 패턴을 파악할 수 있습니다. 예를 들어, 오름차순 인덱스라고 가정할 때, 리프 노드의 가장 마지막 슬롯에 새로운 키가 입력되면 오름차순으로 증가하는 패턴으로 키가 입력되고 있다고 예측할 수 있습니다. 반대로 리프 노드의 노드 헤더 바로 다음 슬롯에 새로운 키가 입력되면 내림차순으로 감소하는 패턴으로 키가 입력되고 있다고 것으로 예측할 수 있습니다.

노드 헤더는 노드 분할 정보(BTREE_NODE_SPLIT_INFO)를 포함하고 있습니다. 이 정보는 페이지에 입력되는 슬롯 아이디에 대한 누적 이동 평균(pivot)을 계산해서 저장합니다. 새로운 키가 입력될 때마다 btree_split_next_pivot 함수에서 새로운 누적 이동 평균을 계산하고, 노드 분할이 필요한 경우에는 btree_find_split_point 함수에서 현재의 누적 이동 평균을 확인해서 노드의 레코드를 분할합니다.

	
			1
2
3
4
5
6

			#0  btree_split_next_pivot (...) at src/storage/btree.c:12603
#1  0x00007ff421cd3e96 in btree_key_insert_new_key (...) at src/storage/btree.c:27717
#2  0x00007ff421cd335e in btree_key_insert_new_object (...) at src/storage/btree.c:27484
#3  0x00007ff421cc7d9c in btree_search_key_and_apply_functions (...) at src/storage/btree.c:22802
#4  0x00007ff421ccfb63 in btree_insert_internal (...) at src/storage/btree.c:26345
#5  0x00007ff421ccf635 in btree_insert (...) at src/storage/btree.c:26199

		

누적 이동 평균은 다음과 같은 수식으로 계산됩니다. 여기서 CA_i는 i+1번째 키가 입력되기 전에 노드 분할 정보에 저장된 누적 이동 평균을 나타냅니다. 또한, X_i+1은 i+1번째 키에 대한 이동 평균을 나타냅니다. 이는 i+1번째 키가 입력된 슬롯 아이디를 i+1번째 키가 입력된 후의 전체 키 개수로 나누어 계산됩니다.

노드 분할이 발생할 때 레코드를 분할할 위치는 btree_split_find_pivot 함수에서 결정됩니다. 이 함수는 누적 이동 평균을 직접적으로 반영하지 않습니다. 누적 이동 평균이 0.2f(BTREE_SPLIT_LOWER_BOUND)와 0.8f(BTREE_SPLIT_UPPER_BOUND) 사이에 있는 경우에는 레코드를 반으로 분할하고, 벗어나는 경우에만 누적 이동 평균을 직접적으로 반영하여 레코드를 분할할 위치를 결정합니다. 만약 누적 이동 평균이 0.05f(BTREE_SPLIT_MIN_PIVOT)보다 작으면 0.05f를 사용하고, 0.95f(BTREE_SPLIT_MAX_PIVOT)보다 크면 0.95f를 사용하여 레코드를 분할할 위치를 결정합니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

			#0  btree_split_find_pivot (...) at src/storage/btree.c:12575
#1  0x00007ff421cafaee in btree_find_split_point (...) at src/storage/btree.c:12289
#2  0x00007ff421cb3cbd in btree_split_root (...) at src/storage/btree.c:13889
#3  0x00007ff421cd1934 in btree_split_node_and_advance (...) at src/storage/btree.c:27003
#4  0x00007ff421cc7b93 in btree_search_key_and_apply_functions (...) at src/storage/btree.c:22753
#5  0x00007ff421ccfb63 in btree_insert_internal (...) at src/storage/btree.c:26345
#6  0x00007ff421ccf635 in btree_insert (...) at src/storage/btree.c:26199
 
#0  btree_split_find_pivot (...) at src/storage/btree.c:12575
#1  0x00007ff421cafaee in btree_find_split_point (...) at src/storage/btree.c:12289
#2  0x00007ff421cb1a1e in btree_split_node (...) at src/storage/btree.c:13051
#3  0x00007ff421cd28f9 in btree_split_node_and_advance (...) at src/storage/btree.c:27290
#4  0x00007ff421cc7b93 in btree_search_key_and_apply_functions (...) at src/storage/btree.c:22753
#5  0x00007ff421ccfb63 in btree_insert_internal (...) at src/storage/btree.c:26345
#6  0x00007ff421ccf635 in btree_insert (...) at src/storage/btree.c:26199

		

사용자가 키를 입력하는 패턴에 따라 달라지는 노드 분할 #2

1. 오름차순으로 증가하는 패턴으로 키를 입력하는 경우

새로운 키는 항상 페이지의 마지막 슬롯에 입력되기 때문에 노드 분할 정보에서 누적 이동 평균은 0.95f(BTREE_SPLIT_MAX_PIVOT)보다 큰 값을 유지합니다. 따라서 노드 분할이 발생할 때 누적 이동 평균이 0.95f보다 크기 때문에 분할되는 왼쪽 페이지에는 전체 레코드 길이의 95%가 이동하고, 오른쪽 페이지에는 나머지 5%가 이동합니다. SHOW INDEX CAPACITY에서 Total_free_space_non_ovf를 보면 공간 낭비가 없는 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
set system parameters 'cte_max_recursions=100000';
 
drop table if exists t_asc;
create table t_asc (c1 int, index i1 (c1));
 
insert into t_asc with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 100000
  )
select n from cte;
 
/* csql> ;line-output on */
show index capacity of t_asc.i1;
 
/*
<00001> Table_name                       : 'dba.t_asc'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 100206
        Total_value                      : 100206
        ...
        Num_leaf_page                    : 104
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 105
        Height                           : 2
        ...
        Total_space                      : '1.6M'
        Total_used_space_non_ovf         : '1.5M'
        Total_free_space_non_ovf         : '101.9K'
        ...
*/

		

2. 내림차순으로 감소하는 패턴으로 키를 입력하는 경우

새로운 키는 항상 페이지의 1번 슬롯에 입력되기 때문에 노드 분할 정보에서 누적 이동 평균은 0.05f(BTREE_SPLIT_MIN_PIVOT)보다 작은 값을 유지합니다. 노드 분할이 발생할 때 누적 이동 평균이 0.05f보다 작기 때문에 분할되는 왼쪽 페이지에는 전체 레코드 길이의 5%가 이동하고, 오른쪽 페이지에는 나머지 95%가 이동합니다. SHOW INDEX CAPACITY에서 Total_free_space_non_ovf를 보면 공간 낭비가 없는 것을 확인할 수 있습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
set system parameters 'cte_max_recursions=100000';
 
drop table if exists t_desc;
create table t_desc (c1 int, index i1 (c1));
 
insert into t_desc with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 100000
  )
select n from cte order by n desc;
 
/* csql> ;line-output on */
show index capacity of t_desc.i1;
 
/*
<00001> Table_name                       : 'dba.t_desc'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 100206
        Total_value                      : 100206
        ...
        Num_leaf_page                    : 104
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 105
        Height                           : 2
        ...
        Total_space                      : '1.6M'
        Total_used_space_non_ovf         : '1.5M'
        Total_free_space_non_ovf         : '101.9K'
        ...
*/

		

3. 불규칙 패턴으로 키를 입력하는 경우

키가 입력될 때마다 키가 입력되는 슬롯 아이디에 대한 누적 이동 평균이 갱신됩니다. 그래프를 보면 0.5f에서 크게 벗어나지 않고 있습니다. 노드 분할이 발생할 때 누적 이동 평균이 0.2f(BTREE_SPLIT_LOWER_BOUND)와 0.8f(BTREE_SPLIT_UPPER_BOUND) 사이에 있기 때문에 분할되는 왼쪽 페이지와 오른쪽 페이지에 각각 전체 레코드 길이의 50%를 이동합니다. SHOW INDEX CAPACITY 결과를 확인하면 오름차순 및 내림차순 패턴과 비교했을 때 Total_free_space_non_ovf가 큰 편입니다. 하지만 불규칙 패턴에서는 분할되는 왼쪽과 오른쪽 페이지 양쪽에 새로운 키가 입력될 가능성이 있으므로, 잦은 노드 분할을 방지하기 위해 적당한 여유 공간을 유지하는 것이 좋습니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
set system parameters 'cte_max_recursions=100000';
 
drop table if exists t_random;
create table t_random (c1 int, index i1 (c1));
 
insert into t_random with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 100000
  )
select n from cte order by random ();
 
/* csql> ;line-output on */
show index capacity of t_random.i1;
 
/*
<00001> Table_name                       : 'dba.t_random'
        Index_name                       : 'i1'
        Btid                             : '(0|4160|4161)'
        Num_distinct_key                 : 100254
        Total_value                      : 100254
        ...
        Num_leaf_page                    : 128
        Num_non_leaf_page                : 1
        Num_ovf_page                     : 0
        Num_total_page                   : 129
        Height                           : 2
        ...
        Total_space                      : '2.0M'
        Total_used_space_non_ovf         : '1.5M'
        Total_free_space_non_ovf         : '482.4K'
        ...
*/

		

루트 노드 → 브랜치 노드 → 리프 노드 순서의 노드 분할

노드 분할은 루트 노드 → 브랜치 노드 → 리프 노드 순서로 발생합니다. 키는 리프 노드에 입력되기 때문에 처음에는 리프 노드에서 노드 분할이 발생할 것으로 생각할 수 있습니다. 그러나 실제로는 루트 노드부터 시작하여 새로운 키를 입력할 수 있는 여유 공간이 있는지 확인합니다. 루트 노드에 공간이 부족하다면 키가 입력되지 전에 루트 노드에서부터 노드 분할이 발생합니다. 나중에 리프 노드에서 분할이 발생했을 때 분할된 페이지를 구분하기 위한 분할 키를 루트 노드와 브랜치 노드에 저장해야 하기 때문에 미리 여유 공간이 확보하는 것입니다.

아래는 B+ 트리의 높이가 1에서 2가로 증가하는 과정입니다. B+ 트리의 높이 1일 때는 리프 노드가 1개만 존재합니다. 리프 노드에 새로운 키를 저장할 수 있는 공간이 부족할 때 노드 분할이 발생합니다. 루트 노드의 분할은 새로운 키가 입력되기 전에 발생하며, 노드 분할이 완료된 후에 정렬된 위치에 새로운 키가 입력됩니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
drop table if exists t1;
create table t1 (c1 int auto_increment, index i1 (c1));
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < 1012
  )
select null from cte;
 
insert into t1 values (null); /* 1013 */

		

아래는 B+ 트리의 높이가 2에서 3으로 증가하는 과정입니다. 리프 노드에 새로운 키를 저장할 공간이 부족해서 노드 분할이 발생한 것이 아니라 루트 노드에 여유 공간이 부족해서 노드 분할이 발생했습니다. 루트 노드의 노드 분할이 완료된 후에는 정렬된 위치의 리프 노드에 새로운 키가 입력된 것을 확인할 수 있습니다. 이 때 리프 노드의 공간은 충분하기 때문에 노드 분할이 발생하지 않았습니다. 루트 노드가 분할하면서 B+ 트리의 높이가 2에서 3으로 증가할 때 새로운 브랜치 노드 2개가 추가됩니다. 루트 노드와 리프 노드의 VPID는 변경되지 않고, 새로운 브랜치 노드에 리프 노드의 레코드를 이동합니다.

	
			1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

			/**
 * standalone mode
 *   $ csql -u dba  -S
 */
 
set system parameters 'cte_max_recursions=1000000';
 
insert into t1 with recursive cte (n) as (
    select 1
    union all
    select n + 1 from cte where n < (976629 - 1013)
  )
select null from cte;
 
insert into t1 values (null); /* 976630 */

		

참고

1. [CUBRID Blog] CUBRID 슬랏 페이지(slotted page) 구조 살펴보기

2. [NAVER D2] CUBRID Internals - 키와 인덱스의 관계

3. [University of San Francisco] B+ Tree Visualization

4. [Wikimedia] Moving average - Cumulative average

CUBRID | Enterprise Open Source DBMS

CircleCI 테스트 카테고리 확장 도입기 — Shell 테스트를 머지 이전 단계로 (1편)

CircleCI 테스트 카테고리 확장 도입기 — Shell 테스트를 머지 이전 단계로 (1편)

들어가며

왜 통합 빌드에서는 원인 커밋을 찾기 어려운가

해결의 방향 — 테스트를 머지 이전으로 당기다

1차 시도 — 클라우드 컨테이너 기반 테스트

2차 시도 — 셀프 호스팅 Kubernetes 클러스터

클러스터는 만들었지만 — 디스크 병목

회피 전략 1 — 물리 디스크 대신 RAM 디스크

새로운 병목 — 동시성 대기 큐

예상하지 못한 부작용 — 공유 자원 오염

회피 전략 2 — PR별 테스트 케이스 브랜치 분리

리그레션의 노이지 네이버 — retry 로직 재설계

지금까지의 결과

남은 과제

마치며 — 머지 이전 검증으로 코드 안정성을 끌어올리다

CUBRID 장애 보고서 작성법 : Broker Log와 Server Log로 원인, 영향, 조치를 정리하기

CUBRID 장애 보고서 작성법:Broker Log와 Server Log로 원인, 영향, 조치를 정리하기

1. 장애 보고서가 필요한 이유

2. CUBRID 장애 보고서의 기본 구조

3. 장애 개요 작성법

4. 발생 시간 — 타임라인으로 작성하기

5. 영향 범위 — 서비스 지표와 DB 지표 연결하기

6. 최초 감지 지표 작성법

CUBRID 측 확인 명령어

7. Broker 상태 작성법

8. DB Server 상태 작성법

9. 원인 SQL 작성법

10. 조치 내용 작성법

11. 재발 방지 대책 작성법

12. 실무 예시: 조건절 누락 대량 UPDATE 장애 보고서

13. 자주 하는 실수

14. 장애 보고서 템플릿

15. 핵심 정리

CUBRID EOL 대응 가이드 : 운영 DB 업그레이드 계획 수립하기

CUBRID EOL 대응 가이드:운영 DB 업그레이드 계획 수립하기

1. DB 업그레이드를 변경관리로 봐야 하는 이유

2. CUBRID EOL 정책 이해

3. EOL 대응이 필요한 이유

4. 현재 버전 확인

5. 업그레이드 대상 버전 선정

5.1 CUBRID 버전 표기 방식과 업그레이드 범위 이해

5.2 대상 버전 선정 기준

6. 변경 영향 범위 분석

7. 드라이버 호환성 확인

8. 백업 및 Rollback 계획

8.1 업그레이드 전 백업

8.2 Rollback 기준을 사전에 정한다

9. SQL 호환성 · 성능 회귀 테스트

9.1 SQL 호환성 테스트

9.2 성능 회귀 기준 설정

10. 배치 SQL 별도 테스트

11. Broker CAS 재산정

12. HA 환경 업그레이드 점검

13. 업그레이드 일정 수립

14. 운영 반영 당일 Runbook

15. 반영 후 안정화 모니터링

16. 운영자가 자주 하는 실수

17. 체크리스트

18. 핵심 정리

Testcontainers-cubrid로 CUBRID 통합 테스트 환경 구성하기

테스트 코드에서 바로 띄우는CUBRID 통합 테스트 환경

0 CUBRID 통합 테스트 환경의 고민

1 사전 요구사항

2 의존성 추가

3 CubridContainer로 통합 테스트 작성

4 JDBC URL로 더 간단하게 사용하기

5 Spring Boot 테스트에서 사용하기

6 마치며

🔗 관련 링크

히스토그램 출시 임박 기념 칼럼: 바인드 피킹과 플랜 유효성 문제

바인드 피킹

바인드 피킹의 시스템적 해결

어떤 쿼리를 대상으로 플랜 캐시 키를 확장해야 할까?

마무리

CUBRID 전환 후 성능 이슈 분석: SQL 문법보다 실행 패턴이 중요하다

CUBRID 전환 후 성능 이슈 분석:SQL 문법보다 실행 패턴이 중요하다

1. 개요

2. 전환 후 성능 저하가 발생하는 이유

CUBRID 장애 보고서 작성법:
Broker Log와 Server Log로 원인, 영향, 조치를 정리하기

CUBRID EOL 대응 가이드:
운영 DB 업그레이드 계획 수립하기

테스트 코드에서 바로 띄우는
CUBRID 통합 테스트 환경

CUBRID 전환 후 성능 이슈 분석:
SQL 문법보다 실행 패턴이 중요하다