uroboroSQL

# 事前準備

uroboroSQLを利用した基本的なDB操作を説明します。

# DB接続

まず最初にSQLを実行するDBへの接続を行います。
DBに接続するためにはSqlConfigインタフェースのインスタンスを生成する必要があります。

SqlConfigインスタンスはUroboroSQLクラスのビルダーメソッドを使用して生成します。

// JDBC接続を行うSqlConfigの生成
// SqlConfig config = UroboroSQL.builder(url, user, password).build();
SqlConfig config = UroboroSQL.builder("jdbc:h2:mem:uroborosql", "sa", "").build();

// DataSourceを使用したDB接続を行うSqlConfigの生成
// SqlConfig config = UroboroSQL.builder(datasource).build();
Context context = new InitialContext();
DataSource dataSource = context.lookup("java:comp/env/jdbc/datasource");
SqlConfig config = UroboroSQL.builder(dataSource).build();
1
2
3
4
5
6
7
8
9
10

UroboroSQLクラスを使ってSqlConfigインスタンスを生成する際、uroboroSQLの挙動を変更する各種の設定も合わせて行うことができます。
設定の詳細については設定を参照してください。

WARNING

SqlConfigインスタンスはアプリケーション内で接続先毎に１つ保持するようにしてください。 SQL実行の都度生成すると、不要なインスタンスの生成やSQLロード処理が実行されます。

# SqlAgentインスタンスの取得

次にすべての操作の基点となるSqlAgentインタフェースのインスタンスを取得します。

try (SqlAgent agent = config.agent()) {
  // この中でSQLの操作を行う
}
1
2
3

SQLの操作はすべてこのSqlAgentインスタンスを使って行うことになります。

TIP

SqlAgentインタフェースはjava.lang.AutoClosableインタフェースを実装しており、try-with-resourcesで記述することで終了時に自動的にclose処理が呼び出され、中で保持しているConnectionやPreparedStatementなどのリソースオブジェクトも正しくクローズされます。

# SQLファイルの配置

uroboroSQLではSQL文の書かれたファイルのパスを指定してSQLを実行することができます。
その際、SQLファイルはクラスパスから参照できる場所に配置されている必要があります。

src
    └─main
        └─resources
            └─sql
                ├─department
                │    ├─insert_department.sql
                │    └─select_department.sql
                └─employee
                     ├─insert_employee.sql
                     └─select_employee.sql
1
2
3
4
5
6
7
8
9
10

上のようなフォルダ構成の場合で、src/main/resources/をクラスパスに指定すれば、 その下のsqlフォルダをルートフォルダとした相対パスでSQLファイルを指定することができます。

TIP

SQLファイルのルートフォルダ（初期値：sql)は変更することができます。
変更方法の詳細は SQLファイルルートフォルダの設定 を参照してください。

# SQL名

SQLファイルの指定する際のファイルパスをSQL名といいます。
上記フォルダ構成の場合、それぞれのSQLファイルは以下のようなSQL名となります。

SQLファイルパス（SQLルートフォルダから） SQL名
department/insert_department.sql department/insert_department
department/select_department.sql department/select_department
employee/insert_employee.sql employee/insert_employee
employee/select_employee.sql employee/select_employee

SQLファイルの配置は設定によりカスタマイズが可能です。SQLファイル配置のカスタマイズについては SQLファイルの解決ルール を参照してください。

# 共通API

検索(SqlQuery (opens new window))、更新(SqlUpdate (opens new window))、バッチ更新(SqlBatch (opens new window))、ストアドプロシージャ実行(Procedure (opens new window))を行うクラスは、バインドパラメータや置換文字列の設定を行うためのAPI(SqlFluent (opens new window))を実装しています。

バインドパラメータや置換文字列の設定はこのAPIを利用して設定を行ってください。
流れるAPI(Fluent API)を採用しているため、値の設定は連続して行うことができるようになっています。

パラメータ設定例

Map<String, Object> department = agent.query("department/select_department")
  .param("dept_no", 1)
  .param("dept_name", "sales")
  .first();
1
2
3
4
主なメソッド 説明
<V> SqlFluent#param(String key, V value) バインドパラメータや置換文字列として使用するキーと値のセットを設定する
<V> SqlFluent#param(String key, V value, SQLType sqlType) SQLTypeを指定して値を設定する
<V> SqlFluent#param(String key, V value, int sqlType) SQLTypeを表すint型を指定して値を設定する
<V> SqlFluent#param(String key, Supplier<V> supplier) supplierの評価結果をキーの値としてパラメータに設定する 0.10.1+
<V> SqlFluent#paramIfAbsent(String key, V value) 指定したキーがまだ登録されていない場合に値を設定する
<V> SqlFluent#paramIfAbsent(String key, V value, SQLType sqlType) 指定したキーがまだ登録されていない場合にSQLTypeを指定して値を設定する
<V> SqlFluent#paramIfAbsent(String key, V value, int sqlType) 指定したキーがまだ登録されていない場合にSQLTypeを表すint型を指定して値を設定する
<V> SqlFluent#paramList(String key, V... value) IN句のバインドパラメータに使用するキーと値のセットを設定する。
0.14.0+ から非推奨。かわりにparam()にArrays.asList()もしくはList.of()を使ってList型に詰めて設定してください
SqlFluent#paramMap(Map<String, ?> paramMap) 引数のMapのKey/Valueのセットをパラメータに設定する
<V> SqlFluent#paramBean(V bean) 引数として渡されたbeanのフィールド名と値のセットをパラメータに設定する

他にもパラメータの型に応じたパラメータ設定メソッドが提供されています。

配列型の指定

DBの種類によっては配列型をサポートしています。（postgresqlなど）
バインドパラメータで配列型を利用する場合、以下のようにJavaの配列を値としてparamメソッドに渡してください

  • Java実装例
agent.query("select_with_array")
  .param("array_values", new String[] {"1", "2"})
  .first();
1
2
3
  • SQL例
select
  st.val
from sample_table st
where 1 = 1
and st.val = ANY(/*array_values*/)
1
2
3
4
5

← SQLファイルインタフェース →