はじめに

今回は、参画中のプロジェクトで使用しているORMフレームワーク Apache Cayenne を使った Spring Boot + PostgreSQL 環境でDB接続を行う手順を備忘録としてまとめます。

Apache Cayenne はニッチなフレームワークということもあり、ネット上では日本語の情報があまり多くありません。もし、Apache Cayenne の使用を検討している方がいれば、本記事が少しでも参考になれば幸いです。

この記事では、Apache Cayenne を使った基本的なDB接続までを扱い、エンティティ設計やCRUDの実装については扱いません。CRUDの実装については続編を投稿予定です。

参考記事:
https://qiita.com/KentOhwada_AlibabaCloudJapan/items/fa145e42bf32271d8d6c

使用環境

Java 21
Spring Boot 3.5.10
Apache Cayenne 4.2.3
PostgreSQL 17
Maven
※バージョンはお好みで設定してください。

プロジェクトの作成

Spring Initializr を使用して、サンプルプロジェクトを作成します。
今回は説明用のため、依存関係は最小限とし、データベース関連の設定は後続の手順で追加します。

DB作成（PostgreSQL）

demo_dbというデータベースを作成し、以下のテーブルを作成しておきます。
本記事では、Apache Cayenne の動作確認を目的として、最小構成の 2 テーブル（1:N）としています。

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL,
    content TEXT NOT NULL,
    CONSTRAINT fk_posts_users
        FOREIGN KEY (user_id)
        REFERENCES users(id)
);

プロジェクトの設定

作成した Spring Boot プロジェクトに対して、
Apache Cayenne を利用し、PostgreSQL に接続するための設定を行います。
まずは、Apache Cayenne本体とPostgreSQLのJDBCドライバを利用するため、pom.xml に以下の依存関係を追加します。

pom.xml

<dependency>
    <groupId>org.apache.cayenne</groupId>
	<artifactId>cayenne-server</artifactId>
	<version>4.2.3</version>
</dependency>

<dependency>
	<groupId>org.postgresql</groupId>
	<artifactId>postgresql</artifactId>
	<version>42.7.3</version>
	<scope>runtime</scope>
</dependency>

Apache Cayenne Modeler について

Apache Cayenne には、
データベースと Java クラス（エンティティ）とのマッピングを GUI で設計・管理できる公式ツールとして Cayenne Modeler が用意されています。

Cayenne Modeler では、以下の情報を管理できます。

データベースのテーブル構造
Java のエンティティクラス
両者のマッピング定義

これらをXML形式のマッピングファイルで管理します。
Cayenne Modeler は、このマッピングファイルを作成・編集するための専用ツールです。
こちらでダウンロードできます。
※2026/02/01時点での最新安定版は4.2.3となっております。

Cayenne Modeler を Maven プラグインとして利用する

Cayenne Modeler は Maven プラグインとしてプロジェクトに組み込むことで、コマンドラインから起動できます。
そのため、pom.xml に Cayenne Modeler 用の Maven プラグインを定義しておく必要があります。
以下の設定を pom.xml に追加します。

pom.xml

<plugin>
    <groupId>org.apache.cayenne.plugins</groupId>
	<artifactId>cayenne-modeler-maven-plugin</artifactId>
	<version>4.2.3</version>
    <configuration>
        <modelFile>${project.basedir}/src/main/resources/cayenne-demo.xml</modelFile>
    </configuration>
</plugin>

設定後、以下のコマンドでプロジェクトをビルドします。

mvn clean install

続いて、以下のコマンドを実行すると Cayenne Modeler が起動します。

mvn cayenne-modeler:run

下記のような画面が表示されれば、起動は成功です。

Cayenne Maven Plugin について

cayenne-maven-plugin は、
Cayenne Modeler で作成したマッピングファイルをもとに、
対応する Java のエンティティクラスを自動生成するための Maven プラグインです。

このプラグインを実行することで、

データベースのテーブルに対応したエンティティクラス
テーブル間のリレーションを表すクラス定義

が Java コードとして生成されます。

では、cayenne-maven-pluginをpom.xmlに追加してみます。

pom.xml

<plugin>
    <groupId>org.apache.cayenne.plugins</groupId>
	<artifactId>cayenne-maven-plugin</artifactId>
	<version>4.2.3</version>

    <configuration>
        <!-- Cayenne のマッピングファイル -->
        <map>${project.basedir}/src/main/resources/demo.map.xml</map>
        
        <!-- データベース接続設定 -->
    	<dataSource>
        	<driver>org.postgresql.Driver</driver>
    		<url>jdbc:postgresql://localhost:5432/demo_db</url>
    		<username>設定したusername</username>
    		<password>設定したpassword</password>
    	</dataSource>

        <!-- DB → エンティティ生成設定 -->
    	<dbImport>
    		<defaultPackage>com.example.demo.cayenne</defaultPackage>
    		<schema>public</schema>
    	</dbImport>
    </configuration>
    
     <!-- DB Import 時に使用する JDBC ドライバ -->
    <dependencies>
        <dependency>
        	<groupId>org.postgresql</groupId>
    		<artifactId>postgresql</artifactId>
    		<version>42.7.3</version>
    	</dependency>
    </dependencies>
</plugin>

設定後、以下のコマンドを実行し、
データベースの構造を読み込んでマッピングファイルを生成します。

mvn cayenne:cdbimport

下記のようなログが出力されれば、
マッピングファイルの生成およびDBとの同期は正常に完了しています。
resources配下にdemo.map.xmlが出力されていることも確認できます。

[INFO] Connecting to 'jdbc:postgresql://localhost:5432/demo_db' as 'postgres'
[INFO] +++ Connecting: SUCCESS.
[INFO] Detected and installed adapter: org.apache.cayenne.dba.postgres.PostgresAdapter
[INFO] Connecting to 'jdbc:postgresql://localhost:5432/demo_db' as 'postgres'
[INFO] +++ Connecting: SUCCESS.
[INFO] Detected and installed adapter: org.apache.cayenne.dba.postgres.PostgresAdapter
[WARNING] Missing dbimport config. Database is imported completely.
[INFO] Connecting to 'jdbc:postgresql://localhost:5432/demo_db' as 'postgres'
[INFO] +++ Connecting: SUCCESS.
[INFO]   Table: public.posts
[INFO]   Table: public.users
[INFO]     Db Relationship : toMany (users.id, posts.user_id)
[INFO]     Db Relationship : toOne  (posts.user_id, users.id)
[INFO]
[INFO] Map file does not exist. Loaded db model will be saved into 'C:\Users\Miyos\Desktop\demo\src\main\resources\demo.map.xml'
[INFO] 
[INFO] Detected changes:
[INFO]     Create Table         users
[INFO]     Create Table         posts
[INFO]
[WARNING] Can't find ObjEntity for posts
[WARNING] Db Relationship (Db Relationship : toMany (users.id, posts.user_id)) will have GUESSED Obj Relationship reflection.
[INFO] Migration Complete Successfully.
[INFO]
[INFO] All changes saved.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.790 s
[INFO] Finished at: 2026-02-01T18:27:43+09:00
[INFO] ------------------------------------------------------------------------

続いて、以下のコマンドで Javaクラスを生成してみます。

mvn cayenne:cgen

以下のログが出力され、Javaクラスが生成されました。

Using default cgen config.
[INFO] Generating superclass file: C:\Users\Miyos\Desktop\demo\src\main\java\com\example\demo\cayenne\auto\_Posts.java
[INFO] Generating class file: C:\Users\Miyos\Desktop\demo\src\main\java\com\example\demo\cayenne\Posts.java
[INFO] Generating superclass file: C:\Users\Miyos\Desktop\demo\src\main\java\com\example\demo\cayenne\auto\_Users.java
[INFO] Generating class file: C:\Users\Miyos\Desktop\demo\src\main\java\com\example\demo\cayenne\Users.java
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.592 s
[INFO] Finished at: 2026-02-01T18:37:49+09:00
[INFO] ------------------------------------------------------------------------

生成されたクラスは、以下の構成になっています。

src/main/java  
└─ com.example.demo.cayenne  
   ├─ auto  
   │  ├─ _Users.java  
   │  └─ _Posts.java  
   ├─ Users.java  
   └─ Posts.java

Cayenne における DataDomain / DataMap / DataNode について

Cayenne では、データベース接続やマッピング情報を
以下の3つの単位で管理します。

DataDomain
Cayenne 全体の設定をまとめる単位（最上位）
DataMap
テーブルと Java エンティティの対応関係（マッピング定義）
DataNode
実際のデータベース接続情報（JDBC URL やドライバなど）

今回の構成では、

demo.map.xml … DataMap
cayenne-demo.xml … DataDomain

という役割になります。

Cayenne Modeler を使って DataDomain（DB接続定義）を作成する

Cayenne Modeler を起動すると、
まず DataDomain（Cayenne 全体の設定）を作成する必要があります。

そのため、起動後は New Project を選択し、Data Domain Name を入力します。

次に、cdbimport で生成した
マッピングファイル（DataMap）を Modeler に読み込みます。

File → Import DataMap を選択し、
src/main/resources/demo.map.xml を指定します。

DataMap を実際のデータベースと紐付けるために、
DataNode（DB接続情報）を作成します。

ツリー上で右クリック → Create DataNode を選択し、
JDBC ドライバや DB URL を設定します。

続いて、DataMap に対して、先ほど作成した DataNode（データベース接続情報）を紐付けます。

ツリー上で DataMap を選択し、
右側の設定画面から DataNode に作成済みの DataNode を指定します。
これにより、
「このマッピング（DataMap）は、どのデータベースに接続するのか」
が明示的に定義されます。

設定が完了したら、
File → Save を選択し、プロジェクトの resources 配下にある demo.map.xml を保存します。

保存後、resources 配下に cayenne-demo.xml が作成されていることを確認します。

Spring Boot アプリ起動時には、このファイルが読み込まれます。

おわりに

以上で、

データベース構造の読み込み
マッピングファイルの作成
Java エンティティの生成
Cayenne が DB に接続できる状態

までが一通り整いました。

次回は、生成されたエンティティと Cayenne を使って
実際にデータを取得・登録する（CRUD）処理を実装していきます。