Migrations generated from your Hibernate entities.

Five ideas to know

Everything WaveBase does is built on these. The full glossary ships with the source code.

1. Clone WaveBase next to your project

   git clone https://github.com/WaveBase-Project/WaveBase.git ../WaveBase

2. Include the build and apply the plugin

   settings.gradle.kts

   pluginManagement {
       includeBuild("../WaveBase")
   }

   build.gradle.kts

   import io.github.agallina.wavebase.core.dialect.Dialect
   
   plugins {
       java
       id("io.github.agallina.wavebase")
   }
   
   dependencies {
       runtimeOnly("org.postgresql:postgresql:42.7.3")  // your JDBC driver
   }
   
   wavebase {
       jdbcUrl.set(providers.environmentVariable("WAVEBASE_JDBC_URL"))
       jdbcUsername.set(providers.environmentVariable("WAVEBASE_JDBC_USER"))
       jdbcPassword.set(providers.environmentVariable("WAVEBASE_JDBC_PASSWORD"))
       dialect.set(Dialect.POSTGRESQL)  // or MYSQL, H2
   }

3. Generate your first Migration

   With no snapshot yet, the first Migration creates every table, ordered so foreign keys come after the tables they reference.

   ./gradlew wavebaseGenerateMigration
   # WaveBase: generated Migration 20261010143005123001 in src/main/resources/db/migration/...

4. Review, commit, apply

   git add src/main/resources/db
   git commit -m "Initial schema"
   ./gradlew wavebaseApply

1. Install WaveBase on your machine (once)

   One command builds WaveBase and puts it in your local Maven repository (~/.m2). You only need Java 17: the ./gradlew script downloads everything else by itself. This step goes away once WaveBase is on Maven Central.

   git clone https://github.com/WaveBase-Project/WaveBase.git
   cd WaveBase
   ./gradlew publishToMavenLocal

2. Add WaveBase to your pom.xml

   Two blocks. First, the settings, in <properties>. Change the dialect to match your database; leave the rest as is.

   pom.xml · inside <project>

   <properties>
     <!-- ...your existing properties... -->
   
     <wavebase.version>0.1.0-SNAPSHOT</wavebase.version>
     <wavebase.dialect>POSTGRESQL</wavebase.dialect>   <!-- POSTGRESQL, MYSQL or H2 -->
     <wavebase.jdbcUrl>${env.WAVEBASE_JDBC_URL}</wavebase.jdbcUrl>
     <wavebase.jdbcUsername>${env.WAVEBASE_JDBC_USER}</wavebase.jdbcUsername>
     <wavebase.jdbcPassword>${env.WAVEBASE_JDBC_PASSWORD}</wavebase.jdbcPassword>
   </properties>

   Then the plugin, in <build><plugins>. If your pom has no <build> section yet, paste the whole block.

   pom.xml · inside <project>

   <build>
     <plugins>
       <plugin>
         <groupId>io.github.agallina</groupId>
         <artifactId>wavebase-maven-plugin</artifactId>
         <version>${wavebase.version}</version>
         <executions>
           <execution>
             <goals>
               <goal>verify-migrations</goal>   <!-- checks every mvn verify / mvn install -->
             </goals>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>

3. Make sure the JDBC driver is a dependency

   Most projects already have it. If not, add the one for your database:

   Database	wavebase.dialect	Driver dependency
   PostgreSQL	POSTGRESQL	org.postgresql:postgresql:42.7.3
   MySQL	MYSQL	com.mysql:mysql-connector-j:8.4.0
   H2	H2	com.h2database:h2:2.2.224

   Show a complete pom.xml to start from

   pom.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example</groupId>
     <artifactId>my-app</artifactId>
     <version>1.0.0-SNAPSHOT</version>
   
     <properties>
       <maven.compiler.release>17</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   
       <!-- WaveBase -->
       <wavebase.version>0.1.0-SNAPSHOT</wavebase.version>
       <wavebase.dialect>POSTGRESQL</wavebase.dialect>
       <wavebase.jdbcUrl>${env.WAVEBASE_JDBC_URL}</wavebase.jdbcUrl>
       <wavebase.jdbcUsername>${env.WAVEBASE_JDBC_USER}</wavebase.jdbcUsername>
       <wavebase.jdbcPassword>${env.WAVEBASE_JDBC_PASSWORD}</wavebase.jdbcPassword>
     </properties>
   
     <dependencies>
       <!-- Your entities: Hibernate 6 / Jakarta Persistence -->
       <dependency>
         <groupId>org.hibernate.orm</groupId>
         <artifactId>hibernate-core</artifactId>
         <version>6.5.2.Final</version>
       </dependency>
   
       <!-- JDBC driver for your database -->
       <dependency>
         <groupId>org.postgresql</groupId>
         <artifactId>postgresql</artifactId>
         <version>42.7.3</version>
         <scope>runtime</scope>
       </dependency>
     </dependencies>
   
     <build>
       <plugins>
         <plugin>
           <groupId>io.github.agallina</groupId>
           <artifactId>wavebase-maven-plugin</artifactId>
           <version>${wavebase.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>verify-migrations</goal>
               </goals>
             </execution>
           </executions>
         </plugin>
       </plugins>
     </build>
   </project>

4. Tell WaveBase where your database is

   The pom reads the connection from environment variables, so no password ends up in git. Generating Migrations does not need them; applying them does.

   export WAVEBASE_JDBC_URL=jdbc:postgresql://localhost:5432/mydb
   export WAVEBASE_JDBC_USER=myuser
   export WAVEBASE_JDBC_PASSWORD=secret

5. Generate your first Migration

   Run compile in the same command: WaveBase reads your compiled entity classes. With no snapshot yet, the first Migration creates every table.

   mvn compile wavebase:generate-migration
   # [INFO] WaveBase: generated Migration 20261010143005123001 in src/main/resources/db/migration/...

6. Review, commit, apply

   git add src/main/resources/db
   git commit -m "Initial schema"
   mvn wavebase:apply

   From now on, mvn verify and mvn install fail if an entity changes without a Migration, so nobody forgets one.

The everyday loop

// 1. change an entity
@Entity @Table(name = "posts")
public class Post {
    @Id private Long id;
    @Column(nullable = false) private String title;
    @Column private String summary;            // new
    @ManyToOne(optional = false) @JoinColumn(name = "author_id")
    private User author;
}

# 2. generate: writes db/migration/<version>/ and updates model-snapshot.json
./gradlew wavebaseGenerateMigration

# 3. commit the entity, the Migration and the snapshot together
git add -A && git commit -m "Add Post.summary"

# 4. CI: `check` fails if someone forgets step 2
./gradlew check

# 2. generate: writes db/migration/<version>/ and updates model-snapshot.json
mvn compile wavebase:generate-migration

# 3. commit the entity, the Migration and the snapshot together
git add -A && git commit -m "Add Post.summary"

# 4. CI: `mvn verify` fails if someone forgets step 2
mvn verify

./gradlew wavebaseApply
./gradlew wavebaseRevert            # last one
./gradlew wavebaseRevert --to <v>   # everything after <v>

mvn wavebase:apply
mvn wavebase:revert                     # last one
mvn wavebase:revert -Dwavebase.to=<v>  # everything after <v>

# DBA runs <v>/postgresql.up.sql
./gradlew wavebaseMarkApplied --version <v>
./gradlew wavebaseVerifySchema

# DBA runs <v>/postgresql.up.sql
mvn wavebase:mark-applied -Dwavebase.version=<v>
mvn wavebase:verify-schema

Onboard an existing database

Reverse Scaffold writes one entity class per table. It runs once: after that, your entities are the source of truth.

./gradlew wavebaseReverseScaffold --package com.acme.entity
# review and commit the generated classes, then create the baseline:
./gradlew wavebaseGenerateMigration
./gradlew wavebaseMarkApplied --version <v>   # tables already exist

mvn wavebase:reverse-scaffold -Dwavebase.package=com.acme.entity
# review and commit the generated classes, then create the baseline:
mvn compile wavebase:generate-migration
mvn wavebase:mark-applied -Dwavebase.version=<v>   # tables already exist

Command reference

The Gradle tasks (group wavebase) and the Maven goals behave identically. The short wavebase: prefix works when the plugin is declared in your pom.xml; otherwise use the full form io.github.agallina:wavebase-maven-plugin:0.1.0-SNAPSHOT:<goal>.

Configuration

In Maven, put these properties in your pom's <properties> block (as in the Quickstart) and override any of them with -D on the command line.

What a Migration looks like on disk

src/main/resources/db/
├── model-snapshot.json
└── migration/
    └── 20261010143005123001/
        ├── postgresql.up.sql   postgresql.down.sql
        ├── mysql.up.sql        mysql.down.sql
        └── h2.up.sql           h2.down.sql

Scope and status

Community

WaveBase is open source and shaped in the open. Design decisions are tracked as GitHub issues, so every behaviour on this page has a discussion behind it.