When dealing with a legacy database, especially a large legacy database, the task of creating Grails domain objects may be daunting. Developers experienced with Hibernate may have used Hibernate Tools to reverse-engineer a database and create Hibernate mappings automatically. Of course, tools such as this never work perfectly, requiring work on your part to adjust the automatically-created mappings.

In the Grails world, the reverse engineering plugin wraps the Hibernate tools to create Grails domain objects automatically from existing tables. Experienced developers may have forgotten about this plugin, though, since it was stuck at a pre-2.x Grails release for a long time.

Using the reverse-engineering plugin is remarkably easy.

First, create a project. I’d recommend creating a new throw-away project just for the purposes of generating domain classes. That way, you can pick and choose which classes to pull into your project.grails create-app dbrevThen, set up your database JDBC driver. You may need to copy a jar file into your lib directory, or set up a library dependency in BuildConfig.groovy.

Next, configure the connection in grails-app/conf/DataSource.groovy. I usually create a new Grails environment just for the purposes of reverse engineering, such as one named extract. In this environment, you do not want to blow away your database. So, be sure you do not have dbCreate set to ‘create-drop’. You’ll want something like the following:dbCreate = nullYou should also define the Hibernate dialect for your database.

After you set up the database connection, add the db-reverse-engineer plugin to your application in BuildConfig.grooy. Add the following line to the plugins section:runtime ':db-reverse-engineer:0.5'Before you get started, double-check the version number in case a new release is out. And make sure your project includes the mavenCentral() repository.

You probably want to configure the db-reverse-engineer plugin, even if you just want to define the Java package for your code. In Config.groovy, you can define lots of parameters as defined in the excellent db-reverse-engineer documentation at http://grails-plugins.github.com/grails-db-reverse-engineer/docs/manual/index.html.

For example:grails.plugin.reveng.packageName='com.objectpartners.dbrev'If you use something other than the default schema for the user account to the database, you’ll need to configure grails.plugin.reveng.defaultSchema or grails.plugin.reveng.defaultCatalog as needed. If you don’t set this correctly, the plugin nicely lists the available schemas and catalogs.

I’d suggest trying just one table to start out, to get familiar with how the reverse engineering works. To do so, define the includeTables configuration value to a list holding just the table name in which you are interested. For example:grails.plugin.reveng.includeTables=['employee']You can later add more table names to this list.

To make sure the plugin gets installed, run a command such as refresh-dependencies:grails refresh-dependenciesYou can verify the plugin is installed with the list-plugins command:grails list-pluginsYou are now ready to flame on. Run the following command in your project:grails -Dgrails.env=extract db-reverse-engineerIn this example, the extract environment is the special Grails environment mentioned above.

When dealing with some legacy tables, especially on SQL Server, you may have problems with tables that have no explicitly-defined primary key. In that case, the db-reverse-engineer script may throw an exception. The one-character fix listed with the following issue report (http://jira.grails.org/browse/GPREVERSEENGINEER-12)) takes care of the problem.

If you re-run the database reverse engineering after changing the configuration, you need to tell the plugin to overwrite existing files in your Config.groovy by setting the following value:grails.plugin.reveng.overwriteExisting=trueView the plugin information at http://www.grails.org/plugin/db-reverse-engineer.