GradleでPostgreSQLとFlywayを連携する方法とバージョン管理の実践

GradleはJavaプロジェクトのビルド自動化ツールです。PostgreSQLやFlywayと組み合わせることで、DBマイグレーションを含む開発フロー全体を効率化できます。本記事では初心者向けに、各要素の基本から実践的なバージョン管理までを順に解説します。

Gradleとは何か：Javaプロジェクトにおける役割と基本概念

ビルド自動化ツールとしてのGradleの位置づけ

Gradleはソフトウェアのビルド処理を自動化するためのツールです。Java開発ではコンパイル、テスト実行、外部ライブラリの取得、依存関係の解決、JARなどのパッケージングをまとめて自動化できます。Gradle自体がJavaコンパイラではなく、これらの処理をタスクとして構成・実行する役割を担います。

Mavenも同様のビルドツールですが、GradleはGroovyまたはKotlinによるDSLで柔軟に設定を記述できる点が特徴です。MavenのXML形式（pom.xml）と比較して、条件分岐や独自タスクの定義がしやすいという利点があります。ただし「Gradleが必ずMavenより優れている」とは言い切れず、プロジェクトの要件や既存資産によって選択が変わります（出典：Gradle「Gradle Build Tool Features」）。

Project・Task・Dependencyの基本概念

Gradleの主要概念はProject、Task、Build Script、Dependency、Plugin、Repositoryです。Projectはビルド対象となる単位で、通常は1つのアプリケーションやライブラリに対応します。Taskはコンパイルやテストなど、Gradleが実行する個々の処理単位です。

DependencyはJavaアプリケーションが利用する外部ライブラリを指します。Gradleはビルドスクリプトに記述された依存関係を読み取り、Maven Centralなどのリポジトリから必要なライブラリを自動取得します。推移的依存関係も解決できるため、ライブラリAが依存するライブラリBも自動的に取得されます（出典：Gradle「Gradle Build Tool Features」）。

Gradle Wrapperの重要性と導入方法

Gradle Wrapperは、プロジェクトごとに使用するGradleバージョンを固定する仕組みです。代表的なファイルは「gradlew」（Linux/macOS用）、「gradlew.bat」（Windows用）、「gradle/wrapper/gradle-wrapper.properties」です。Wrapperが含まれるプロジェクトなら、システムにGradleを手動インストールしなくてもビルドを実行できます。

新規Javaプロジェクトでは基本的にWrapperの利用が公式推奨です。既存プロジェクトで「gradlew」の有無を確認し、あればWrapperを使ってビルドするのが基本です。これにより開発者全員が同じGradleバージョンを使用でき、CI環境での予期せぬバージョン差異による問題も防げます（出典：Gradle「Gradle Wrapper Basics」）。

要点：Gradleはビルド自動化ツールであり、Project・Task・Dependencyの概念を理解することが第一歩です。また、プロジェクトごとのバージョン固定にはWrapperの利用が推奨されます。

GradleとPostgreSQLの接続：JDBCドライバの依存関係設定

JDBCドライバとは何か

JDBC（Java Database Connectivity）ドライバは、Javaアプリケーションからデータベースへ接続するための橋渡し役です。PostgreSQL用のJDBCドライバを依存関係として追加することで、GradleプロジェクトからPostgreSQLへの接続が可能になります。

Gradle自体はデータベース製品ではなく、DB接続はJDBCドライバ等を依存関係として追加する形で実現します。専用のビルドスクリプトに依存関係を記述すれば、Gradleがリポジトリからドライバを自動取得します（出典：Gradle Plugin Portal・Spring Boot公式ドキュメント）。

build.gradleへの依存関係の追加手順

PostgreSQLのJDBCドライバを追加するには、ビルドスクリプトのdependenciesブロックに記述します。Groovy DSLの場合の基本的な記述例は以下の通りです。

dependencies {
    runtimeOnly 'org.postgresql:postgresql:42.7.3'
}

JDBCドライバは実行時にのみ必要となるため、「runtimeOnly」で指定するのが一般的です。「implementation」はコンパイル時と実行時の両方で必要となる依存関係を表しますが、JDBCドライバをコンパイル時に直接参照しない場合はruntimeOnlyで十分です。バージョン番号は記事執筆時点で確認可能な最新版を使用してください（出典：Spring Boot公式ドキュメント）。

接続設定で注意すべきポイント

Gradleのビルドスクリプトに依存関係を追加するだけでは、実際のDB接続は行われません。接続情報（URL、ユーザー名、パスワード）はアプリケーション側の設定ファイルやコードで指定する必要があります。ビルド時の依存関係解決と、実行時のDB接続は別のレイヤーであることを理解しておきましょう。

またGradle 9.x系を実行するにはJDK 17以上が必要です。2026年8月時点の互換性表ではJava 17〜26がGradleの実行環境としてサポートされています。古い記事にある「JDK 8があればGradleを実行できる」という説明は現行版には適用できないため注意が必要です（出典：Gradle「Installing Gradle」）。

FlywayによるDBマイグレーション：Gradleでの導入と実行手順

Flywayとは何か：DBスキーマ管理の役割

FlywayはDBスキーマのバージョン管理・マイグレーションを行うツールです。SQLスクリプトをバージョン順に適用し、データベースの構造変更を管理します。Gradleと連携させることで、ビルドプロセスにDBマイグレーションを組み込めます。

代表的なDBマイグレーションツールとしてFlywayとLiquibaseがあります。FlywayはSQL中心のシンプルなアプローチ、Liquibaseはロールバック対応が特徴です。Flywayのコミュニティ版はロールバック（undo）機能に対応していないため、必要な場合は手動のSQLスクリプトで対応する必要があります（出典：Spring Boot公式ドキュメント・Flyway公式ドキュメント）。

GradleでのFlyway導入と依存関係の設定

FlywayをGradleプロジェクトに導入するには、依存関係としてflyway-coreを追加します。Spring Bootプロジェクトでの基本的な記述例は以下の通りです。

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-jdbc'
    runtimeOnly 'org.flywaydb:flyway-core'
}

マイグレーションをGradle経由で実行する場合は、専用プラグイン（org.flywaydb.flyway）を使用します。Gradle Plugin Portalで複数のサードパーティ製DBプラグインが公開されていますが、公式プラグインを利用するのが安全です（出典：Spring Boot公式ドキュメント・Gradle Plugin Portal）。

マイグレーション実行時の注意点

Flywayの「clean」コマンドは開発環境専用です。本番DBでは絶対に実行しないでください。全オブジェクトを削除するため、取り返しのつかないデータ損失を引き起こします。

大量データのマイグレーション（例：数千万行のバックフィル）はトランザクションログが肥大化するため、バッチ処理（例：1000行ごとのコミット）が推奨されます。また、マイグレーション失敗時に「flyway:clean」を本番で実行しないことも重要です。Liquibaseと比較する場合、ロールバックの自動生成が必ずしも正しいとは限らない点にも注意が必要です（出典：Flyway/Liquibase公式ドキュメント）。

要点：FlywayはDBスキーマのバージョン管理ツールで、flyway-core依存で導入できます。cleanコマンドは開発環境専用であり、本番環境では絶対に使用しないでください。

Gradleのバージョン管理：Version CatalogとDependency Lockingの使い方

Version Catalogによる依存関係の一元管理

Version Catalogはプロジェクト全体の依存関係バージョンを一元管理するGradle公式機能です。設定ファイル「gradle/libs.versions.toml」にバージョンを集約し、依存関係の重複やドリフト（意図せぬバージョン差異）を防止します。

[versions]
jackson = "2.17.2"

[libraries]
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }

単一ファイルでバージョン管理が可能になるため、監査や更新作業が容易になります。複数モジュールで構成される大規模プロジェクトでは特に有効です（出典：Gradle公式ドキュメント）。

Dependency Lockingによる再現可能なビルド

Dependency Lockingは、推移的依存関係を含む全依存関係の解決結果をロックファイルに記録する機能です。Gradle 4.8以降で正式導入され、ロックファイル「gradle.lockfile」を生成します。

dependencyLocking {
    lockAllConfigurations()
}

ロックファイル生成は「./gradlew dependencies –write-locks」で実行します。生成したロックファイルをGit等にコミットすることで、誰がビルドしても同じ依存関係が解決される再現可能なビルドを実現できます。注意点として、動的バージョン（例：1.+、latest.release）を使うとロックと競合し、ビルドエラーになるため、依存関係のバージョンは固定することが必要です（出典：Gradle公式ドキュメント「Dependency Locking」）。

Gradle Wrapperによるバージョン固定とJDK互換性

Gradle WrapperはプロジェクトごとにGradle本体のバージョンを固定する仕組みです。「gradle/wrapper/gradle-wrapper.properties」に使用するバージョンを指定し、開発者全員とCI環境が同じGradleバージョンでビルドを実行できます。手動インストールは不要です。

2026年8月時点の最新安定版はGradle 9.6.1です。JavaバージョンとGradleバージョンの互換性も重要です。Java 26でGradleを実行するにはGradle 9.4.0以降が必要で、Java 21ならGradle 8.5以降が必要です。「最新のGradleを使うのが絶対」ではなく、プロジェクトのJDKバージョンとの互換性確認が先です（出典：Gradle「Gradle 9.6.1 Release Notes」・Gradle「Compatibility Matrix」）。

要点：Version Catalogでバージョンを一元管理し、Dependency Lockingで解決結果を固定し、Gradle Wrapperで本体バージョンを固定する、この3層の管理が実践的なアプローチです。

Gradle実行環境と互換性：JDKバージョンとGradleバージョンの関係

Gradle実行に必要なJDKバージョン

現行のGradleを実行するにはJDK 17以上が必要です。2026年8月時点の互換性表では、Java 17〜26がGradleの実行環境としてサポートされています。Java 17上でGradleを実行できるようになったのはGradle 7.3からですが、現在の新規プロジェクトでGradle 7.3を選ぶべきではありません。最新世代はGradle 9.x系です（出典：Gradle「Installing Gradle」・Gradle「Compatibility Matrix」）。

JDKバージョンとGradleバージョンの対応表

JavaのバージョンとGradleのバージョンは別物です。Gradleを実行するJavaのバージョンと、コンパイル対象となるJavaのバージョンを混同しないようにしましょう。主な対応関係は以下の通りです。

2026年8月時点の最新安定版はGradle 9.6.1です。ただし「Java 26を使うなら必ずGradle 9.6.1が必要」という意味ではなく、Gradle 9.4.0以降でJava 26上での実行が可能です（出典：Gradle「Compatibility Matrix」・Gradle「Gradle 9.4.0 Release Notes」）。

Java Toolchainsによる実行環境とビルド環境の分離

Java Toolchainsは、Gradleを実行するJDKと、プロジェクトのコンパイル・テストに使用するJDKを分離する機能です。Gradle 6.7以降で導入され、ビルドスクリプトの「java.toolchain」ブロックで使用するJavaバージョンを指定できます。

例えば、Gradle自体はJava 21で実行しつつ、プロジェクトのコンパイルはJava 17を対象にする、といった使い方が可能です。自動ダウンロード機能により、必要なJDKがなければ自動取得・管理できます。ツールチェーンの確認は「gradle -q javaToolchains」コマンドで実行できます（出典：Gradle User Manual「Toolchains for JVM projects」）。

要点：Gradle実行環境にはJDK 17以上が必要です。JavaのバージョンとGradleのバージョンは別物であり、互換性表の確認とJava Toolchainsによる環境分離が重要です。