대상: CloudBeaver Community Edition 25.x 계열 (2026년 테스트 됨)
목적: Hive 4 · Impala · Phoenix · OpenSearch 드라이버를 포함한 Docker 이미지를 빌드하고 운영한다
공식 CloudBeaver CE 이미지에는 PostgreSQL · MySQL · Oracle 같은 기본 드라이버만 활성화되어 있다. Hadoop 에코시스템 드라이버(Hive · Impala · Phoenix)와 OpenSearch 는 다음 이유로 기본 이미지에서 쓸 수 없다.
| 드라이버 | 비활성화 원인 | 해결 방법 |
|---|---|---|
| Apache Hive 4+ | drivers.base 에 미등록 | plugin.xml 패치 |
| Cloudera Impala | supportsDistributedMode="false" + 드라이버 클래스 불일치 |
plugin.xml 패치 + JDBC JAR 교체 |
| Apache Phoenix | supportsDistributedMode 미설정 (기본값 false) |
plugin.xml 패치 + JDBC JAR 추가 |
| OpenSearch | supportsDistributedMode 미설정 (기본값 false) |
plugin.xml 패치 + JDBC JAR 추가 |
핵심 원인은 CloudBeaver 가 distributed/multiuser 모드로 실행된다는 점이다. 드라이버의 supportsDistributedMode 속성이 true 가 아니면 getEnabledDrivers() 에서 자동으로 제외된다.
| 드라이버 | JDBC 클래스 | 기본 포트 | JDBC URL 형식 |
|---|---|---|---|
| Apache Hive 4+ | org.apache.hive.jdbc.HiveDriver |
10000 | jdbc:hive2://<host>:10000/<db> |
| Cloudera Impala | com.cloudera.impala.jdbc.Driver |
21050 | jdbc:impala://<host>:21050/<db> |
| Apache Phoenix | org.apache.phoenix.jdbc.PhoenixDriver |
2181 | jdbc:phoenix:<host>:2181 |
| OpenSearch | org.opensearch.jdbc.Driver |
443 | jdbc:opensearch://https://<host>:443 |
| 항목 | 최소 사양 | 비고 |
|---|---|---|
| OS | Linux (RHEL/Rocky 9, Ubuntu 22.04 이상) | Docker 실행 가능한 환경 |
| Docker | 20.10 이상 | docker version 으로 확인 |
| Java (JDK) | 11 이상 | jar 명령을 쓴다 (빌드 시에만 필요) |
| Python | 3.6 이상 | plugin.xml 패치 스크립트용 |
| 디스크 | 2 GB 이상 여유 | 이미지 빌드용 |
| 메모리 | 2 GB 이상 | CloudBeaver 서버 실행용 |
작업 디렉터리는 /root/cloudbeaver 로 두고, 아래 스크립트는 그 밑의 scripts/ 에 둔다. 스크립트 01-prerequisites.sh 가 Docker · Java · Python 설치 여부를 확인하고 작업 디렉터리를 만든다.
스크립트 02-download-drivers.sh 가 각 드라이버의 JDBC JAR 를 내려받는다.
| 파일명 | 출처 | 비고 |
|---|---|---|
hive-jdbc-4.0.1-standalone.jar |
Maven Central | Apache Hive 4+ |
ImpalaJDBC42.jar |
Cloudera 공식 사이트 | 수동 다운로드 필요 |
phoenix-client-hbase-2.6.0.jar |
Maven Central | Apache Phoenix |
opensearch-sql-jdbc-1.4.0.1.jar |
Maven Central | OpenSearch |
Impala JDBC JAR 은 Maven Central 에 없다. Cloudera 다운로드 페이지에서 직접 내려받아 /root/cloudbeaver/ImpalaJDBC42.jar 에 둔다.
커스텀 드라이버가 필요 없으면 스크립트 03-run-official.sh 로 공식 이미지를 바로 실행한다.
| 설정 | 기본값 | 설명 |
|---|---|---|
| 웹 포트 | 8978 | http://<서버IP>:8978 로 접속 |
| 데이터 볼륨 | cloudbeaver-workspace |
설정 · 연결 정보 영구 저장 |
| 관리자 계정 | 최초 접속 시 생성 | 웹 UI 에서 설정 |
초기 설정은 브라우저에서 http://<서버IP>:8978 에 접속해 서버 설정 마법사(언어 · 관리자 계정 생성)를 진행한 뒤 New Connection 으로 데이터베이스 연결을 추가하는 순서다.
공식 이미지 → JAR 추출 → plugin.xml 패치 → JDBC JAR 추가 → 커스텀 이미지
빌드는 세 단계로 이루어진다.
| 단계 | 내용 |
|---|---|
| STEP 1. drivers.base 패치 | 드라이버 활성화 등록 |
| STEP 2. ext.generic 패치 | 드라이버 속성 수정 (supportsDistributedMode · 클래스명 · file 태그) |
| STEP 3. Docker 이미지 빌드 | 패치된 JAR + JDBC JAR 를 포함한 이미지 생성 |
스크립트 04-patch-drivers-base.sh 가 담당한다. io.cloudbeaver.resources.drivers.base 플러그인의 plugin.xml 은 CloudBeaver 에서 활성화할 드라이버를 제어한다. 세 개의 extension point 에 각각 등록해야 한다.
<!-- 1. 리소스 매핑 (드라이버 디렉토리) -->
<extension point="org.jkiss.dbeaver.resources">
<resource name="drivers/impala"/>
</extension>
<!-- 2. 번들 등록 (JAR 로딩 조건) -->
<extension point="org.jkiss.dbeaver.product.bundles">
<bundle id="drivers.impala" label="Cloudera Impala JDBC drivers"/>
</extension>
<!-- 3. 드라이버 활성화 (provider:driver_id 형식) -->
<extension point="io.cloudbeaver.driver">
<driver id="generic:cloudera_impala"/>
</extension>
세 곳 모두 등록하지 않으면 드라이버가 나타나지 않는다.
스크립트 05-patch-ext-generic.sh (Python 스크립트 포함)가 담당한다. org.jkiss.dbeaver.ext.generic 플러그인에 정의된 드라이버의 속성을 수정한다.
| 드라이버 | 패치 내용 |
|---|---|
| Impala | supportsDistributedMode → "true", 클래스 jdbc41.Driver → jdbc.Driver, <file> 태그 추가 |
| Phoenix | supportsDistributedMode="true" 속성 추가, <file> 태그 추가 |
| OpenSearch | supportsDistributedMode="true" 속성 추가, <file> 태그 추가 |
Impala 클래스를 고치는 이유는 DBeaver 정의가 com.cloudera.impala.jdbc41.Driver 인데 ImpalaJDBC42.jar 에는 com.cloudera.impala.jdbc.Driver 만 있기 때문이다.
스크립트 06-build-image.sh 가 모든 패치와 빌드를 한 번에 수행한다.
cd /root/cloudbeaver
bash scripts/06-build-image.sh
빌드가 끝나면 다음과 같은 검증 출력이 나온다.
Available drivers: Hadoop / Apache Hive 4+,ClickHouse,...,Hadoop / Cloudera Impala,...,Apache Phoenix,OpenSearch,...
스크립트 07-run-custom.sh 로 실행한다. Docker Compose 를 쓰면 scripts/docker-compose.yml 을 쓴다.
docker run -d -p 8978:8978 \
-v cloudbeaver-workspace:/opt/cloudbeaver/workspace \
--name cloudbeaver cloudbeaver-custom:latest
기존 컨테이너를 교체할 때 workspace 볼륨을 삭제하면 모든 설정이 초기화된다. 연결 정보를 유지하려면 볼륨을 지우지 않는다.
| 항목 | 값 |
|---|---|
| 드라이버 | Apache Hive 4+ |
| 호스트 | HiveServer2 주소 |
| 포트 | 10000 |
| JDBC URL | jdbc:hive2://<host>:10000/<database> |
| 인증 | 환경에 따라 None / LDAP / Kerberos |
| 항목 | 값 |
|---|---|
| 드라이버 | Cloudera Impala |
| 호스트 | Impala Daemon 주소 |
| 포트 | 21050 |
| JDBC URL | jdbc:impala://<host>:21050/<database> |
| 인증 | AuthMech=0 (없음), AuthMech=3 (LDAP) |
| SSL | URL 에 ;SSL=1 추가 |
| 항목 | 값 |
|---|---|
| 드라이버 | Apache Phoenix |
| 호스트 | ZooKeeper 주소 |
| 포트 | 2181 |
| JDBC URL | jdbc:phoenix:<host>:2181 |
| 항목 | 값 |
|---|---|
| 드라이버 | OpenSearch |
| 호스트 | OpenSearch 클러스터 주소 |
| 포트 | 443 (HTTPS) 또는 9200 (HTTP) |
| JDBC URL | jdbc:opensearch://https://<host>:443 |
서버 로그에서 드라이버 목록을 확인한다.
docker logs cloudbeaver 2>&1 | grep "Available drivers"
| 증상 | 원인 | 해결 |
|---|---|---|
| 전체 드라이버 목록이 비어 있음 | MANIFEST.MF 손상 | jar uf 만 사용, MANIFEST 직접 수정 금지 |
| 특정 드라이버만 없음 (에러 없음) | supportsDistributedMode 미설정 |
ext.generic plugin.xml 에서 속성 추가 |
| "missing library" 에러 | JDBC JAR 없거나 경로 불일치 | drivers/ 디렉터리에 JAR 복사 |
| 에러도 없고 목록에도 없음 | drivers.base 에 미등록 | 3개 extension point 모두 확인 |
mkdir: cannot create directory 'workspace/.metadata': Permission denied
공식 이미지는 root 사용자로 실행한다. Dockerfile 에 USER 지시문을 추가하지 않는다.
볼륨을 초기화하고 다시 시작한다. 연결 정보는 사라진다.
docker rm -f cloudbeaver
docker volume rm cloudbeaver-workspace
docker run -d -p 8978:8978 \
-v cloudbeaver-workspace:/opt/cloudbeaver/workspace \
--name cloudbeaver cloudbeaver-custom:latest
[OSGi Extension Registry]
↓
[WebDriverRegistry.loadExtensions()]
→ io.cloudbeaver.driver extension point에서 드라이버 ID 수집
→ webDrivers Set에 저장
↓
[WebDriverRegistry.refreshApplicableDrivers()]
→ DataSourceProviderRegistry.getEnabledDataSourceProviders()
→ 각 provider의 getEnabledDrivers() ← 여기서 supportsDistributedMode 체크
→ filter: isDriverApplicable() ← 여기서 webDrivers.contains(fullId) 체크
→ filter: isDriverLibraryFilePresent() ← 여기서 JAR 존재 여부 체크
↓
[Available drivers 로그 출력]
for (DriverDescriptor driver : drivers) {
if (driver.isDisabled()) continue; // 1. 비활성화 여부
if (driver.getReplacedBy() != null) continue; // 2. 대체 드라이버 여부
if (!driver.isSupportedByLocalSystem()) continue; // 3. OS/배포모드 지원
enabledDrivers.add(driver);
}
if (DBWorkbench.isDistributed() || application.isMultiuser()) {
return this.supportsDistributedMode; // CloudBeaver는 항상 이 경로
}
// Desktop DBeaver 전용 로직 (OS 체크 등)
| 방법 | 결과 | 사용 여부 |
|---|---|---|
jar cf (새로 생성) |
MANIFEST.MF 손상 → OSGi 번들 로딩 실패 | 사용 금지 |
jar uf (업데이트) |
MANIFEST 보존 → 안전 | 사용 |
| MANIFEST.MF 직접 수정 | SHA-384 해시 불일치 → 드라이버 전체 사라짐 | 사용 금지 |
드라이버 ID 는 provider:driver_id 형식이다. getFullId() = getProviderId() + ":" + getId().
| 드라이버 | provider | driver_id | fullId |
|---|---|---|---|
| Hive 4+ | hive | apache_hive4 | hive:apache_hive4 |
| Impala | generic | cloudera_impala | generic:cloudera_impala |
| Phoenix | generic | phoenix_hbase | generic:phoenix_hbase |
| OpenSearch | generic | opensearch | generic:opensearch |
| Trino | generic | trino_jdbc | generic:trino_jdbc |
/root/cloudbeaver/
├── scripts/
│ ├── 01-prerequisites.sh # 사전 준비 (환경 확인)
│ ├── 02-download-drivers.sh # JDBC JAR 다운로드
│ ├── 03-run-official.sh # 공식 이미지 실행
│ ├── 04-patch-drivers-base.sh # drivers.base plugin.xml 패치
│ ├── 05-patch-ext-generic.sh # ext.generic plugin.xml 패치 (Python)
│ ├── 06-build-image.sh # 전체 빌드 통합 스크립트
│ ├── 07-run-custom.sh # 커스텀 이미지 실행
│ └── docker-compose.yml # Docker Compose 파일
├── ImpalaJDBC42.jar # (수동 다운로드)
├── hive-jdbc-4.0.1-standalone.jar # (스크립트로 다운로드)
├── phoenix-client-hbase-2.6.0.jar # (스크립트로 다운로드)
└── opensearch-sql-jdbc-1.4.0.1.jar # (스크립트로 다운로드)
스크립트 본문은 이 문서에 실려 있지 않다. 원본 작업 디렉터리에서 가져와야 한다.