Skip to main content
LibreDB Studio는 브라우저에서 실행되는 오픈 소스(MIT) 자체 호스팅 SQL IDE입니다. JDBC나 네이티브 드라이버 없이 HTTP 인터페이스를 통해 ClickHouse에 연결하며, SQL 편집기, 데이터베이스 브라우저, EXPLAIN 실행 계획, system 테이블을 기반으로 한 모니터링 대시보드를 제공합니다.

시작하기 전에

  • Docker(docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest) 또는 Node.js 24 이상(npx @libredb/studio)으로 LibreDB Studio를 실행한 다음 http://localhost:3000을 여십시오. 처음 실행하면 관리자 비밀번호가 로그에 출력됩니다.
  • LibreDB Studio를 실행하는 머신에서 ClickHouse HTTP 또는 HTTPS 포트에 접근할 수 있는지 확인하십시오.
  • 쿼리할 데이터베이스에 액세스할 수 있는 ClickHouse 사용자를 생성하십시오. 데이터베이스 브라우저를 사용하려면 system.dictionaries 및 system.data_skipping_indices에 대한 SELECT 권한과, 딕셔너리가 있는 각 데이터베이스에 대한 dictGet 권한도 필요합니다. 대시보드를 사용하려면 ClickHouse 모니터링에 나열된 system 테이블에 SELECT 권한을 부여하십시오.
예를 들어, uk 데이터베이스를 쿼리하는 사용자 reader는 다음과 같이 설정합니다.

작동 방식

  1. 브라우저가 SQL 문을 LibreDB Studio 서버로 전송합니다.
  2. 서버는 이 SQL 문을 HTTP POST / 요청의 body에 담아 ClickHouse로 전송합니다. 이때 default_format=JSONCompact와 선택한 데이터베이스는 URL 매개변수로, 자격 증명은 HTTP 기본 인증으로 전달합니다.
  3. 서버는 결과 행(rows)과 함께 ClickHouse가 선언한 컬럼 타입, ClickHouse가 보고한 경과 시간을 반환합니다. 각 SQL 문은 독립적인 상태 비저장 요청으로 처리되며, 세션을 고정하지 않습니다.

자체 호스팅 ClickHouse에 연결

1

연결 정보 확인

호스트, HTTP 포트(기본값 8123, 또는 서버에서 사용하는 HTTPS 포트로 보통 8443), 사용자 이름과 비밀번호가 필요하며, 필요에 따라 데이터베이스 이름도 지정할 수 있습니다. 데이터베이스를 지정하지 않으면 default가 사용됩니다.
2

연결 생성

  1. 사이드바에서 + (New connection)를 선택합니다.
  2. 데이터베이스 유형으로 ClickHouse를 선택합니다. 포트에는 8123이 자동으로 입력됩니다.
  3. 연결 이름, 호스트, 포트, 사용자 이름, 비밀번호를 입력하고, 필요하면 데이터베이스 이름도 입력합니다.
  4. HTTPS를 사용하려면 SSL / TLS를 열고 disable 이외의 SSL 모드를 선택한 다음, Port를 서버의 HTTPS 포트(보통 8443)로 변경합니다. disable 이외의 모든 모드는 LibreDB Studio 서버가 신뢰하는 인증 기관(CA)을 기준으로 서버 인증서를 검증하며, 이것이 verify-system에 해당하는 동작입니다. 이 방식은 ClickHouse Cloud 및 공개적으로 신뢰되는 CA가 발급한 인증서를 사용하는 서버에서 동작합니다. 자체 서명 인증서나 사설 CA 인증서를 사용하는 경우 문제 해결을 참조하십시오.
  5. Test Connection을 선택한 다음 Establish Connection을 선택합니다.
각 필드를 직접 입력하는 대신 Paste URL로 URL을 붙여 넣을 수도 있습니다(예: clickhouse://localhost:8123/default 또는 https://reader:secret@ch.example.com:8443/analytics). https:// URL을 사용하면 TLS가 활성화됩니다.
3

쿼리 실행

연결을 열고 편집기에서 SQL 문을 작성한 후 실행합니다. 데이터베이스 브라우저에는 각 데이터베이스의 테이블, 뷰(view), materialized view, 딕셔너리, 사용자 정의 함수가 표시되며, 컬럼, 기본 키 컬럼(primary key columns), 데이터 건너뛰기 인덱스(data-skipping indexes), 객체 정의도 함께 확인할 수 있습니다.이 예시에서는 UK Property Price 데이터셋을 사용합니다. 해당 가이드의 설명에 따라 데이터를 uk.uk_price_paid에 로드하고 연결의 데이터베이스를 uk로 설정한 다음, 아래 쿼리를 실행하십시오.

ClickHouse 모니터링

모니터링 대시보드는 연결에 설정된 사용자 권한으로 다음 소스를 읽습니다. 사용자에게 이 테이블 중 하나에 대한 권한이 없거나 query_log가 비활성화되어 있으면, 대시보드 전체가 실패하지 않고 해당 패널만 비어 있게 됩니다. system.query_log는 비동기로 플러시되므로, 방금 완료된 SQL 문이 표시되기까지 몇 초가 걸릴 수 있습니다. LibreDB Studio에서는 테이블에 OPTIMIZE TABLE ... FINAL을 실행하거나, 테이블 또는 데이터베이스의 system.parts 요약을 확인하거나, KILL QUERY ... SYNC로 실행 중인 쿼리를 중지할 수도 있습니다. 이러한 작업을 수행하려면 각 작업에 맞는 권한이 필요합니다.

문제 해결

요청은 브라우저가 아니라 LibreDB Studio의 서버가 보내므로, LibreDB Studio를 실행하는 머신 또는 컨테이너에서 호스트에 연결할 수 있어야 합니다. LibreDB Studio는 Docker에서, ClickHouse는 같은 머신에서 실행 중이라면 localhost는 호스트가 아니라 컨테이너를 가리킵니다. 또한 native protocol 포트인 9000이 아니라 HTTP 포트를 입력했는지 확인하십시오.
LibreDB Studio의 서버는 Node.js에서 실행되며, Node.js는 자체 번들에 포함된 공개 CA 목록을 기준으로 서버 인증서를 검증합니다. 따라서 SSL / TLS 아래에 붙여 넣은 CA 인증서는 무시되며, 운영 체제의 인증서 저장소에 CA를 추가하는 것만으로도 충분하지 않습니다. CA 인증서(자체 서명 인증서라면 서버 자체의 인증서)가 담긴 PEM 파일의 경로를 NODE_EXTRA_CA_CERTS 환경 변수로 지정한 상태에서 LibreDB Studio 서버를 시작하십시오. Docker를 사용한다면 해당 파일을 컨테이너에 마운트하고 -e NODE_EXTRA_CA_CERTS=/certs/ca.pem과 같이 전달하십시오.
데이터베이스 브라우저는 각 데이터베이스의 객체를 종류별로 분류할 때 system.dictionaries를 읽고, 테이블 세부 정보를 표시할 때 system.data_skipping_indices를 읽습니다. system.dictionaries에 대한 SELECT 권한이 없으면 객체 목록이 로드되지 않고, system.data_skipping_indices에 대한 SELECT 권한이 없으면 테이블 세부 정보가 열리지 않습니다. 또한 사용자에게 딕셔너리가 속한 데이터베이스에 대한 dictGet 권한이 없으면 해당 딕셔너리는 테이블 아래에 표시됩니다. 시작하기 전에에 설명된 대로 이러한 권한을 부여한 후 브라우저를 새로 고치십시오.
ClickHouse 사용자가 ClickHouse 모니터링에 나열된 system 테이블 중 하나 이상을 읽을 수 없기 때문입니다. 필요한 테이블에 대한 SELECT 권한을 부여한 후 다시 연결하십시오.
느린 쿼리 뷰는 system.query_log를 읽는데, 쿼리 로깅이 꺼져 있으면 이 테이블에는 아무것도 기록되지 않습니다. 해당 사용자에 대해 log_queries 설정을 활성화한 후(예: 사용자의 설정 프로파일(Settings Profile)에서) 쿼리를 몇 개 실행하십시오. 새 항목은 로그가 플러시된 후에 나타나며, 플러시까지 몇 초 정도 걸릴 수 있습니다. 그래도 뷰가 계속 비어 있다면 사용자 단위가 아니라 서버 전체에서 쿼리 로깅이 비활성화되어 있을 수 있습니다. system.query_log에 설명된 대로 서버 구성에 query_log 섹션이 있는지 확인하십시오.

다음 단계