Merge database migration plugin into gorm-hibernate5

.gitignore

@@ -21,3 +21,6 @@ gradle-app.setting
 # # Work around https://youtrack.jetbrains.com/issue/IDEA-116898
 # gradle/wrapper/gradle-wrapper.properties
 .DS_Store
+
+# Database Migration Test Database File
+*.db

docs/build.gradle

@@ -38,6 +38,8 @@ dependencies {
 }
 
 asciidoctor {
+    inputs.dir layout.projectDirectory.dir('src/docs/asciidoc')
+    outputs.dir layout.buildDirectory.dir('docs/manual')
     baseDirFollowsSourceDir()
     resources {
         from("${project.projectDir}/src/docs/asciidoc/images")
@@ -51,7 +53,13 @@ asciidoctor {
                 'reproducible'  : '',
                 'version'       : project.version,
                 'pluginVersion' : project.version,
-                'sourcedir'     : "${project.projectDir}/src/main/groovy"
+                'groupId'       : project.group,
+                'artifactId'    : project.name,
+                'sourcedir'     : "${project.projectDir}/src/main/groovy",
+                'migrationPluginExamplesDir' : rootProject.layout.projectDirectory.dir('grails-database-migration/src/integration-test/resources').asFile.absolutePath,
+                'migrationPluginGroupId' : rootProject.findProject(':database-migration').group,
+                'migrationPluginArtifactId' : rootProject.findProject(':database-migration').name,
+                'liquibaseHibernate5Version': liquibaseHibernate5Version
 }
 
 task fetchSource {

docs/src/docs/asciidoc/databaseMigration/configuration.adoc

@@ -0,0 +1,49 @@
+=== Configuration
+
+There are a few configuration options for the plugin. All configurations are prefixed with `grails.plugin.databasemigration`:
+
+[options="header"]
+|==================================
+|Property |Default |Meaning
+|changelogLocation |`grails-app/migrations` |the folder containing the main changelog file (which can include one or more other files)
+|changelogFileName |`changelog.groovy` |the name of the main changelog file
+|changelogProperties |none |a map of properties to use for property substitution in Groovy DSL changelogs
+|contexts |none |A comma-delimited list of http://www.liquibase.org/manual/contexts[context] names. If specified, only changesets tagged with one of the context names will be run
+|dbDocLocation |`target/dbdoc` |the directory where the output from the <<ref-documentation-scripts-dbm-db-doc,dbm-db-doc>> script is written
+|dbDocController.enabled |`true` in dev mode |whether the /dbdoc/ url is accessible at runtime
+|dropOnStart |`false` |if `true` then drops all tables before auto-running migrations (if updateOnStart is true)
+|updateOnStart |`false` |if `true` then changesets from the specified list of names will be run at startup
+|updateOnStartFileName |none |the file name (relative to `changelogLocation`) to run at startup if `updateOnStart` is `true`
+|updateOnStartDefaultSchema |none |the default schema to use when running auto-migrate on start
+|updateOnStartContexts |none |A comma-delimited list of http://www.liquibase.org/manual/contexts[context] names. If specified, only changesets tagged with one of the context names will be run
+|updateAllOnStart |false |if `true` then changesets from the specified list of names will be run at startup for all dataSources. Useful for Grails Multitenancy with Multiple Databases (same db schema)
+|autoMigrateScripts |['RunApp'] |the scripts when running auto-migrate. Useful to run auto-migrate during test phase with: ['RunApp', 'TestApp']
+|excludeObjects |none |A comma-delimited list of database object names to ignore while performing a dbm-gorm-diff or dbm-generate-gorm-changelog
+|includeObjects |none |A comma-delimited list of database object names to look for while performing a dbm-gorm-diff or dbm-generate-gorm-changelog
+|databaseChangeLogTableName |'databasechangelog' |the Liquibase changelog record table name
+|databaseChangeLogLockTableName |'databasechangeloglock' |the Liquibase lock table name
+|==================================
+
+NOTE: All the above configs can be used for multiple datasources
+
+
+*Multiple DataSource Example:*
+
+If secondary dataSource named "second" is configured in application.yml
+[source,yaml]
+----
+include::{migrationPluginExamplesDir}/application-multiple-datasource.yml[lines=11..29]
+----
+
+The configuration for this data source would be:
+[source,groovy]
+----
+grails.plugin.databasemigration.reports.updateOnStart = true
+grails.plugin.databasemigration.reports.changelogFileName = changelog-second.groovy
+----
+The configuration for all data sources with same db schema would be:
+[source,groovy]
+----
+grails.plugin.databasemigration.updateAllOnStart = true
+grails.plugin.databasemigration.changelogFileName = changelog.groovy
+----

docs/src/docs/asciidoc/databaseMigration/dbdoc.adoc

@@ -0,0 +1,23 @@
+=== DbDoc Controller
+
+You can use the <<ref-documentation-scripts-dbm-db-doc,dbm-db-doc>> script to generate static HTML files to view changelog information, but another option is to use the `DbDocController` at runtime. By default this controller is mapped to `/appname/dbdoc/` but this can be customized with `UrlMappings` like any controller.
+
+You probably don't want to expose this information to all of your application's users so by default the controller is only enabled in the development environment. But you can enable or disable it for any environment in `application.groovy` with the `dbDocController.enabled` config option. For example to enable for all environments (be sure to guard the URL with a security plugin in prod):
+
+[source,groovy]
+----
+grails.plugin.databasemigration.dbDocController.enabled = true
+----
+
+or to enable in the production environment:
+
+[source,groovy]
+----
+environments {
+   production {
+      grails.plugin.databasemigration.dbDocController.enabled = true
+   }
+   ...
+}
+----
+

docs/src/docs/asciidoc/databaseMigration/generalUsage.adoc

@@ -0,0 +1,95 @@
+=== General Usage
+
+After creating the initial changelog, the typical workflow will be along the lines of:
+
+* make domain class changes that affect the schema
+* add changes to the changelog for them
+* backup your database in case something goes wrong
+* run `grails dbm-update` to update your development environment (or wherever you're applying the changes)
+* check the updated domain class(es) and changelog(s) into source control
+
+[WARNING]
+=====
+1. When running migration scripts on non-development databases, it's important that you backup the database before running the migration in case anything goes wrong. You could also make a copy of the database and run the script against that, and if there's a problem the real database will be unaffected.
+2. Setting the dbCreate setting to "none" is recommended when executing the dbm migration commands. Otherwise you might run into troubles and the commands could not be executed.
+=====
+
+To create the changelog additions, you can either manually create the changes or with the <<ref-diff-scripts-dbm-gorm-diff,dbm-gorm-diff>> script (you can also use the <<ref-diff-scripts-dbm-diff,dbm-diff>> script but it's far less convenient and requires a 2nd temporary database).
+
+You have a few options with `dbm-gorm-diff`:
+
+* `dbm-gorm-diff` will dump to the console if no filename is specified, so you can copy/paste from there
+* if you include the `--add` parameter when running the script with a filename it will register an include for the filename in the main changelog for you
+
+Regardless of which approach you use, be sure to inspect generated changes and adjust as necessary.
+
+
+==== Autorun on start
+
+
+Since Liquibase maintains a record of changes that have been applied, you can avoid manually updating the database by taking advantage of the plugin's auto-run feature. By default this is disabled, but you can enable it by adding
+
+[source,groovy]
+----
+grails.plugin.databasemigration.updateOnStart = true
+----
+
+to application.groovy. In addition you must specify the file containing changes; specify the name using the `updateOnStartFileName` property, e.g.:
+
+[source,groovy]
+----
+grails.plugin.databasemigration.updateOnStartFileName = 'changelog.groovy'
+----
+
+Since changelogs can contain changelogs you'll most often just specify the root changelog, changelog.groovy by convention. Any changes that haven't been executed (in the specified file(s) or files included by them) will be run in the order specified.
+
+You may optionally limit the plugin's auto-run feature to run only specific contexts. If this configuration parameter is empty or omitted, all contexts will be run.
+
+[source,groovy]
+----
+grails.plugin.databasemigration.updateOnStartContexts = ['context1,context2']
+----
+
+You can be notified when migration are run (for example to do some work before and/or after the migrations execute) by registering a "callback" class as a Spring bean. The class can have any name and package and doesn't have to implement any interface since its methods will be called using Groovy duck-typing.
+
+The bean name is "migrationCallbacks" and there are currently three callback methods supported (all are optional):
+
+* `beforeStartMigration` will be called (if it exists) for each datasource before any migrations have run; the method will be passed a single argument, the Liquibase `Database` for that datasource
+* `onStartMigration` will be called (if it exists) for each migration script; the method will be passed three arguments, the Liquibase `Database`, the `Liquibase` instance, and the changelog file name
+* `afterMigrations` will be called (if it exists) for each datasource after all migrations have run; the method will be passed a single argument, the Liquibase `Database` for that datasource
+
+An example class will look like this:
+
+[source,groovy]
+----
+package com.mycompany.myapp
+
+import liquibase.Liquibase
+import liquibase.database.Database
+
+class MigrationCallbacks {
+
+   void beforeStartMigration(Database Database) {
+      ...
+   }
+
+   void onStartMigration(Database database, Liquibase liquibase, String changelogName) {
+      ...
+   }
+
+   void afterMigrations(Database Database) {
+      ...
+   }
+}
+----
+
+Register it in resources.groovy:
+
+[source,groovy]
+----
+import com.mycompany.myapp.MigrationCallbacks
+
+beans = {
+   migrationCallbacks(MigrationCallbacks)
+}
+----

docs/src/docs/asciidoc/databaseMigration/gettingStarted.adoc

@@ -0,0 +1,110 @@
+=== Getting Started
+
+*The first step is to add a dependency for the plugin in `build.gradle`:*
+
+[source,groovy,subs="attributes"]
+----
+buildscript {
+   dependencies {
+      ...
+      classpath '{migrationPluginGroupId}:{migrationPluginArtifactId}:{version}'
+   }
+}
+
+dependencies {
+   ...
+     implementation '{migrationPluginGroupId}:{migrationPluginArtifactId}:{version}'
+}
+----
+
+It is also recommended to add a direct dependency to liquibase because Spring Boot overrides the one provided by this plugin
+
+[source,groovy,subs="attributes"]
+----
+dependencies {
+   ...
+     implementation "org.liquibase:liquibase-core:{liquibaseHibernate5Version}"
+     implementation "org.liquibase.ext:liquibase-hibernate5:{liquibaseHibernate5Version}"
+}
+----
+
+You should also tell Gradle about the migrations folder. If using Grails 4 or above, make sure the configuration below is BEFORE the
+`dependencies` configuration, so that the `sourceSets` declaration takes effect.
+
+[source,groovy,subs="attributes"]
+----
+sourceSets {
+    main {
+        resources {
+            srcDir 'grails-app/migrations'
+        }
+    }
+}
+----
+
+*Typical initial workflow*
+
+Next you'll need to create an initial changelog. You can use Liquibase XML or the plugin's Groovy DSL for individual files. You can even mix and match; Groovy files can include other Groovy files and Liquibase XML files (but XML files can't include Groovy files).
+
+Depending on the state of your database and code, you have two options; either create a changelog from the database or create it from your domain classes. The decision tends to be based on whether you prefer to design the database and adjust the domain classes to work with it, or to design your domain classes and use Hibernate to create the corresponding database structure.
+
+To create a changelog from the database, use the <<ref-rollback-scripts-dbm-generate-changelog,dbm-generate-changelog>> script:
+[source,groovy]
+----
+grails dbm-generate-changelog changelog.groovy
+----
+
+or
+
+[source,groovy]
+----
+grails dbm-generate-changelog changelog.xml
+----
+
+depending on whether you prefer the Groovy DSL or XML. The filename is relative to the changelog base folder, which defaults to `grails-app/migrations`.
+
+NOTE: If you use the XML format (or use a non-default Groovy filename), be sure to change the name of the file in `application.groovy` so `dbm-update` and other scripts find the file:
+[source,groovy]
+----
+grails.plugin.databasemigration.changelogFileName = 'changelog.xml'
+----
+
+Since the database is already correct, run the <<ref-maintenance-scripts-dbm-changelog-sync,dbm-changelog-sync>> script to record that the changes have already been applied:
+[source,groovy]
+----
+grails dbm-changelog-sync
+----
+
+Running this script is primarily a no-op except that it records the execution(s) in the Liquibase DATABASECHANGELOG table.
+
+To create a changelog from your domain classes, use the <<ref-rollback-scripts-dbm-generate-gorm-changelog,dbm-generate-gorm-changelog>> script:
+
+[source,groovy]
+----
+grails dbm-generate-gorm-changelog changelog.groovy
+----
+
+or
+
+[source,groovy]
+----
+grails dbm-generate-gorm-changelog changelog.xml
+----
+
+If you haven't created the database yet, run the <<ref-update-scripts-dbm-update,dbm-update>> script to create the corresponding tables:
+
+[source,groovy]
+----
+grails dbm-update
+----
+
+or the <<ref-maintenance-scripts-dbm-changelog-sync,dbm-changelog-sync>> script if the database is already in sync with your code:
+
+[source,groovy]
+----
+grails dbm-changelog-sync
+----
+
+*Source control*
+
+Now you can commit the changelog and the corresponding application code to source control. Other developers can then update and synchronize their databases, and start doing migrations themselves.

docs/src/docs/asciidoc/databaseMigration/gorm.adoc

@@ -0,0 +1,25 @@
+=== GORM Support
+
+The plugin's support for GORM is one feature that differentiates it from using Liquibase directly. Typically, when using Liquibase you make changes to a database yourself, and then create changesets manually, or use a diff script to compare your updated database to one that hasn't been updated yet. This is a decent amount of work and is rather error-prone. It's easy to forget some changes that aren't required but help performance, for example creating an index on a foreign key when using MySQL.
+
+*create-drop, create, and update*
+
+On the other end of the spectrum, Hibernate's `create-drop` mode (or `create`) will create a database that matches your domain model, but it's destructive since all previous data is lost when it runs. This works well in the very early stages of development but gets frustrating quickly. Unfortunately Hibernate's `update` mode seems like a good compromise since it only makes changes to your existing schema, but it's very limited in what it will do. It's very pessimistic and won't make any changes that could lose data. So it will add new tables and columns, but won't drop anything. If you remove a not-null domain class property you'll find you can't insert anymore since the column is still there. And it will create not-null columns as nullable since otherwise existing data would be invalid. It won't even widen a column e.g. from `VARCHAR(100)` to `VARCHAR(200)`.
+
+*dbm-gorm-diff*
+
+The plugin provides a script that will compare your GORM current domain model with a database that you specify, and the result is a Liquibase changeset - `dbm-gorm-diff`. This is the same changeset you would get if you exported your domain model to a scratch database and diffed it with the other database, but it's more convenient.
+
+So a good workflow would be:
+
+* make whatever domain class changes you need (add new ones, delete unneeded ones, add/change/remove properties, etc.)
+* once your tests pass, and you're ready to commit your changes to source control, run the script to generate the changeset that will bring your database back in line with your code
+* add the changeset to an existing changelog file, or use the `include` tag to include the whole file
+* run the changeset on your functional test database
+* assuming your functional tests pass, check everything in as one commit
+* the other members of your team will get both the code and database changes when they next update, and will know to run the update script to sync their database with the latest code
+* once you're ready to deploy to QA for testing (or staging or production), you can run all the un-run changes since the last deployment
+
+*dbm-generate-gorm-changelog*
+
+The <<ref-rollback-scripts-dbm-generate-gorm-changelog,dbm-generate-gorm-changelog>> script is useful for when you want to switch from `create-drop` mode to doing proper migrations. It's not very useful if you already have a database that's in sync with your code, since you can just use the <<ref-rollback-scripts-dbm-generate-changelog,dbm-generate-changelog>> script that creates a changelog from your database.