Configuration Examples

The plugin was designed with two main goals in mind:

  • It should be easy to use.
  • It should be maximal unlikely, to erase a producation-database by accident.

To achieve the first goal, the convention-over-configuration paradigma was applied and the plugin was stuffed with usefull logging-messages. So, if in doubt, just turn on the Debug-Output with the mvn -X ....

To achieve the second goal, the precedence in which the configuration locations are consulted was layouted in a way that makes it possible, to prevent overwrites of the wrong database by accident.

Configuration through a hibernate.properties-File

The most simple way to configure the plugin is, to put all the hibernate-configuration in a hibernate.properties-file on your classpath. Put the file in the resources-folder. Maven will put it in the class-folder of your webapp, where it will be picked up by this plugin as well as by Hibernate 4.

Doing so, the only additionally configuration needed, to activat the plugin is the following entry in the plugins-section of your pom.xml:

<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
</plugin>

But be aware, that in this case the database-url, that is build in the application is the same that is used while testing, where the database is droped and recreated by the plugin. So, you should never fire up this configuration on your production system, or your database might be erased!

Hence, you should specify a different url for testing like in the following snippet:

<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
  </configuration>
</plugin>

Configuration properties, that are set in the configuration-section of the plugin-configuration cannnot be overwritten elsewere (for details see Configuration-Method-Precedence). You never can overwrite them by accident when specifying a property on the commandline or in your settings.xml.

Configuration through maven-properties

Alternatively, it is possible, to configure the plugin via maven-properties. Each relevant configuration-option has a corresponding maven-property (for a full list see the Documentation of the export-Mojo). These are named after the Hibernate JDBC Properties:

  • hibernate.connection.driver_class
  • hibernate.dialect
  • hibernate.connection.url
  • hibernate.connection.username
  • hibernate.connection.password

So, instead of writing the hibernate-configuration in the properties-file, like above, you could put it in the properties-section of your pom.xml.

Thogether with the plugin-definition from above, the following would be a complete configuration (again, the database-url was overwritten in the plugin-configuration, to be sure to have a separate database for testing):

<properties>
  <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
  <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
  <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
  <hibernate.connection.username>sa</hibernate.connection.username>
  <hibernate.connection.password></hibernate.connection.password>
</properties>

...

<plugins>

  ...

  <plugin>
    <groupId>de.juplo</groupId>
    <artifactId>hibernate4-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
      <execution>
        <goals>
          <goal>export</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
    </configuration>
  </plugin>

<plugins>

Configuration through the plugin-configuration

A third way for configuring the plugin is the plugin-configuration. The relevant configuration-parameters are:

  • driverClassName
  • hibernateDialect
  • url
  • username
  • password

The equivalent of the configuration from the last section would look like this:

<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
    <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
    <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
    <username>sa</username>
    <password></password>
  </configuration>
</plugin>

There are some seldom used parameters, that can only be configured throug this method:

  • delimiter the delimiter used in the generated sql-script
  • format wether the generated sql-script is formatted, or not
  • hibernateProperties name of the hibernate-properties-file
  • outputFile name of the generated sql-script
  • target create database or generate sql-script or both
  • type create or drop the database or do both or nothing (just validate the annotation-configuration)

For explanations, see the Documentation of the export-Mojo.

Configuration-Method-Precedence

The configuration is gathered in a fix order:

  1. hibernate.properties
  2. maven-properties
  3. plugin-configuration

If you are in doubt about where a configuration-value comes from, run maven with the Debug-Output enabled: mvn -X hibernate4:export and be aware, that maven-properties can be overwitten on the command-line, in your ~/.m2/settings.xml and in a profile.

The plugin-configuration comes last and overwrites everything else. That way, you can be sure, that a configuration-value, that is specified in the plugin-configuration will never be overwritten by any other configuration-method.

If you realy need to overwrite plugin-configuration-values with maven-properties, you can use maven-properties in the plugin-configuration:

<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <password>${my-password-property}</password>
  </configuration>
</plugin>

Enabling Debug-Output

If you are new to hibernate4-maven-plugin, in many cases, the Configuration-Method-Precedence may be the source of configuration errors. To solve this problem, you should run maven with the debugging output enabled. For example, by executing:

mvn -X compile hibernate4:export 

(The compile might be necessary, because hibernate4-maven-plugin has to scan the compiled classes for annotations!)

Unlike the majority of the maven-plugins, hibernate4-maven-plugin was designed to give a good many hints, when debugging is enabled. Because, if you do not know, what went wrong, you can't fix it!

But be warned: hibernate4-maven-plugin tends to be very chatty ;)

Known Pitfalls

One regular problem is the scope of the jdbc-driver-dependency. It is very unlikely, that this dependency is needed at compile-time. So a tidy maven-developer would usually scope it for runtime.

But this will break the execution of the hibernate4-maven-plugin. Since it will not be able to see the needed dependency, it will fail with an error-message like:

[INFO] Gathered hibernate-configuration (turn on debugging for details):
[INFO]   hibernate.connection.username = sa
[INFO]   hibernate.connection.password = 
[INFO]   hibernate.dialect = org.hibernate.dialect.HSQLDialect
[INFO]   hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
[INFO]   hibernate.connection.driver_class = org.hsqldb.jdbcDriver
[ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] org.hsqldb.jdbcDriver
[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
[INFO] Final Memory: 32M/342M
[INFO] ------------------------------------------------------------------------

A quick workaround for this error would be, to delete the runtime-constraint for the jdbc-driver-dependency.

A much cleaner way is, to (additionally) ad the dependency, to the plugin-definition:

<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <dependencies>
  <dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>2.2.8</version>
  </dependency>
  </dependencies>
</plugin>

This is also the best way, if you use a different jdbc-driver for testing, than in production. Because otherwise, this dependency will unnecessarily bloat the runtime-dependencies of your project.