Skip to main content
LibreDB Studio は、ブラウザ上で動作するオープンソース (MIT) のセルフホスト型 SQL IDE です。 JDBC やネイティブドライバーを使わずに HTTP インターフェース経由で ClickHouse に接続でき、SQL エディタ、データベースブラウザ、EXPLAIN による実行計画の表示、 system テーブルを基盤とした監視ダッシュボードを利用できます。

はじめる前に

  • LibreDB Studio を Docker (docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest) または Node.js 24 以降 (npx @libredb/studio) で起動し、http://localhost:3000 を開きます。初回 起動時には、管理者パスワードがログに出力されます。
  • LibreDB Studio を実行するマシンから ClickHouse の HTTP または HTTPS ポートにアクセスできることを確認してください。
  • クエリ対象のデータベースへのアクセス権を持つ ClickHouse ユーザーを作成します。データベースブラウザを使用するには、 system.dictionaries と system.data_skipping_indices に対する SELECT 権限、およびDictionaryを含む 各データベースに対する dictGet 権限も必要です。ダッシュボードを使用する場合は、ClickHouse の監視 に記載されている system テーブルに対する SELECT 権限を付与してください。
たとえば、uk データベースに対してクエリを実行するユーザー reader の場合は、次のようになります。

仕組み

  1. ブラウザがステートメントを LibreDB Studio サーバーに送信します。
  2. サーバーはそのステートメントを HTTP POST / のボディとして ClickHouse に送信します。その際、 default_format=JSONCompact と選択したデータベースは URL パラメータとして、認証情報は HTTP 基本認証で渡します。
  3. サーバーは、結果の行、ClickHouse が宣言したカラム型、ClickHouse が報告した経過時間を 返します。各ステートメントはそれぞれ独立したステートレスなリクエストとして処理され、session は固定されません。

セルフホスト型 ClickHouse に接続する

1

接続情報を準備する

ホスト、HTTP ポート (デフォルトは 8123。HTTPS を使用する場合はサーバーの 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

クエリを実行する

接続を開き、エディタでステートメントを記述して実行します。データベースブラウザには、各 データベースのテーブル、ビュー、materialized view、Dictionary、ユーザー定義関数が一覧表示され、 カラム、主キーカラム、データスキッピングインデックス、オブジェクト定義も確認できます。この例では 英国不動産価格データセット を使用します。 同ガイドの手順に従って uk.uk_price_paid にデータをロードし、接続のデータベースを uk に設定してから、 次のクエリを実行します:

ClickHouse を監視する

監視ダッシュボードは、接続に設定されたユーザーの権限で以下のソースを読み取ります。 ユーザーがこれらのテーブルのいずれかに対する権限を持っていない場合や、query_log が無効になっている場合でも、ダッシュボード全体がエラーになることはなく、該当するパネルが空のままになるだけです。system.query_log は非同期でフラッシュされるため、完了したばかりのステートメントが表示されるまでに数秒かかることがあります。 LibreDB Studio では、テーブルに対する OPTIMIZE TABLE ... FINAL の実行、テーブルまたはデータベース単位での system.parts の概要表示、KILL QUERY ... SYNC による実行中クエリの停止も行えます。これらの操作には、それぞれに対応する権限が必要です。

トラブルシューティング

リクエストを送信するのはブラウザーではなく LibreDB Studio のサーバーであるため、ホストは LibreDB Studio を実行しているマシンまたはコンテナから 接続可能である必要があります。LibreDB Studio を Docker で実行し、ClickHouse を同じマシン上で実行している場合、 localhost はホストではなくコンテナを指します。また、入力したポートがネイティブプロトコルのポート 9000 ではなく HTTP ポートであることを確認してください。
LibreDB Studio のサーバーは Node.js 上で動作しており、Node.js はサーバー証明書を自身に同梱された公開 CA の一覧と照合して検証します。 そのため、SSL / TLS に貼り付けた CA 証明書は無視され、CA をオペレーティングシステムの証明書ストアに追加するだけでも 不十分です。LibreDB Studio のサーバーを起動する際は、NODE_EXTRA_CA_CERTS 環境変数に、CA 証明書 (自己署名の場合はサーバー自身の証明書) を含む PEM ファイルのパスを指定してください。Docker を使用する場合は、 ファイルをコンテナにマウントし、たとえば -e NODE_EXTRA_CA_CERTS=/certs/ca.pem を指定します。
データベースブラウザは、各データベースのオブジェクトを種類別に分類するために system.dictionaries を、 テーブルの詳細を表示するために system.data_skipping_indices を読み取ります。system.dictionaries に対する SELECT 権限がない場合は オブジェクト一覧が読み込まれず、system.data_skipping_indices に対する SELECT 権限がない場合はテーブルの詳細が 開きません。また、ユーザーがそのデータベースに対する dictGet 権限を持っていない間は、Dictionary はテーブルとして一覧に表示されます。 始める前に に示すとおりにこれらの権限を付与し、ブラウザーを更新してください。
ClickHouse ユーザーが、ClickHouse の監視 に記載されている system テーブルの いずれかを読み取れない状態です。必要なテーブルに対する SELECT 権限を付与し、再接続してください。
スロークエリビューは system.query_log を読み取りますが、クエリのログ記録が無効になっている間は何も記録されません。 ユーザーの log_queries 設定を有効にし (たとえばそのユーザーの設定プロファイルで)、いくつかクエリを実行してください。 新しいエントリはログがフラッシュされると表示されますが、これには数秒かかる場合があります。 それでもビューが空のままの場合は、クエリのログ記録がユーザー単位ではなくサーバー全体で無効になっている可能性があります。 system.query_log の説明に従い、 サーバー構成に query_log セクションが存在することを確認してください。

次のステップ