--- /dev/null
+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-SNAPSHOT</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-SNAPSHOT</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 {{{./export-mojo.html} Documentation of the export-Mojo}}).
+ These are named after the
+ {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} 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-SNAPSHOT</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-SNAPSHOT</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
+ {{{./export-mojo.html} 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-SNAPSHOT</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-SNAPSHOT</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.
-A simple plugin for generating a database-schema from Hibernate 4 mapping-annotations.
+A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations.
- Hibernate comes with the buildin functionality, to automatically create or
- update the database schema.
- This functionality is configured in the session-configuraton via the
- parameter <hbm2ddl.auto>
- (see {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-optional} Hibernate Reference Documentation - Chapter 3.4. Optional configuration properties}}).
- But doing so
- {{{http://stackoverflow.com/questions/221379/hibernate-hbm2ddl-auto-update-in-production} is not very wise}}, because you can easily corrupt or erase your
- production database, if this configuration parameter slips through to your
- production environment.
- Alternatively, you can
- {{{http://stackoverflow.com/questions/835961/how-to-creata-database-schema-using-hibernate} run the tools SchemaExport or SchemaUpdate by hand}}.
- But that is not very comfortable and being used to maven you will quickly
- long for a plugin, that does that job automatically for you, when you fire
- up your test cases.
+ <<hibernate4-maven-plugin>> is a plugin for generating a database-schema
+ from your Hibernate-4-Mappings and create or update your database
+ accordingly.
- In the good old times, there was the
- {{{http://mojo.codehaus.org/maven-hibernate3/hibernate3-maven-plugin/} Maven Hibernate3 Plugin}}, that does this for you.
- But unfortunatly, this plugin is not compatible with Hibernate 4.x.
+ The plugin was designed to be easy and safe to use, because it must not
+ never, never happen, that you blow away your production database when
+ firering a maven-build of your webapp on your production-machine!
+ For more information about the insiration to write this tiny plugin,
+ {{{/hibernate4-maven-plugin-a-simple-plugin-for-generating-a-database-schema-from-hibernate-4-mapping-annotations/} read our blog-article about the hibernate4-maven-plugin}}.
- Since there does not seem to be any successor for the Maven Hibernate3 Plugin
- and {{{http://www.google.de/search?q=hibernate4+maven+plugin} googeling}}
- does not help, I decided to write up this simple plugin (inspired by these
- two articles I found: {{{http://www.tikalk.com/alm/blog/schema-export-hibernate-4-and-maven} Schema Export with Hibernate 4 and Maven}} and
- {{{http://doingenterprise.blogspot.de/2012/05/schema-generation-with-hibernate-4-jpa.html} Schema generation with Hibernate 4, JPA and Maven}}).
+Documentation and Examples
+
+ * See {{{./examples.html} Examples}} for Usage-Eplanations and simple
+ examples of how to use this plugin.
+
+ * See {{{./plugin-info.html} Plugin Documentation}} for the full
+ autogenerated documentation. These are mostly configuration-options
+ of the Hibernate-Tools <<<SchemaExport>>> and <<<SchemaUpdate>>>, that do
+ the work in the background.
projects / hibernate4-maven-plugin / commitdiff