メインコンテンツへスキップ

データ接続

千桐テクノロジー2026/06/11約5分デベロップメントドキュメント

ヒント

さまざまな業務場面におけるデータソース接続要件を満たすため、システムは「データ接続」メニューを提供します。この記事では、この機能を利用して必要なDBまたはAPIデータ接続を自主的に設定および拡張する方法を説明します。

1. データ接続 - SQL

DA_DATASOURCE テーブルは、主にシステムに設定されたデータソース接続情報を記録するために使用します。データソース名（DATASOURCE_NAME）、種別（DATASOURCE_TYPE）、IPアドレス（IP）、ポート番号（PORT）などの通常接続パラメーターを含み、多くのリレーショナルDBの接続管理を支えます。

ただし実際のアプリケーションでは、特に Hive、HBase、Kafka などのビッグデータエコシステム内のデータソースへ接続する場合、接続方式はより複雑になり、必要な設定項目も柔軟です。固定フィールドだけでは完全に網羅できません。そのため、テーブルには DATASOURCE_CONFIG フィールドが用意されており、ユーザー名、パスワード、Kerberos 認証情報、Zookeeper アドレスなどの拡張パラメーターを JSON 文字列として保存します。このフィールドにより、システムはより強い拡張性と適合能力を持ち、複数の異種データソースの動的接続に対応できます。

-- ----------------------------
-- データソーステーブル DM サンプルスクリプト
-- ----------------------------
CREATE TABLE "QDATA"."DA_DATASOURCE"
(
    "ID" BIGINT IDENTITY(49, 1) NOT NULL,
    "DATASOURCE_NAME" VARCHAR2(128) NOT NULL,
    "DATASOURCE_TYPE" VARCHAR2(32) NOT NULL,
    "DATASOURCE_CONFIG" VARCHAR2(3072),
    "IP" VARCHAR2(32) NOT NULL,
    "PORT" INTEGER NOT NULL,
    "LIST_COUNT" INTEGER DEFAULT 0,
    "SYNC_COUNT" INTEGER DEFAULT 0,
    "DATA_SIZE" INTEGER DEFAULT 0,
    "DESCRIPTION" VARCHAR2(512),
    "VALID_FLAG" VARCHAR2(1) DEFAULT 1 NOT NULL,
    "CREATE_BY" VARCHAR2(32),
    "CREATOR_ID" BIGINT,
    "CREATE_TIME" DATETIME(6),
    "UPDATE_BY" VARCHAR2(32),
    "UPDATER_ID" BIGINT,
    "UPDATE_TIME" DATETIME(6),
    "REMARK" VARCHAR2(512),
    "DEL_FLAG" VARCHAR(1) DEFAULT '0' NOT NULL,
    NOT CLUSTER PRIMARY KEY("ID")) STORAGE(ON "MAIN", CLUSTERBTR) ;

COMMENT ON TABLE "QDATA"."DA_DATASOURCE" IS 'データソーステーブル';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."CREATE_BY" IS '作る者';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."CREATE_TIME" IS '作る日時';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."CREATOR_ID" IS '作る者ID';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."DATA_SIZE" IS '同期データサイズ（予約）';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."DATASOURCE_CONFIG" IS 'データソース設定（JSON文字列）';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."DATASOURCE_NAME" IS 'データソース名';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."DATASOURCE_TYPE" IS 'データソース種別';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."DESCRIPTION" IS '説明';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."ID" IS 'ID';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."IP" IS 'IP';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."LIST_COUNT" IS 'DBテーブル数（予約）';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."PORT" IS 'ポート番号';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."REMARK" IS '備考';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."SYNC_COUNT" IS '同期レコード数（予約）';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."UPDATE_BY" IS 'アップデート者';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."UPDATE_TIME" IS 'アップデート日時';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."UPDATER_ID" IS 'アップデート者ID';
COMMENT ON COLUMN "QDATA"."DA_DATASOURCE"."VALID_FLAG" IS '有効かどうか; 0: 無効、1: 有効';

2. データ接続 - 業務コード

データ接続テーブル名 DA_DATASOURCE から分かるように、データソース接続関連の業務コードは qdata-module-da モジュールに属します。このモジュールで、コントローラー層の入口クラスは次の場所にあります。

tech.qiantong.qdata.module.da.controller.admin.datasource

具体的には、中心となるコントローラーは DaDatasourceController であり、データ接続に関するAPIリクエストを処理します。これにはデータソースの加える、編集、接続テストなどの操作が含まれます。

データ接続の業務ロジックを拡張したい場合、たとえば対応DB種別の加える、接続パラメーター構造の調整、検証ロジックの拡張などは、このクラスから着手できます。同時に、その下位の service 層なども連動して変更する必要があります。

3. データ接続 - ユーティリティメソッド

データ接続モジュールの service 層まで深く見ると、JDBC との基盤的な連携ロジックは各業務クラスで個別に実装されているのではなく、統一的に封装され、共通メソッドパッケージへ向いていることが分かります。

この共通パッケージは qdata-framework モジュール配下の qdata-common サブモジュールにあり、具体的なパスは次のとおりです。

tech.qiantong.qdata.common.database

このパッケージでは、DB連携に関するすべての機能が統一的に封装されています。主な内容は次のとおりです。

  • データソース接続の確立（例: DataSourceFactory）
  • データソース種別に応じた適切な SQL 方言の選択（DbDialect、DialectFactory）
  • DB構造情報の取得（DbQuery、DbQueryFactoryBean）
  • SQL クエリ実行、メタデータ抽出エンティティ（DbTable、DbColumn）
  • キャッシュ機構、例外封装、フィールド型定義などへの対応

📂 パッケージ構造は次のとおりです（主要クラス説明）。

  • datasource: 動的に接続オブジェクトを作るするための抽象ファクトリと既定ファクトリクラスを提供
  • query: クエリ実行ロジックのインターフェースと具体実装を定義
  • dialect: DB種別ごとに SQL 方言適合戦略を封装
  • constants: DB種別、フィールド型、解析方式の列挙などを定義
  • core: 抽象テーブル、フィールド、ページングオブジェクト
  • utils: MD5Util などのユーティリティクラス

この設計により、システムのDB適合能力は大きく向上しています。新しいデータソース種別を加えるする場合、対応する方言とクエリファクトリを実装するだけで、データ接続モジュール全体へシームレスに接続でき、拡張性とコード分離性を確保できます。

4. 新しいデータソース種別の拡張（デベロップメントフロー）

上記のデータ接続共通メソッド体系の説明をよく読んだなら、全体構造をある程度理解できているはずです。次に、MySQL データソースの拡張を例として、データソース種別加えるのフローを一通り説明します。これにより、Hive、ClickHouse など他のDBを後から接続しやすくなります。

1. DbType 列挙クラスにデータソース種別を加える

パス: tech.qiantong.qdata.common.database.constants.DbType

/**
 * MYSQL
 */
MYSQL("MySql",
      "MySql database",
      "jdbc:mysql://${host}:${port}/${dbName}?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8",
      "LENGTH",
      "SELECT COUNT(1) FROM {tableName}",
      "SELECT {tableFieldName} FROM {tableName} ORDER BY {orderBy} DESC LIMIT ({pageNo}-1)*{pageSize},{pageSize}");

各データソース列挙項目には次が含まれます。

  • データソース識別子
  • 閲覧名
  • JDBC URL テンプレート
  • フィールド長取得関数
  • レコード数クエリ SQL テンプレート
  • ページングクエリ SQL テンプレート

2. 対応する Dialect クラス（方言パーサー）を作る

パス: tech.qiantong.qdata.common.database.dialect

クラス名は MySqlDialect などとし、抽象クラスを継承する必要があります。

public class MySqlDialect extends AbstractDbDialect {
    // 親クラスの抽象メソッドを実装
}

3. 方言ロジックを実装

MySqlDialect で、AbstractDbDialect が定義する主なメソッドを実装します。例:

  • tables
  • columns
  • buildQuerySqlFields
  • someInternalSqlGenerator

既存DBの実装を参考にするか、DbQuery インターフェースの説明を確認してください。

4. 新しい方言を方言ファクトリへ登録

パス: DialectRegistry.java
場所: tech.qiantong.qdata.common.database.dialect.DialectRegistry

コンストラクター内で新しい方言をマッピングテーブルへ登録します。

public DialectRegistry() {
    ...
    dialect_enum_map.put(DbType.MYSQL, new MySqlDialect());
    ...
}

DbType 列挙値と登録項目が一致していることを確認してください。

5. ここまでで、データソース加えるの主な作業は完了です。

システムがデータソース関連機能（テーブル作る文生成、フィールド抽出、ページングクエリなど）を処理するとき、DbType に基づいて実装した Dialect クラスを自動的に呼び出し、異なるDBへの接続適合を実現します。

5. 加えるの拡張メモ

1. 特殊データ接続（HDFS、HBase、Kafka など）

HDFS、HBase、Kafka など、JDBC で標準接続を確立できないデータソースについては、接続方式が従来のDBとは少し異なります。このようなデータソースは、データ接続モジュールで次の特別な処理が必要です。

(1) 設定保存方式

この種の特殊データソースに必要な接続パラメーター（Zookeeper アドレス、認証情報、トピック名など）は、DATASOURCE_CONFIG フィールドに統一して保存されます。このフィールドは JSON 形式で、柔軟な拡張を支えます。

(2) 接続コンテキストオブジェクト（DbQueryProperty）の構築

DBファクトリメソッド createDbQuery() を呼び出す前に、DbQueryProperty を構築する必要があります。ここにはホストアドレス、ポート、DB名などの通常フィールドが含まれます。

このような特殊データソースでは、加えるの接続パラメーターを互換的に config フィールドへ書き込む必要があります。

DbQueryProperty dbQueryProperty = new DbQueryProperty();
dbQueryProperty.setHost("kafka-host");
dbQueryProperty.setPort(9092);
dbQueryProperty.setConfig(Map.of(
  "security.protocol", "SASL_PLAINTEXT",
  "sasl.mechanism", "PLAIN"
));

(3) カスタム接続検証ロジックを実装（Kafka の例）

Kafka 接続テストでは、JDBC 接続ではなく Kafka AdminClient を使ってテストするため、validConnection メソッドを独自実装する必要があります。

@Override
public Boolean validConnection(DataSource dataSource, DbQueryProperty dbQueryProperty) {
    Properties props = new Properties();
    props.put("bootstrap.servers", dbQueryProperty.getHost() + ":" + dbQueryProperty.getPort());
    props.put("default.api.timeout.ms", 10000);
    props.put("request.timeout.ms", 10000);
    props.put("admin.request.timeout.ms", 10000);

    if (dbQueryProperty.getConfig() != null && !dbQueryProperty.getConfig().isEmpty()) {
        dbQueryProperty.getConfig().forEach(props::put);
    }

    String topic = "TEST_TOPIC_" + UUID.randomUUID();
    AdminClient admin = AdminClient.create(props);
    try {
        admin.createTopics(Collections.singleton(new NewTopic(topic, 1, (short) 1))).all().get();
        admin.deleteTopics(Collections.singleton(topic)).all().get();
        return true;
    } catch (Exception e) {
        throw new DataQueryException("Kafka 接続に失敗しました。後でもう一度お試しください");
    } finally {
        try {
            admin.close();
        } catch (Exception e) {
            throw new DataQueryException("Kafka 接続のクローズに失敗しました");
        }
    }
}

(4) その他データソース種別の適合

HDFS、HBase などその他の非リレーショナルデータソースについては、Kafka と同様に、対応する DbQuery 実装クラスで次を行います。

  • DbQueryProperty.config から必要パラメーターを取得
  • FileSystem、HBaseAdmin などの接続初期化ロジックを独自実装
  • valid() またはその他関連メソッドをオーバーライド

📝 まとめ:
特殊データソースの適合原則は、設定情報の JSON 化、接続フローの戦略化、API 呼び出しの統一化です。これにより、各種データソースが統一ファクトリ機構を通じて登録、初期化、検証できるようになります。

2. ページ設定

ここまでで、新しいデータソース種別のバックエンド拡張は完了しました。ただし、フロントエンドページで設定しなければ、そのデータソース種別はまだ選択できません。この場合、システム管理 → 辞書管理メニューで対応する設定を行う必要があります。

具体的な操作は次のとおりです。

  • システム管理モジュール → 辞書管理ページを開く
  • 辞書種別 datasource_type を見つける
  • その辞書項目に辞書値を加えるします。辞書コードはバックエンドの DbType 列挙名と一致させる必要があります。例: KAFKA、CLICKHOUSE

設定完了後、フロントエンドページのデータソース加えるフォームに対応する種別選択肢が閲覧され、ページ連動とパラメーター入力に対応します。

まとめ

これで、データ接続モジュールのデベロップメントドキュメントはすべて説明しました。内容には、モジュール構造、主要機能、基盤封装ロジック、新しいデータソース種別を加えるする完全な拡張フローが含まれます。このガイドにより、モジュール全体の設計思想とデベロップメント方法をすばやく理解し、今後のデータソース適合と機能拡張の基礎を築けます。

最終更新:
qData オープンソースデータプラットフォーム
Copyright © 2026 千桐テクノロジー