本記事は「珠玉のアドベントカレンダー記事をリバイバル公開します」企画のために、以前Qiitaに投稿した記事を7年ぶりに改訂したものです。

筆者自身もコミッターとして関わるJavaのDB永続化ライブラリ「uroboroSQL」の紹介です。

https://github.com/future-architect/uroborosql

はじめに

エンタープライズシステム開発では、まだまだJavaで作られていることが多く、システム特性上、やはりRDBを利用するケースが多いですよね。

Amazon AuroraやCloud Spannerといったプロダクトに注目が集まるのも、時代の変化とともにDBも並列分散型でスケールアウトはしたいけれども、トランザクションもSQLも使いたいというCAP定理を覆す特徴を持っていることが要因だと思います。

2016/12/24にクリスマス・イブにCockroachDBに負荷をかけてみるという記事を投稿したのですが、このCockroachDBもそんな理想を追い求めるプロダクトで、RDBでNoSQLのメリットを教授したいニーズはもはやエンジニアが切望する夢なんですね✨️

2024年6月追記
現在では、TiDB、yugabyteDBなどの選択肢も増えました。
CockroachDBもしぶとく生き残っていて何よりです。

JavaとRDBの歴史

2000年代前半にJavaで作られたシステムは、JDBCのAPIをそのまま利用することも多かったのですが、その後、Hibernate、iBatis(現在のMyBatis)、SeaserプロジェクトのS2Daoなどをはじめとして、O/Rマッパー(O/Rマッパ)が開発され、利用されるようになりました。

その後、2006年にJPA(Java Persistence API)の1.0がJava標準の永続化フレームワークとして策定され、2009年にJPA2.0、2013年にJPA2.1と、Java SEでも利用はできるのですが、Java EEのEJBと共に進化を続けているという状況ですね。

なお、2017年時点のライブラリ比較については、2017年度 Java 永続化フレームワークについての考察(1)の記事が非常に参考になります（残念ながらこれから紹介するuroboroSQLは入ってません😢）。

2024年6月追記
執筆から6年半ほど経ち、改めて調査してみましたが、大きな変化はないように思います。

ここ数年でアプリケーションフレームワークの領域は、Spring Boot以外に、Quarkus、Micronautのようなマイクロサービス、コンテナネイティブ、ネイティブビルド最適化されたものが登場していますが、O/Rマッパは独立して選定されているように感じます。
（SpringBootの場合、王道的にSpring Data JPAを選定しているケースも多いとは思います）

uroboroSQLとは

uroboroSQLは、JavaにおけるDB永続化ライブラリの1つであり、基本的にはJavaからSQLを生成することよりも、SQLに足りないところをJavaで補うアプローチを採用しています。

もちろん、1レコードのINSERT/UPDATE/DELETEでSQLをいちいち書くのも辛いので、O/RマッパとしてのAPIも提供しています。

2017年にOSSとして公開後も、社内で脈々と使い続け、都度フィードバックを受けて、2024年6月現在までバージョンアップを継続しています。

特徴的な機能

開発時に便利なREPL機能搭載

2Way-SQLでの開発時にビルド不要で即試すことが可能です。

カバレッジレポート

SQL文の条件分岐を集計してカバレッジレポートを行うことが可能です。

その他の特徴

[object Object] undefined

※2024/06/25時点最新バージョンとなるv0.26.8時点

uroboroSQLのコードサンプル

さて、ライブラリを理解するには、利用時にどんな実装になるのか見るのが手っ取り早いですよね。
というわけで、よく利用する実装をサンプルとして、まとめました。

2017年の初版執筆時点では、公式ドキュメントよりも豊富だと思っていましたが、2024年時点では公式ドキュメントが充実していますので、是非こちら↓もご覧ください。
https://future-architect.github.io/uroborosql-doc/

接続

SqlConfig config = UroboroSQL.builder("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1", "sa", "sa").build();

トランザクション

[object Object] undefined

try (SqlAgent agent = config.agent()) {
  //
  agent.required(() -> {
    // insert/update/delete
  });

  agent.requiresNew(() -> {
    // insert/update/delete
  });
}

SQLファイルインタフェース（2way-SQL）

department/select_department.sql

SELECT /* _SQL_ID_ */
    DEPT.DEPT_NO    AS  DEPT_NO
,   DEPT.DEPT_NAME  AS  DEPT_NAME
FROM
    DEPARTMENT  DEPT
WHERE
    1               =   1
/*IF SF.isNotEmpty(dept_no)*/
AND DEPT.DEPT_NO    =      /*dept_no*/1
/*END*/
/*IF SF.isNotEmpty(dept_name)*/
AND DEPT.DEPT_NAME  LIKE   '%' || /*dept_name*/'' || '%'
/*END*/

department/insert_department.sql

INSERT /* _SQL_ID_ */
INTO
    DEPARTMENT
(
    DEPT_NO
,   DEPT_NAME
) VALUES (
    /*dept_no*/1
,   /*dept_name*/'sample'
)

department/update_department.sql

UPDATE /* _SQL_ID_ */
    DEPARTMENT  DEPT
SET
    DEPT.DEPT_NAME      =   /*dept_name*/'sample'
    DEPT.LOCK_VERSION   =   DEPT.LOCK_VERSION   +   1
WHERE
    DEPT.DEPT_NO        =   /*dept_no*/1
AND DEPT.LOCK_VERSION   =   /*lock_version*/0

department/delete_department.sql

DELETE /* _SQL_ID_ */
FROM
    DEPARTMENT  DEPT
WHERE
    DEPT.DEPT_NO    =   /*dept_no*/1

S2Dao等と同じ文法で、SQL内でコメント標記で分岐を記述することができます。

SELECT(リスト取得)

try (SqlAgent agent = config.agent()) {
  List<Map<String, Object>> deptList =
    agent.query("department/select_department")
      .param("dept_name", "retail")
      .collect();
}

SELECT(Stream取得、Map型)

try (SqlAgent agent = config.agent()) {
  Stream<Map<String, Object>> depts =
    agent.query("department/select_department")
      .param("dept_name", "retail")
      .stream();
}

SELECT(Stream取得、モデル型)

try (SqlAgent agent = config.agent()) {
  Stream<Department> depts =
    agent.query("department/select_department")
      .param("dept_name", "retail")
      .stream(Department.class);
}

SELECT(1件取得、Map型、取得できない場合例外)

try (SqlAgent agent = config.agent()) {
  Map<String, Object> dept =
    agent.query("department/select_department")
      .param("dept_no", 1001)
      .first();
}

SELECT(1件取得、モデル型、取得できない場合例外)

try (SqlAgent agent = config.agent()) {
  Department dept =
    agent.query("department/select_department")
      .param("dept_no", 1001)
      .first(Department.class);
}

SELECT(1件取得、Map型、Optional)

try (SqlAgent agent = config.agent()) {
  Map<String, Object> dept =
    agent.query("department/select_department")
      .param("dept_no", 1001)
      .findFirst()
      .orElse(null);
}

SELECT(1件取得、モデル型、Optional)

try (SqlAgent agent = config.agent()) {
  Department dept =
    agent.query("department/select_department")
      .param("dept_no", 1001)
      .findFirst(Department.class)
      .orElse(null);
}

SELECT(1件のみ取得、モデル型、取得できない場合と2件以上取得した場合に例外)

try (SqlAgent agent = config.agent()) {
  Department dept =
    agent.query("department/select_department")
      .param("dept_no", 1001)
      .one(Department.class);
}

INSERT/UPDATE/DELETE

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    // insert
    agent.update("department/insert_department")
      .param("dept_no", 1001)
      .param("dept_name", "sales")
      .count();
    // update
    agent.update("department/update_department")
      .param("dept_no", 1001)
      .param("dept_name", "HR")
      .count();
    // delete
    agent.update("department/delete_department")
      .param("dept_no", 1001)
      .count();
  });
}

INSERT/UPDATE/DELETE(バッチ実行)

List<Map<String, Object>> inputList = new ArrayList<>();
// 中略

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    // default configuration
    agent.batch("department/insert_department")
      .paramStream(inputList.stream())
      .count();

    // custom configuration
    agent.batch("department/insert_department")
      .paramStream(inputList.stream())
      .by((ctx, row) -> ctx.batchCount() == 100)  // 100件毎にSQL実行
      .batchWhen((agent, ctx) -> agent.commit())  // SQL実行が成功したらコミットする
      .errorWhen((agent, ctx, ex) -> {
        // 例外が発生したらログ出力する
        log.error("error occured. ex:{}", ex.getMessage());
      })
      .count();
  });
}

DAOインタフェース

下記のようなモデルクラスがある前提とします。

@Data
@Table(name = "DEPARTMENT")
public class Department {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private int deptNo;
  private String deptName;
  private String location;

  @Version
  private int lockVersion = 0;
}

@Id/@GeneratedValueが付与されたフィールドはDBの自動採番を利用することをマークします。
@Versionが付与されたフィールドは楽観ロック用のバージョン情報としてuroboroSQLが認識し、UPDATE時にはSET句で+1され、WHERE句の検索条件に追加されてSQLを発行し、更新件数が0の場合にOptimisticLockExceptionを発生させます。

SELECT(主キー検索)

try (SqlAgent agent = config.agent()) {
  Department dept =
      agent.find(Department.class, 1001).orElse(null);
}

SELECT(条件指定検索、ソート順、悲観ロック)

try (SqlAgent agent = config.agent()) {
  // dept_no = 1 のレコードをList<Department>で取得
  List<Department> deptList = agent.query(Department.class)
    .equal("dept_no", 1)
    .collect();

  // dept_no = 10 又は 20 のレコードをList<Department>で取得
  List<Department> deptList = agent.query(Department.class)
    .in("dept_no", 10, 20)
    .collect();

  // dept_name like '%Sales%' のレコードをList<Department>で取得
  List<Department> deptList = agent.query(Department.class)
    .contains("dept_name", "Sales")
    .collect();

  // where句を直接記述(dept_name = 'Sales' and location = 'Boston')した結果をList<Employee>で取得
  List<Department> deptList = agent.query(Department.class)
    .where("dept_name =''/*deptName*/", "deptName", "Sales")
    .where("location = ''/*location*/", "location", "Boston")
    .collect();

  // ソート順
  List<Department> deptList = agent.query(Department.class)
    .desc("dept_no") // 昇順の場合は asc
    .collect();

  // 悲観ロック（SELECT FOR UPDATE)
  Department dept = agent.query(Department.class)
    .equal("dept_no", 1)
    .forUpdate() // forUpdateNoWaitやforUpdateWaitのバリエーションあり
    .collect();
}

INSERT

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    Department hrDept = new Department();
    hrDept.setDeptNo(1002);
    hrDept.setDeptName("HR");
    agent.insert(hrDept);

    // 主キーを自動採番にしている場合に、主キーを取得したエンティティを取得する
    Department insertedDept = agent.insertAndReturn(hrDept);

    // バッチINSERT
    agent.inserts(
      agent.query(Department.class).equal("domestic", false).stream()
        .map(d -> {
          ForeignDepartment fd = new ForeignDepartment();
          fd.setDeptName(d.getDeptName());
          return fd;
        })
    );
  });
}

UPDATE

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    Department dept =
        agent.find(Department.class, 1001).orElseThrow(Exception::new);
    dept.setDeptName("Human Resources");
    agent.update(dept); // 戻り値を返す場合はupdateAndReturnを利用する

    // バッチUPDATE
    agent.updates(
      agent.query(Department.class).stream()
        .map(d -> {
          d.location = "Chicago";
          return d;
        })
    );
  });
}

MERGE

PKによるレコードの検索を行い、レコードがない場合はINSERT、ある場合はUPDATEします。

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    Department hrDept = new Department();
    hrDept.setDeptNo(1002);
    hrDept.setDeptName("HR");
    agent.merge(hrDept); // 悲観ロックする場合はmergeWithLockingを利用する
  });
}

DELETE / TRUNCATE

try (SqlAgent agent = config.agent()) {
  agent.required(() -> {
    // DELETE
    Department dept =
        agent.find(Department.class, 1001).orElseThrow(Exception::new);
    agent.delete(dept); // 戻り値を返す場合はdeleteAndReturnを利用する

    // TRUNCATE
    agent.truncate(Department.class);
  });
}

おわりに

この記事の初版公開から7年ぶりに更新しようとしたら、自分でも驚くほど機能追加されていて、よい振り返りとなりました。
OSSにしても社内プロダクトにしても、継続的にアップデートし続けるのが一番大変だなとしみじみ感じますね。

顧客向けの大規模エンタープライズ開発では、リリースしてから5-10年後にさくっと全部作り直しましょうというケースのほうが稀で、長く使い続けたいというニーズが強いため、下位互換性を失うにしても移行しやすいかどうかも重要なので、これからも継続の価値と意義を再認識して、アップデートを続けていきたいと思います。

参考：uroboroSQLドキュメント、ツール、サンプル

uroboroSQL日本語ドキュメント
- https://future-architect.github.io/uroborosql-doc/
uroboroSQLの紹介 (OSC2017 Nagoya) #oscnagoya
- https://www.slideshare.net/KenichiHoshi1/uroborosql-osc2017-nagoya-oscnagoya
uroboroSQL ソースジェネレータ
- https://github.com/shout-star/uroborosql-generator
uroboroSQL サンプルCLIアプリケーション
- https://github.com/future-architect/uroborosql-sample
uroboroSQL サンプルWebアプリケーション(with Spring Boot)
- https://github.com/shout-star/uroborosql-springboot-demo

エンタープライズJavaで使えるORM「uroboroSQL」まとめ（リバイバル）