4 General Usage

This plugin will save you a lot of time by using the JDBC metadata API to inspect your database schema and create domain classes for you, using some assumptions and augmented by configuration options that you set.

The core of the plugin is the db-reverse-engineer script. There are too many configuration options to support specifying them when running the script, so it takes no arguments and uses configuration options set in grails-app/conf/Config.groovy. These are described in the configuration.

Environments

You can choose which database to read from by specifying the environment when running the script (like any Grails script). For example to use the development environment settings, just run

grails db-reverse-engineer

To use the production environment settings, run

grails prod db-reverse-engineer

And if you want to use a custom 'staging' environment configured in DataSource.groovy, run

grails -Dgrails.env=staging db-reverse-engineer

Re-running the reverse engineering script

If you have new or changed tables you can re-run the db-reverse-engineer script to pick up changes and additions. This is not an incremental process though, so existing classes will be overwritten and you will lose any changes you made since the last run. But it's simple to define which tables to include or exclude.

As described in the configuration section, you can use a combination of the grails.plugin.reveng.includeTables, grails.plugin.reveng.includeTableRegexes, grails.plugin.reveng.includeTableAntPatterns, grails.plugin.reveng.excludeTables, grails.plugin.reveng.excludeTableRegexes, and grails.plugin.reveng.excludeTableAntPatterns properties to define which tables to include or exclude.

By default all tables are included, and the plugin assumes you're more likely to exclude than include. So you can specify one or more table names to explicitly exclude using grails.plugin.reveng.excludeTables, one or more regex patterns for exclusion using grails.plugin.reveng.excludeTableRegexes, and one or more Ant-style patterns for exclusion using grails.plugin.reveng.excludeTableAntPatterns.

For example, using this configuration

grails.plugin.reveng.excludeTables = ['clickstream', 'error_log']
grails.plugin.reveng.excludeTableRegexes = ['temp.+']
grails.plugin.reveng.excludeTableAntPatterns = ['audit_*']

you would process all tables except clickstream and error_log, and any tables that start with 'temp' (e.g. tempPerson, tempOrganization, etc.) and any tables that start with 'audit_' (e.g. 'audit_orders', 'audit_order_items', etc.)

If you only want to include one or a few tables, it's more convenient to specify inclusion rules rather than exclusion rules, so you use grails.plugin.reveng.includeTables, grails.plugin.reveng.includeTableRegexes, and grails.plugin.reveng.includeTableAntPatterns for that. If any of these properties are set, the table exclusion rules are ignored.

For example, using this configuration

grails.plugin.reveng.includeTables = ['person', 'organization']

you would process (or re-process) just the person and organization tables. You can also use The grails.plugin.reveng.includeTableRegexes and grails.plugin.reveng.includeTableAntPatterns properties to include tables based on patterns.

You can further customize the process by specifying which columns to exclude per-table. For example, this configuration

grails.plugin.reveng.excludeColumns = ['some_table': ['col1', 'col2'],
                                       'another_table': ['another_column']]

will exclude columns col1 and col2 from table some_table, and column another_column from table another_table.

You can also use the grails.plugin.reveng.excludeColumnRegexes and grails.plugin.reveng.excludeColumnAntPatterns properties to define patterns for columns to exclude.

Destination folder

By default the domain classes are generated under the grails-app/domain folder in the package specified. But you can override the destination, for example if you're re-running the process and want to compare the new classes with the previous ones.

By default the db-reverse-engineer script will overwrite existing classes. You can set the grails.plugin.reveng.overwriteExisting property to false to override this behavior and not overwrite existing files.

Many-to-many tables

Typically many-to-many relationships are implemented using a join table which contains just two columns which are foreign keys referring to the two related tables. It's possible for join tables to have extra columns though, and this will cause problems when trying to infer relationships. By default Hibernate will only consider tables that have two foreign key columns to be join tables. To get the script to correctly use join tables with extra columns, you can specify the table names with the grails.plugin.reveng.manyToManyTables property. This is demonstrated in the tutorial.

Another problem with many-to-many relationships is that one of the two GORM classes needs to be the 'owning' side and the other needs to be the 'owned' side, but this cannot be reliably inferred from the database. Both classes need a hasMany declaration, but the 'owned' domain class also needs a belongsTo declaration. So all of your many-to-many related tables need to have the tables that will create the belongsTo classes specified in the grails.plugin.reveng.manyToManyBelongsTos property. This is demonstrated in the tutorial.

Optimistic locking columns

Hibernate assumes that columns used for optimistic lock detection are called version. If you have customized one or more column names, you can direct the script about what the custom names are with the grails.plugin.reveng.versionColumns property. This is demonstrated in the tutorial.

Logging

All of the plugin classes are in the grails.plugin.reveng package, so you can configure that package for logging to see generated messages.