This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+
+
+
+
+
Overview
+
The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
+
+
+
Package
+
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
+
+
Interfaces (italic)
+
Classes
+
Enums
+
Exceptions
+
Errors
+
Annotation Types
+
+
+
+
Class/Interface
+
Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
+
Class inheritance diagram
+
Direct Subclasses
+
All Known Subinterfaces
+
All Known Implementing Classes
+
Class/interface declaration
+
Class/interface description
+
+
+
Nested Class Summary
+
Field Summary
+
Constructor Summary
+
Method Summary
+
+
+
Field Detail
+
Constructor Detail
+
Method Detail
+
+
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+
Annotation Type
+
Each annotation type has its own separate page with the following sections:
+
+
Annotation Type declaration
+
Annotation Type description
+
Required Element Summary
+
Optional Element Summary
+
Element Detail
+
+
+
+
Enum
+
Each enum has its own separate page with the following sections:
+
+
Enum declaration
+
Enum description
+
Enum Constant Summary
+
Enum Constant Detail
+
+
+
+
+
Deprecated API
+
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+
+
Index
+
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+
+
Frames/No Frames
+
These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+
All Classes
+
The All Classes link shows all classes and interfaces except non-static nested types.
+
+
+
Serialized Form
+
Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
The transactionManager bean for the current dataSource
+
+
+
+
+
void
+
withNewTransaction(groovy.lang.Closure callable) Executes the closure within the context of a new transaction
+
+
+
+
+
void
+
withNewTransaction(java.util.Map transactionProperties, groovy.lang.Closure callable) Executes the closure within the context of a new transaction which is
+ configured with the properties contained in transactionProperties.
+
+
+
+
+
+
void
+
withTransaction(groovy.lang.Closure callable) Executes the closure within the context of a transaction, creating one if none is present or joining
+ an existing transaction if one is already present.
withTransaction(TransactionDefinition definition, groovy.lang.Closure callable) Executes the closure within the context of a transaction for the given TransactionDefinition
Executes the closure within the context of a new transaction which is
+ configured with the properties contained in transactionProperties.
+ transactionProperties may contain any properties supported by
+ DefaultTransactionDefinition. Note that if transactionProperties
+ includes entries for propagationBehavior or propagationName, those values
+ will be ignored. This method always sets the propagation level to
+ TransactionDefinition.REQUIRES_NEW.
+
+
Executes the closure within the context of a transaction, creating one if none is present or joining
+ an existing transaction if one is already present.
@groovy.transform.CompileStatic
+@liquibase.change.DatabaseChange(name: grailsChange, description: Adds creates a primary key out of an existing column or set of columns., priority: ChangeMetaData.PRIORITY_DEFAULT)
+class GroovyChange
+extends AbstractChange
There are a few configuration options for the plugin. All configurations are prefixed with grails.plugin.databasemigration:
+
+
+
+
+
+
+
+
+
+
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 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 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 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
+
+
+
+
+
+
+
+
+
+
+All the above configs can be used for multiple datasources
+
+
+
+
+
+
Multiple DataSource Example:
+
+
+
If secondary dataSource named "second" is configured in application.yml
You can use the 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):
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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
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 dbm-gorm-diff script (you can also use the 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
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.
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
You should also tell Gradle about the migrations folder. If using Grails 4, make sure the configuration below is BEFORE the
+dependencies configuration, so that the sourceSets declaration takes effect.
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.
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.
+
+
+
+
+
+
+
+
+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:
+
If you haven’t created the database yet, run the dbm-update script to create the corresponding tables:
+
+
+
+
grails dbm-update
+
+
+
+
or the dbm-changelog-sync script if the database is already in sync with your code:
+
+
+
+
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.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/gorm.html b/5.0.0/gorm.html
new file mode 100644
index 00000000..63886c08
--- /dev/null
+++ b/5.0.0/gorm.html
@@ -0,0 +1,512 @@
+
+
+
+
+
+
+
+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 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 dbm-generate-changelog script that creates a changelog from your database.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/groovyChanges.html b/5.0.0/groovyChanges.html
new file mode 100644
index 00000000..73954491
--- /dev/null
+++ b/5.0.0/groovyChanges.html
@@ -0,0 +1,599 @@
+
+
+
+
+
+
+
+Groovy Changes
+
+
+
+
+
+
In addition to the built-in Liquibase changes (see the documentation for what’s available) you can also make database changes using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsChange tag name and are contained in a changeSet tag like standard built-in tags.
+
+
+
There are four supported inner tags and two callable methods (to override the default confirmation message and checksum value).
+
+
+
General format
+
+
This is the general format of a Groovy-based change; all inner tags and methods are optional:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ grailsChange {
+ init {
+ // arbitrary initialization code; note that no
+ // database or connection is available
+ }
+
+ validate {
+ // can call warn(String message) to log a warning
+ // or error(String message) to stop processing
+ }
+
+ change {
+ // arbitrary code; make changes directly and/or return a
+ // SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'change confirmation message'
+ }
+
+ rollback {
+ // arbitrary code; make rollback changes directly and/or
+ // return a SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'rollback confirmation message'
+ }
+
+ confirm 'confirmation message'
+
+ checkSum 'override value for checksum'
+ }
+
+ }
+}
+
+
+
+
+
Available variables
+
+
These variables are available throughout the change closure:
+
+
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
+
+
The change and rollback closures also have the following available:
+
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
+
+
init
+
+
+
This is where any optional initialization should happen. You can’t access the database from this closure.
+
+
+
validate
+
+
+
If there are any necessary validation checks before executing changes or rollbacks they should be done here. You can log warnings by calling warn(String message) and stop processing by calling error(String message). It may make more sense to use one or more preConditions instead of directly validating here.
+
+
+
change
+
+
+
All migration changes are done in the change closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
rollback
+
+
+
All rollback changes are done in the rollback closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
confirm
+
+
+
The confirm(String message) method is used to specify the confirmation message to be shown. The default is "Executed GrailsChange" and it can be overridden in the change or rollback closures to allow phase-specific messages or outside of both closures to use the same message for the update and rollback phase.
+
+
+
checkSum
+
+
+
The checksum for the change will be generated automatically, but if you want to override the value that gets hashed you can specify it with the checkSum(String value) method.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/groovyPreconditions.html b/5.0.0/groovyPreconditions.html
new file mode 100644
index 00000000..40b97e82
--- /dev/null
+++ b/5.0.0/groovyPreconditions.html
@@ -0,0 +1,580 @@
+
+
+
+
+
+
+
+Groovy Preconditions
+
+
+
+
+
+
In addition to the built-in Liquibase preconditions (see the documentation for what’s available) you can also specify preconditions using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsPrecondition tag name and are contained in the databaseChangeLog tag or in a changeSet tag like standard built-in tags.
+
+
+
General format
+
+
This is the general format of a Groovy-based precondition:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ preConditions {
+
+ grailsPrecondition {
+
+ check {
+
+ // use an assertion
+ assert x == x
+
+ // use an assertion with an error message
+ assert y == y : 'value cannot be 237'
+
+ // call the fail method
+ if (x != x) {
+ fail 'x != x'
+ }
+
+ // throw an exception (the fail method is preferred)
+ if (y != y) {
+ throw new RuntimeException('y != y')
+ }
+ }
+
+ }
+
+ }
+ }
+}
+
+
+
+
As you can see there are a few ways to indicate that a precondition wasn’t met:
+
+
+
+
+
use a simple assertion
+
+
+
use an assertion with a message
+
+
+
call the fail(String message) method (throws a PreconditionFailedException)
+
+
+
throw an exception (shouldn’t be necessary - use assert or fail() instead)
+
+
+
+
+
+
Available variables
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
changeLog - the current Liquibase DatabaseChangeLog instance
+
+
+
+
+
+
Utility methods
+
+
+
+
createDatabaseSnapshotGenerator() - retrieves the DatabaseSnapshotGenerator for the current Database
+
+
+
createDatabaseSnapshot(String schemaName = null) - creates a DatabaseSnapshot for the current Database (and schema if specified)
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/index.html b/5.0.0/index.html
new file mode 100644
index 00000000..83fce431
--- /dev/null
+++ b/5.0.0/index.html
@@ -0,0 +1,3884 @@
+
+
+
+
+
+
+
+Grails Database Migration Plugin
+
+
+
+
+
+
+
The Database Migration plugin helps you manage database changes while developing Grails applications. The plugin uses the Liquibase library.
+
+
+
Using this plugin (and Liquibase in general) adds some structure and process to managing database changes. It will help avoid inconsistencies, communication issues, and other problems with ad-hoc approaches.
+
+
+
Database migrations are represented in text form, either using a Groovy DSL or native Liquibase XML, in one or more changelog files. This approach makes it natural to maintain the changelog files in source control and also works well with branches. Changelog files can include other changelog files, so often developers create hierarchical files organized with various schemes. One popular approach is to have a root changelog named changlog.groovy (or changelog.xml) and to include a changelog per feature/branch that includes multiple smaller changelogs. Once the feature is finished and merged into the main development tree/trunk the changelog files can either stay as they are or be merged into one large file. Use whatever approach makes sense for your applications, but keep in mind that there are many options available for changelog management.
+
+
+
Individual changes have an ID that should be globally unique, although they also include the username of the user making the change, making the combination of ID and username unique (although technically the ID, username, and changelog location are the "unique key").
+
+
+
As you make changes in your code (typically domain classes) that require changes in the database, you add a new change set to the changelog. Commit the code changes along with the changelog additions, and the other developers on your team will get both when they update from source control. Once they apply the new changes their code and development database will be in sync with your changes. Likewise when you deploy to a QA, a staging server, or production, you’ll run the un-run changes that correspond to the code updates to being that environment’s database in sync. Liquibase keeps track of previously executed changes so there’s no need to think about what has and hasn’t been run yet.
+
+
+
Scripts
+
+
+
Your primary interaction with the plugin will be using the provided scripts. For the most part these correspond to the many Liquibase commands that are typically executed directly from the commandline or with its Ant targets, but there are also a few Grails-specific scripts that take advantage of the information available from the GORM mappings.
+
+
+
All the scripts start with dbm- to ensure that they’re unique and don’t clash with scripts from Grails or other plugins.
+
+
+
+
+
2. Getting Started
+
+
+
The first step is to add a dependency for the plugin in build.gradle:
You should also tell Gradle about the migrations folder. If using Grails 4, make sure the configuration below is BEFORE the
+dependencies configuration, so that the sourceSets declaration takes effect.
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.
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.
+
+
+
+
+
+
+
+
+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:
+
If you haven’t created the database yet, run the dbm-update script to create the corresponding tables:
+
+
+
+
grails dbm-update
+
+
+
+
or the dbm-changelog-sync script if the database is already in sync with your code:
+
+
+
+
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.
+
+
+
+
+
3. Configuration
+
+
+
There are a few configuration options for the plugin. All configurations are prefixed with grails.plugin.databasemigration:
+
+
+
+
+
+
+
+
+
+
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 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 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 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
+
+
+
+
+
+
+
+
+
+
+All the above configs can be used for multiple datasources
+
+
+
+
+
+
Multiple DataSource Example:
+
+
+
If secondary dataSource named "second" is configured in application.yml
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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
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 dbm-gorm-diff script (you can also use the 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.
+
+
+
4.1. 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
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.
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
In addition to the built-in Liquibase changes (see the documentation for what’s available) you can also make database changes using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsChange tag name and are contained in a changeSet tag like standard built-in tags.
+
+
+
There are four supported inner tags and two callable methods (to override the default confirmation message and checksum value).
+
+
+
5.1. General format
+
+
This is the general format of a Groovy-based change; all inner tags and methods are optional:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ grailsChange {
+ init {
+ // arbitrary initialization code; note that no
+ // database or connection is available
+ }
+
+ validate {
+ // can call warn(String message) to log a warning
+ // or error(String message) to stop processing
+ }
+
+ change {
+ // arbitrary code; make changes directly and/or return a
+ // SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'change confirmation message'
+ }
+
+ rollback {
+ // arbitrary code; make rollback changes directly and/or
+ // return a SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'rollback confirmation message'
+ }
+
+ confirm 'confirmation message'
+
+ checkSum 'override value for checksum'
+ }
+
+ }
+}
+
+
+
+
+
5.2. Available variables
+
+
These variables are available throughout the change closure:
+
+
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
+
+
The change and rollback closures also have the following available:
+
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
+
+
init
+
+
+
This is where any optional initialization should happen. You can’t access the database from this closure.
+
+
+
validate
+
+
+
If there are any necessary validation checks before executing changes or rollbacks they should be done here. You can log warnings by calling warn(String message) and stop processing by calling error(String message). It may make more sense to use one or more preConditions instead of directly validating here.
+
+
+
change
+
+
+
All migration changes are done in the change closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
rollback
+
+
+
All rollback changes are done in the rollback closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
confirm
+
+
+
The confirm(String message) method is used to specify the confirmation message to be shown. The default is "Executed GrailsChange" and it can be overridden in the change or rollback closures to allow phase-specific messages or outside of both closures to use the same message for the update and rollback phase.
+
+
+
checkSum
+
+
+
The checksum for the change will be generated automatically, but if you want to override the value that gets hashed you can specify it with the checkSum(String value) method.
+
+
+
+
+
+
6. Groovy Preconditions
+
+
+
In addition to the built-in Liquibase preconditions (see the documentation for what’s available) you can also specify preconditions using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsPrecondition tag name and are contained in the databaseChangeLog tag or in a changeSet tag like standard built-in tags.
+
+
+
6.1. General format
+
+
This is the general format of a Groovy-based precondition:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ preConditions {
+
+ grailsPrecondition {
+
+ check {
+
+ // use an assertion
+ assert x == x
+
+ // use an assertion with an error message
+ assert y == y : 'value cannot be 237'
+
+ // call the fail method
+ if (x != x) {
+ fail 'x != x'
+ }
+
+ // throw an exception (the fail method is preferred)
+ if (y != y) {
+ thrownewRuntimeException('y != y')
+ }
+ }
+
+ }
+
+ }
+ }
+}
+
+
+
+
As you can see there are a few ways to indicate that a precondition wasn’t met:
+
+
+
+
+
use a simple assertion
+
+
+
use an assertion with a message
+
+
+
call the fail(String message) method (throws a PreconditionFailedException)
+
+
+
throw an exception (shouldn’t be necessary - use assert or fail() instead)
+
+
+
+
+
+
6.2. Available variables
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
changeLog - the current Liquibase DatabaseChangeLog instance
+
+
+
+
+
+
6.3. Utility methods
+
+
+
+
createDatabaseSnapshotGenerator() - retrieves the DatabaseSnapshotGenerator for the current Database
+
+
+
createDatabaseSnapshot(String schemaName = null) - creates a DatabaseSnapshot for the current Database (and schema if specified)
+
+
+
+
+
+
+
+
7. 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 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 dbm-generate-changelog script that creates a changelog from your database.
+
+
+
+
+
8. DbDoc Controller
+
+
+
You can use the 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):
Compares two databases and creates a changelog that will make the changes required to bring them into sync.
+
+
+
+
Description
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev) and another configured datasource in application.[yml|groovy].
+
+
+
If a filename parameter is specified then the output will be written to the named file, otherwise it will be written to the console. If the filename ends with .groovy a Groovy DSL file will be created, otherwise a standard XML file will be created.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.1.2. dbm-gorm-diff
+
+
Purpose
+
+
Diffs GORM classes against a database and generates a changelog XML or Groovy DSL file.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Similar to dbm-diff but diffs the current configuration based on the application’s domain classes with the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
Doesn’t modify any existing files - you need to manually merge the output into the changeset along with any necessary modifications.
+
+
+
You can configure database objects to be ignored by this script - either in the GORM classes or in the target database. For example you may want domain objects that are transient, or you may have externally-managed tables, keys, etc. that you want left alone by the diff script. The configuration name for these ignored objects is grails.plugin.databasemigration.ignoredObjects, whose value is a list of strings.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.2. Documentation Scripts
+
+
9.2.1. dbm-db-doc
+
+
Purpose
+
+
Generates Javadoc-like documentation based on current database and change log.
+
+
+
+
Description
+
+
Writes to the folder specified by the destination parameter, or to the grails.plugin.databasemigration.dbDocLocation configuration option (defaults to target/dbdoc).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.3. Maintenance Scripts
+
+
9.3.1. dbm-add-migration
+
+
Purpose
+
+
Adds a template migration file to your project and to the changelog file.
+
+
+
+
Description
+
+
This script provides a template in which to place your migration behaviour code, whether
+Grails code or raw SQL.
+For the dataSource parameter if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.3. dbm-changelog-sync
+
+
Purpose
+
+
Mark all changes as executed in the database.
+
+
+
+
Description
+
+
Registers all changesets as having been run in the Liquibase control table. This is useful when the changes have already been applied, for example if you’ve just created a changelog from your database using the dbm-generate-changelog script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.4. dbm-changelog-to-groovy
+
+
Purpose
+
+
Converts a Liquibase XML changelog file to a Groovy DSL file.
+
+
+
+
Description
+
+
If the Groovy file name isn’t specified the name and location will be the same as the original XML file with a .groovy extension.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
filename - The path to the output file to write to
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource creating a file named changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.8. dbm-list-locks
+
+
Purpose
+
+
Lists who currently has locks on the database changelog to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.11. dbm-register-changelog
+
+
Purpose
+
+
Adds an include for the specified changelog to the main changelog.
filename - The path to the changelog file to include.
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource using changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-diff "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.13. dbm-status
+
+
Purpose
+
+
Outputs count or list of unrun change sets to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.14. dbm-tag
+
+
Purpose
+
+
Adds a tag to mark the current database state.
+
+
+
+
Description
+
+
Useful for future rollbacks to a specific tag (e.g. using the dbm-rollback script).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
dataSource - if provided will run the script for the specified dataSource. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-validate "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.4. Rollback Scripts
+
+
9.4.1. dbm-future-rollback-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the current state after the changes in the changeslog have been applied to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.2. dbm-generate-changelog
+
+
Purpose
+
+
Generates an initial changelog XML or Groovy DSL file from the database.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.3. dbm-generate-gorm-changelog
+
+
Purpose
+
+
Generates an initial changelog XML or Groovy DSL file from current GORM classes.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in DataSource.groovy for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.4. dbm-rollback-count-sql
+
+
Purpose
+
+
Writes the SQL to roll back the specified number of change sets to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.6. dbm-rollback-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the state it was in when the tag was applied to STDOUT or a file.
+
+
+
+
Description
+
+
Requires that the named tag exists. You can create tags with the dbm-tag script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.7. dbm-rollback-to-date-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the state it was in at the given date/time to STDOUT or a file.
+
+
+
+
Description
+
+
You can specify just the date, or the date and time. The date format must be yyyy-MM-dd and the time format must be HH:mm:ss.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy],
+the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.8. dbm-rollback-to-date
+
+
Purpose
+
+
Rolls back the database to the state it was in at the given date/time.
+
+
+
+
Description
+
+
You can specify just the date, or the date and time. The date format must be yyyy-MM-dd and the time format must be HH:mm:ss.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.9. dbm-rollback
+
+
Purpose
+
+
Rolls back the database to the state it was in when the tag was applied.
+
+
+
+
Description
+
+
Requires that the named tag exists. You can create tags with the dbm-tag script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.5. Update Scripts
+
+
9.5.1. dbm-previous-changeset-sql
+
+
Purpose
+
+
Writes the SQL to STDOUT or a file for the specified number of previous changesets whether they have run or not.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
Writes the SQL that will partially update a database to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.3. dbm-update-count
+
+
Purpose
+
+
Partially updates a database.
+
+
+
+
Description
+
+
Runs the specifed number of un-run changesets from the Changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.4. dbm-update-sql
+
+
Purpose
+
+
Writes the SQL that will update the database to the current version to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.5. dbm-update
+
+
Purpose
+
+
Updates a database to the current version.
+
+
+
+
Description
+
+
Runs all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/introduction.html b/5.0.0/introduction.html
new file mode 100644
index 00000000..bb29852d
--- /dev/null
+++ b/5.0.0/introduction.html
@@ -0,0 +1,487 @@
+
+
+
+
+
+
+
+Introduction to the Database Migration Plugin
+
+
+
+
+
+
The Database Migration plugin helps you manage database changes while developing Grails applications. The plugin uses the Liquibase library.
+
+
+
Using this plugin (and Liquibase in general) adds some structure and process to managing database changes. It will help avoid inconsistencies, communication issues, and other problems with ad-hoc approaches.
+
+
+
Database migrations are represented in text form, either using a Groovy DSL or native Liquibase XML, in one or more changelog files. This approach makes it natural to maintain the changelog files in source control and also works well with branches. Changelog files can include other changelog files, so often developers create hierarchical files organized with various schemes. One popular approach is to have a root changelog named changlog.groovy (or changelog.xml) and to include a changelog per feature/branch that includes multiple smaller changelogs. Once the feature is finished and merged into the main development tree/trunk the changelog files can either stay as they are or be merged into one large file. Use whatever approach makes sense for your applications, but keep in mind that there are many options available for changelog management.
+
+
+
Individual changes have an ID that should be globally unique, although they also include the username of the user making the change, making the combination of ID and username unique (although technically the ID, username, and changelog location are the "unique key").
+
+
+
As you make changes in your code (typically domain classes) that require changes in the database, you add a new change set to the changelog. Commit the code changes along with the changelog additions, and the other developers on your team will get both when they update from source control. Once they apply the new changes their code and development database will be in sync with your changes. Likewise when you deploy to a QA, a staging server, or production, you’ll run the un-run changes that correspond to the code updates to being that environment’s database in sync. Liquibase keeps track of previously executed changes so there’s no need to think about what has and hasn’t been run yet.
+
+
+
Scripts
+
+
+
Your primary interaction with the plugin will be using the provided scripts. For the most part these correspond to the many Liquibase commands that are typically executed directly from the commandline or with its Ant targets, but there are also a few Grails-specific scripts that take advantage of the information available from the GORM mappings.
+
+
+
All the scripts start with dbm- to ensure that they’re unique and don’t clash with scripts from Grails or other plugins.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Diff Scripts/dbm-diff.html b/5.0.0/ref/Diff Scripts/dbm-diff.html
new file mode 100644
index 00000000..37b15178
--- /dev/null
+++ b/5.0.0/ref/Diff Scripts/dbm-diff.html
@@ -0,0 +1,550 @@
+
+
+
+
+
+
+
+dbm-diff
+
+
+
+
+
+
Compares two databases and creates a changelog that will make the changes required to bring them into sync.
+
+
+
+
Description
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev) and another configured datasource in application.[yml|groovy].
+
+
+
If a filename parameter is specified then the output will be written to the named file, otherwise it will be written to the console. If the filename ends with .groovy a Groovy DSL file will be created, otherwise a standard XML file will be created.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Diff Scripts/dbm-gorm-diff.html b/5.0.0/ref/Diff Scripts/dbm-gorm-diff.html
new file mode 100644
index 00000000..0cd75ce8
--- /dev/null
+++ b/5.0.0/ref/Diff Scripts/dbm-gorm-diff.html
@@ -0,0 +1,549 @@
+
+
+
+
+
+
+
+dbm-gorm-diff
+
+
+
+
+
+
Diffs GORM classes against a database and generates a changelog XML or Groovy DSL file.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Similar to dbm-diff but diffs the current configuration based on the application’s domain classes with the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
Doesn’t modify any existing files - you need to manually merge the output into the changeset along with any necessary modifications.
+
+
+
You can configure database objects to be ignored by this script - either in the GORM classes or in the target database. For example you may want domain objects that are transient, or you may have externally-managed tables, keys, etc. that you want left alone by the diff script. The configuration name for these ignored objects is grails.plugin.databasemigration.ignoredObjects, whose value is a list of strings.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Documentation Scripts/dbm-db-doc.html b/5.0.0/ref/Documentation Scripts/dbm-db-doc.html
new file mode 100644
index 00000000..d6f74812
--- /dev/null
+++ b/5.0.0/ref/Documentation Scripts/dbm-db-doc.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-db-doc
+
+
+
+
+
+
Generates Javadoc-like documentation based on current database and change log.
+
+
+
+
Description
+
+
Writes to the folder specified by the destination parameter, or to the grails.plugin.databasemigration.dbDocLocation configuration option (defaults to target/dbdoc).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-add-migration.html b/5.0.0/ref/Maintenance Scripts/dbm-add-migration.html
new file mode 100644
index 00000000..27a23a69
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-add-migration.html
@@ -0,0 +1,504 @@
+
+
+
+
+
+
+
+dbm-add-migration
+
+
+
+
+
+
+For the dataSource parameter if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-changelog-sync.html b/5.0.0/ref/Maintenance Scripts/dbm-changelog-sync.html
new file mode 100644
index 00000000..a329a176
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-changelog-sync.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-changelog-sync
+
+
+
+
+
+
Registers all changesets as having been run in the Liquibase control table. This is useful when the changes have already been applied, for example if you’ve just created a changelog from your database using the dbm-generate-changelog script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-changelog-to-groovy.html b/5.0.0/ref/Maintenance Scripts/dbm-changelog-to-groovy.html
new file mode 100644
index 00000000..361da5bc
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-changelog-to-groovy.html
@@ -0,0 +1,501 @@
+
+
+
+
+
+
+
+dbm-changelog-to-groovy
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-create-changelog.html b/5.0.0/ref/Maintenance Scripts/dbm-create-changelog.html
new file mode 100644
index 00000000..11fdb7f6
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-create-changelog.html
@@ -0,0 +1,535 @@
+
+
+
+
+
+
+
+dbm-create-changelog
+
+
+
+
+
+
filename - The path to the output file to write to
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource creating a file named changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-drop-all.html b/5.0.0/ref/Maintenance Scripts/dbm-drop-all.html
new file mode 100644
index 00000000..c06824fc
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-drop-all.html
@@ -0,0 +1,531 @@
+
+
+
+
+
+
+
+dbm-drop-all
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-list-locks.html b/5.0.0/ref/Maintenance Scripts/dbm-list-locks.html
new file mode 100644
index 00000000..84829ba8
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-list-locks.html
@@ -0,0 +1,531 @@
+
+
+
+
+
+
+
+dbm-list-locks
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-list-tags.html b/5.0.0/ref/Maintenance Scripts/dbm-list-tags.html
new file mode 100644
index 00000000..b4263cb2
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-list-tags.html
@@ -0,0 +1,511 @@
+
+
+
+
+
+
+
+dbm-list-tags
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-register-changelog.html b/5.0.0/ref/Maintenance Scripts/dbm-register-changelog.html
new file mode 100644
index 00000000..c1a3162e
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-register-changelog.html
@@ -0,0 +1,533 @@
+
+
+
+
+
+
+
+dbm-register-changelog
+
+
+
+
+
+
filename - The path to the changelog file to include.
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource using changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-diff "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-release-locks.html b/5.0.0/ref/Maintenance Scripts/dbm-release-locks.html
new file mode 100644
index 00000000..aa55bc1d
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-release-locks.html
@@ -0,0 +1,528 @@
+
+
+
+
+
+
+
+dbm-release-locks
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-status.html b/5.0.0/ref/Maintenance Scripts/dbm-status.html
new file mode 100644
index 00000000..90f8107d
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-status.html
@@ -0,0 +1,537 @@
+
+
+
+
+
+
+
+dbm-status
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-tag.html b/5.0.0/ref/Maintenance Scripts/dbm-tag.html
new file mode 100644
index 00000000..cf7b3d7b
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-tag.html
@@ -0,0 +1,538 @@
+
+
+
+
+
+
+
+dbm-tag
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Maintenance Scripts/dbm-validate.html b/5.0.0/ref/Maintenance Scripts/dbm-validate.html
new file mode 100644
index 00000000..f1e3f342
--- /dev/null
+++ b/5.0.0/ref/Maintenance Scripts/dbm-validate.html
@@ -0,0 +1,528 @@
+
+
+
+
+
+
+
+dbm-validate
+
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-validate "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-future-rollback-sql.html b/5.0.0/ref/Rollback Scripts/dbm-future-rollback-sql.html
new file mode 100644
index 00000000..d4ae1d51
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-future-rollback-sql.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-future-rollback-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-generate-changelog.html b/5.0.0/ref/Rollback Scripts/dbm-generate-changelog.html
new file mode 100644
index 00000000..99be89cf
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-generate-changelog.html
@@ -0,0 +1,546 @@
+
+
+
+
+
+
+
+dbm-generate-changelog
+
+
+
+
+
+
Generates an initial changelog XML or Groovy DSL file from the database.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-generate-gorm-changelog.html b/5.0.0/ref/Rollback Scripts/dbm-generate-gorm-changelog.html
new file mode 100644
index 00000000..4259a8e2
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-generate-gorm-changelog.html
@@ -0,0 +1,540 @@
+
+
+
+
+
+
+
+dbm-generate-gorm-changelog
+
+
+
+
+
+
Generates an initial changelog XML or Groovy DSL file from current GORM classes.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in DataSource.groovy for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback-count-sql.html b/5.0.0/ref/Rollback Scripts/dbm-rollback-count-sql.html
new file mode 100644
index 00000000..04deb2a9
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback-count-sql.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-rollback-count-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback-count.html b/5.0.0/ref/Rollback Scripts/dbm-rollback-count.html
new file mode 100644
index 00000000..9a0b6eeb
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback-count.html
@@ -0,0 +1,538 @@
+
+
+
+
+
+
+
+dbm-rollback-count
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback-sql.html b/5.0.0/ref/Rollback Scripts/dbm-rollback-sql.html
new file mode 100644
index 00000000..fa4e2adb
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback-sql.html
@@ -0,0 +1,544 @@
+
+
+
+
+
+
+
+dbm-rollback-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date-sql.html b/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date-sql.html
new file mode 100644
index 00000000..275498dc
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date-sql.html
@@ -0,0 +1,548 @@
+
+
+
+
+
+
+
+dbm-rollback-to-date-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy],
+the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date.html b/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date.html
new file mode 100644
index 00000000..df71af1d
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback-to-date.html
@@ -0,0 +1,544 @@
+
+
+
+
+
+
+
+dbm-rollback-to-date
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Rollback Scripts/dbm-rollback.html b/5.0.0/ref/Rollback Scripts/dbm-rollback.html
new file mode 100644
index 00000000..66b0a563
--- /dev/null
+++ b/5.0.0/ref/Rollback Scripts/dbm-rollback.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-rollback
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Update Scripts/dbm-previous-changeset-sql.html b/5.0.0/ref/Update Scripts/dbm-previous-changeset-sql.html
new file mode 100644
index 00000000..9c0058e0
--- /dev/null
+++ b/5.0.0/ref/Update Scripts/dbm-previous-changeset-sql.html
@@ -0,0 +1,527 @@
+
+
+
+
+
+
+
+dbm-previous-changeset-sql
+
+
+
+
+
+
Writes the SQL to STDOUT or a file for the specified number of previous changesets whether they have run or not.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
Writes the SQL that will partially update a database to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Update Scripts/dbm-update-count.html b/5.0.0/ref/Update Scripts/dbm-update-count.html
new file mode 100644
index 00000000..cbd74f1a
--- /dev/null
+++ b/5.0.0/ref/Update Scripts/dbm-update-count.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-update-count
+
+
+
+
+
+
Runs the specifed number of un-run changesets from the Changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Update Scripts/dbm-update-sql.html b/5.0.0/ref/Update Scripts/dbm-update-sql.html
new file mode 100644
index 00000000..dfc8555b
--- /dev/null
+++ b/5.0.0/ref/Update Scripts/dbm-update-sql.html
@@ -0,0 +1,540 @@
+
+
+
+
+
+
+
+dbm-update-sql
+
+
+
+
+
+
Writes the SQL that will update the database to the current version to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.0/ref/Update Scripts/dbm-update.html b/5.0.0/ref/Update Scripts/dbm-update.html
new file mode 100644
index 00000000..05ba1f5f
--- /dev/null
+++ b/5.0.0/ref/Update Scripts/dbm-update.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-update
+
+
+
+
+
+
Runs all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/api/allclasses-frame.html b/5.0.x/api/allclasses-frame.html
new file mode 100644
index 00000000..acb08022
--- /dev/null
+++ b/5.0.x/api/allclasses-frame.html
@@ -0,0 +1,63 @@
+
+
+
+
+All Classes
+
+
+
+
+
+
+
+
This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+
+
+
+
+
Overview
+
The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
+
+
+
Package
+
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
+
+
Interfaces (italic)
+
Classes
+
Enums
+
Exceptions
+
Errors
+
Annotation Types
+
+
+
+
Class/Interface
+
Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
+
Class inheritance diagram
+
Direct Subclasses
+
All Known Subinterfaces
+
All Known Implementing Classes
+
Class/interface declaration
+
Class/interface description
+
+
+
Nested Class Summary
+
Field Summary
+
Constructor Summary
+
Method Summary
+
+
+
Field Detail
+
Constructor Detail
+
Method Detail
+
+
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+
Annotation Type
+
Each annotation type has its own separate page with the following sections:
+
+
Annotation Type declaration
+
Annotation Type description
+
Required Element Summary
+
Optional Element Summary
+
Element Detail
+
+
+
+
Enum
+
Each enum has its own separate page with the following sections:
+
+
Enum declaration
+
Enum description
+
Enum Constant Summary
+
Enum Constant Detail
+
+
+
+
+
Deprecated API
+
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+
+
Index
+
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+
+
Frames/No Frames
+
These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+
All Classes
+
The All Classes link shows all classes and interfaces except non-static nested types.
+
+
+
Serialized Form
+
Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
The transactionManager bean for the current dataSource
+
+
+
+
+
void
+
withNewTransaction(groovy.lang.Closure callable) Executes the closure within the context of a new transaction
+
+
+
+
+
void
+
withNewTransaction(java.util.Map transactionProperties, groovy.lang.Closure callable) Executes the closure within the context of a new transaction which is
+ configured with the properties contained in transactionProperties.
+
+
+
+
+
+
void
+
withTransaction(groovy.lang.Closure callable) Executes the closure within the context of a transaction, creating one if none is present or joining
+ an existing transaction if one is already present.
withTransaction(TransactionDefinition definition, groovy.lang.Closure callable) Executes the closure within the context of a transaction for the given TransactionDefinition
Executes the closure within the context of a new transaction which is
+ configured with the properties contained in transactionProperties.
+ transactionProperties may contain any properties supported by
+ DefaultTransactionDefinition. Note that if transactionProperties
+ includes entries for propagationBehavior or propagationName, those values
+ will be ignored. This method always sets the propagation level to
+ TransactionDefinition.REQUIRES_NEW.
+
+
Executes the closure within the context of a transaction, creating one if none is present or joining
+ an existing transaction if one is already present.
@groovy.transform.CompileStatic
+@liquibase.change.DatabaseChange(name: grailsChange, description: Adds creates a primary key out of an existing column or set of columns., priority: ChangeMetaData.PRIORITY_DEFAULT)
+class GroovyChange
+extends AbstractChange
There are a few configuration options for the plugin. All configurations are prefixed with grails.plugin.databasemigration:
+
+
+
+
+
+
+
+
+
+
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 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 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 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
+
+
+
+
+
+
+
+
+
+
+All the above configs can be used for multiple datasources
+
+
+
+
+
+
Multiple DataSource Example:
+
+
+
If secondary dataSource named "second" is configured in application.yml
You can use the 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):
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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
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 dbm-gorm-diff script (you can also use the 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
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.
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
You should also tell Gradle about the migrations folder. If using Grails 4, make sure the configuration below is BEFORE the
+dependencies configuration, so that the sourceSets declaration takes effect.
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.
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.
+
+
+
+
+
+
+
+
+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:
+
If you haven’t created the database yet, run the dbm-update script to create the corresponding tables:
+
+
+
+
grails dbm-update
+
+
+
+
or the dbm-changelog-sync script if the database is already in sync with your code:
+
+
+
+
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.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/gorm.html b/5.0.x/gorm.html
new file mode 100644
index 00000000..63886c08
--- /dev/null
+++ b/5.0.x/gorm.html
@@ -0,0 +1,512 @@
+
+
+
+
+
+
+
+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 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 dbm-generate-changelog script that creates a changelog from your database.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/groovyChanges.html b/5.0.x/groovyChanges.html
new file mode 100644
index 00000000..73954491
--- /dev/null
+++ b/5.0.x/groovyChanges.html
@@ -0,0 +1,599 @@
+
+
+
+
+
+
+
+Groovy Changes
+
+
+
+
+
+
In addition to the built-in Liquibase changes (see the documentation for what’s available) you can also make database changes using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsChange tag name and are contained in a changeSet tag like standard built-in tags.
+
+
+
There are four supported inner tags and two callable methods (to override the default confirmation message and checksum value).
+
+
+
General format
+
+
This is the general format of a Groovy-based change; all inner tags and methods are optional:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ grailsChange {
+ init {
+ // arbitrary initialization code; note that no
+ // database or connection is available
+ }
+
+ validate {
+ // can call warn(String message) to log a warning
+ // or error(String message) to stop processing
+ }
+
+ change {
+ // arbitrary code; make changes directly and/or return a
+ // SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'change confirmation message'
+ }
+
+ rollback {
+ // arbitrary code; make rollback changes directly and/or
+ // return a SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'rollback confirmation message'
+ }
+
+ confirm 'confirmation message'
+
+ checkSum 'override value for checksum'
+ }
+
+ }
+}
+
+
+
+
+
Available variables
+
+
These variables are available throughout the change closure:
+
+
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
+
+
The change and rollback closures also have the following available:
+
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
+
+
init
+
+
+
This is where any optional initialization should happen. You can’t access the database from this closure.
+
+
+
validate
+
+
+
If there are any necessary validation checks before executing changes or rollbacks they should be done here. You can log warnings by calling warn(String message) and stop processing by calling error(String message). It may make more sense to use one or more preConditions instead of directly validating here.
+
+
+
change
+
+
+
All migration changes are done in the change closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
rollback
+
+
+
All rollback changes are done in the rollback closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
confirm
+
+
+
The confirm(String message) method is used to specify the confirmation message to be shown. The default is "Executed GrailsChange" and it can be overridden in the change or rollback closures to allow phase-specific messages or outside of both closures to use the same message for the update and rollback phase.
+
+
+
checkSum
+
+
+
The checksum for the change will be generated automatically, but if you want to override the value that gets hashed you can specify it with the checkSum(String value) method.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/groovyPreconditions.html b/5.0.x/groovyPreconditions.html
new file mode 100644
index 00000000..40b97e82
--- /dev/null
+++ b/5.0.x/groovyPreconditions.html
@@ -0,0 +1,580 @@
+
+
+
+
+
+
+
+Groovy Preconditions
+
+
+
+
+
+
In addition to the built-in Liquibase preconditions (see the documentation for what’s available) you can also specify preconditions using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsPrecondition tag name and are contained in the databaseChangeLog tag or in a changeSet tag like standard built-in tags.
+
+
+
General format
+
+
This is the general format of a Groovy-based precondition:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ preConditions {
+
+ grailsPrecondition {
+
+ check {
+
+ // use an assertion
+ assert x == x
+
+ // use an assertion with an error message
+ assert y == y : 'value cannot be 237'
+
+ // call the fail method
+ if (x != x) {
+ fail 'x != x'
+ }
+
+ // throw an exception (the fail method is preferred)
+ if (y != y) {
+ throw new RuntimeException('y != y')
+ }
+ }
+
+ }
+
+ }
+ }
+}
+
+
+
+
As you can see there are a few ways to indicate that a precondition wasn’t met:
+
+
+
+
+
use a simple assertion
+
+
+
use an assertion with a message
+
+
+
call the fail(String message) method (throws a PreconditionFailedException)
+
+
+
throw an exception (shouldn’t be necessary - use assert or fail() instead)
+
+
+
+
+
+
Available variables
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
changeLog - the current Liquibase DatabaseChangeLog instance
+
+
+
+
+
+
Utility methods
+
+
+
+
createDatabaseSnapshotGenerator() - retrieves the DatabaseSnapshotGenerator for the current Database
+
+
+
createDatabaseSnapshot(String schemaName = null) - creates a DatabaseSnapshot for the current Database (and schema if specified)
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/index.html b/5.0.x/index.html
new file mode 100644
index 00000000..83fce431
--- /dev/null
+++ b/5.0.x/index.html
@@ -0,0 +1,3884 @@
+
+
+
+
+
+
+
+Grails Database Migration Plugin
+
+
+
+
+
+
+
The Database Migration plugin helps you manage database changes while developing Grails applications. The plugin uses the Liquibase library.
+
+
+
Using this plugin (and Liquibase in general) adds some structure and process to managing database changes. It will help avoid inconsistencies, communication issues, and other problems with ad-hoc approaches.
+
+
+
Database migrations are represented in text form, either using a Groovy DSL or native Liquibase XML, in one or more changelog files. This approach makes it natural to maintain the changelog files in source control and also works well with branches. Changelog files can include other changelog files, so often developers create hierarchical files organized with various schemes. One popular approach is to have a root changelog named changlog.groovy (or changelog.xml) and to include a changelog per feature/branch that includes multiple smaller changelogs. Once the feature is finished and merged into the main development tree/trunk the changelog files can either stay as they are or be merged into one large file. Use whatever approach makes sense for your applications, but keep in mind that there are many options available for changelog management.
+
+
+
Individual changes have an ID that should be globally unique, although they also include the username of the user making the change, making the combination of ID and username unique (although technically the ID, username, and changelog location are the "unique key").
+
+
+
As you make changes in your code (typically domain classes) that require changes in the database, you add a new change set to the changelog. Commit the code changes along with the changelog additions, and the other developers on your team will get both when they update from source control. Once they apply the new changes their code and development database will be in sync with your changes. Likewise when you deploy to a QA, a staging server, or production, you’ll run the un-run changes that correspond to the code updates to being that environment’s database in sync. Liquibase keeps track of previously executed changes so there’s no need to think about what has and hasn’t been run yet.
+
+
+
Scripts
+
+
+
Your primary interaction with the plugin will be using the provided scripts. For the most part these correspond to the many Liquibase commands that are typically executed directly from the commandline or with its Ant targets, but there are also a few Grails-specific scripts that take advantage of the information available from the GORM mappings.
+
+
+
All the scripts start with dbm- to ensure that they’re unique and don’t clash with scripts from Grails or other plugins.
+
+
+
+
+
2. Getting Started
+
+
+
The first step is to add a dependency for the plugin in build.gradle:
You should also tell Gradle about the migrations folder. If using Grails 4, make sure the configuration below is BEFORE the
+dependencies configuration, so that the sourceSets declaration takes effect.
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.
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.
+
+
+
+
+
+
+
+
+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:
+
If you haven’t created the database yet, run the dbm-update script to create the corresponding tables:
+
+
+
+
grails dbm-update
+
+
+
+
or the dbm-changelog-sync script if the database is already in sync with your code:
+
+
+
+
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.
+
+
+
+
+
3. Configuration
+
+
+
There are a few configuration options for the plugin. All configurations are prefixed with grails.plugin.databasemigration:
+
+
+
+
+
+
+
+
+
+
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 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 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 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
+
+
+
+
+
+
+
+
+
+
+All the above configs can be used for multiple datasources
+
+
+
+
+
+
Multiple DataSource Example:
+
+
+
If secondary dataSource named "second" is configured in application.yml
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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
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 dbm-gorm-diff script (you can also use the 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.
+
+
+
4.1. 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
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.
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
In addition to the built-in Liquibase changes (see the documentation for what’s available) you can also make database changes using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsChange tag name and are contained in a changeSet tag like standard built-in tags.
+
+
+
There are four supported inner tags and two callable methods (to override the default confirmation message and checksum value).
+
+
+
5.1. General format
+
+
This is the general format of a Groovy-based change; all inner tags and methods are optional:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ grailsChange {
+ init {
+ // arbitrary initialization code; note that no
+ // database or connection is available
+ }
+
+ validate {
+ // can call warn(String message) to log a warning
+ // or error(String message) to stop processing
+ }
+
+ change {
+ // arbitrary code; make changes directly and/or return a
+ // SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'change confirmation message'
+ }
+
+ rollback {
+ // arbitrary code; make rollback changes directly and/or
+ // return a SqlStatement using the sqlStatement(SqlStatement sqlStatement)
+ // method or multiple with sqlStatements(List sqlStatements)
+
+ confirm 'rollback confirmation message'
+ }
+
+ confirm 'confirmation message'
+
+ checkSum 'override value for checksum'
+ }
+
+ }
+}
+
+
+
+
+
5.2. Available variables
+
+
These variables are available throughout the change closure:
+
+
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
+
+
The change and rollback closures also have the following available:
+
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
+
+
init
+
+
+
This is where any optional initialization should happen. You can’t access the database from this closure.
+
+
+
validate
+
+
+
If there are any necessary validation checks before executing changes or rollbacks they should be done here. You can log warnings by calling warn(String message) and stop processing by calling error(String message). It may make more sense to use one or more preConditions instead of directly validating here.
+
+
+
change
+
+
+
All migration changes are done in the change closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
rollback
+
+
+
All rollback changes are done in the rollback closure. You can make changes directly (using the sql instance or the connection) and/or return one or more SqlStatements. You can call sqlStatement(SqlStatement statement) multiple times to register instances to be run. You can also call the sqlStatements(statements) method with an array or list of instances to be run.
+
+
+
confirm
+
+
+
The confirm(String message) method is used to specify the confirmation message to be shown. The default is "Executed GrailsChange" and it can be overridden in the change or rollback closures to allow phase-specific messages or outside of both closures to use the same message for the update and rollback phase.
+
+
+
checkSum
+
+
+
The checksum for the change will be generated automatically, but if you want to override the value that gets hashed you can specify it with the checkSum(String value) method.
+
+
+
+
+
+
6. Groovy Preconditions
+
+
+
In addition to the built-in Liquibase preconditions (see the documentation for what’s available) you can also specify preconditions using Groovy code (as long as you’re using the Groovy DSL file format). These changes use the grailsPrecondition tag name and are contained in the databaseChangeLog tag or in a changeSet tag like standard built-in tags.
+
+
+
6.1. General format
+
+
This is the general format of a Groovy-based precondition:
+
+
+
+
databaseChangeLog = {
+
+ changeSet(author: '...', id: '...') {
+
+ preConditions {
+
+ grailsPrecondition {
+
+ check {
+
+ // use an assertion
+ assert x == x
+
+ // use an assertion with an error message
+ assert y == y : 'value cannot be 237'
+
+ // call the fail method
+ if (x != x) {
+ fail 'x != x'
+ }
+
+ // throw an exception (the fail method is preferred)
+ if (y != y) {
+ thrownewRuntimeException('y != y')
+ }
+ }
+
+ }
+
+ }
+ }
+}
+
+
+
+
As you can see there are a few ways to indicate that a precondition wasn’t met:
+
+
+
+
+
use a simple assertion
+
+
+
use an assertion with a message
+
+
+
call the fail(String message) method (throws a PreconditionFailedException)
+
+
+
throw an exception (shouldn’t be necessary - use assert or fail() instead)
+
+
+
+
+
+
6.2. Available variables
+
+
+
+
database - the current Liquibase Database instance
+
+
+
databaseConnection - the current Liquibase DatabaseConnection instance, which is a wrapper around the JDBC Connection (but doesn’t implement the Connection interface)
+
+
+
connection - the real JDBC Connection instance (a shortcut for database.connection.wrappedConnection)
+
+
+
sql - a groovy.sql.Sql instance which uses the current connection and can be used for arbitrary queries and updates
+
+
+
resourceAccessor - the current Liquibase ResourceAccessor instance
+
+
+
ctx - the Spring ApplicationContext
+
+
+
application - the GrailsApplication
+
+
+
changeSet - the current Liquibase ChangeSet instance
+
+
+
changeLog - the current Liquibase DatabaseChangeLog instance
+
+
+
+
+
+
6.3. Utility methods
+
+
+
+
createDatabaseSnapshotGenerator() - retrieves the DatabaseSnapshotGenerator for the current Database
+
+
+
createDatabaseSnapshot(String schemaName = null) - creates a DatabaseSnapshot for the current Database (and schema if specified)
+
+
+
+
+
+
+
+
7. 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 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 dbm-generate-changelog script that creates a changelog from your database.
+
+
+
+
+
8. DbDoc Controller
+
+
+
You can use the 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):
Compares two databases and creates a changelog that will make the changes required to bring them into sync.
+
+
+
+
Description
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev) and another configured datasource in application.[yml|groovy].
+
+
+
If a filename parameter is specified then the output will be written to the named file, otherwise it will be written to the console. If the filename ends with .groovy a Groovy DSL file will be created, otherwise a standard XML file will be created.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.1.2. dbm-gorm-diff
+
+
Purpose
+
+
Diffs GORM classes against a database and generates a changelog XML or Groovy DSL file.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Similar to dbm-diff but diffs the current configuration based on the application’s domain classes with the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
Doesn’t modify any existing files - you need to manually merge the output into the changeset along with any necessary modifications.
+
+
+
You can configure database objects to be ignored by this script - either in the GORM classes or in the target database. For example you may want domain objects that are transient, or you may have externally-managed tables, keys, etc. that you want left alone by the diff script. The configuration name for these ignored objects is grails.plugin.databasemigration.ignoredObjects, whose value is a list of strings.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.2. Documentation Scripts
+
+
9.2.1. dbm-db-doc
+
+
Purpose
+
+
Generates Javadoc-like documentation based on current database and change log.
+
+
+
+
Description
+
+
Writes to the folder specified by the destination parameter, or to the grails.plugin.databasemigration.dbDocLocation configuration option (defaults to target/dbdoc).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.3. Maintenance Scripts
+
+
9.3.1. dbm-add-migration
+
+
Purpose
+
+
Adds a template migration file to your project and to the changelog file.
+
+
+
+
Description
+
+
This script provides a template in which to place your migration behaviour code, whether
+Grails code or raw SQL.
+For the dataSource parameter if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.3. dbm-changelog-sync
+
+
Purpose
+
+
Mark all changes as executed in the database.
+
+
+
+
Description
+
+
Registers all changesets as having been run in the Liquibase control table. This is useful when the changes have already been applied, for example if you’ve just created a changelog from your database using the dbm-generate-changelog script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.4. dbm-changelog-to-groovy
+
+
Purpose
+
+
Converts a Liquibase XML changelog file to a Groovy DSL file.
+
+
+
+
Description
+
+
If the Groovy file name isn’t specified the name and location will be the same as the original XML file with a .groovy extension.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
filename - The path to the output file to write to
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource creating a file named changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.8. dbm-list-locks
+
+
Purpose
+
+
Lists who currently has locks on the database changelog to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.11. dbm-register-changelog
+
+
Purpose
+
+
Adds an include for the specified changelog to the main changelog.
filename - The path to the changelog file to include.
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource using changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-diff "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.13. dbm-status
+
+
Purpose
+
+
Outputs count or list of unrun change sets to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.3.14. dbm-tag
+
+
Purpose
+
+
Adds a tag to mark the current database state.
+
+
+
+
Description
+
+
Useful for future rollbacks to a specific tag (e.g. using the dbm-rollback script).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
dataSource - if provided will run the script for the specified dataSource. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-validate "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.4. Rollback Scripts
+
+
9.4.1. dbm-future-rollback-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the current state after the changes in the changeslog have been applied to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.2. dbm-generate-changelog
+
+
Purpose
+
+
Generates an initial changelog XML or Groovy DSL file from the database.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.3. dbm-generate-gorm-changelog
+
+
Purpose
+
+
Generates an initial changelog XML or Groovy DSL file from current GORM classes.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in DataSource.groovy for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.4. dbm-rollback-count-sql
+
+
Purpose
+
+
Writes the SQL to roll back the specified number of change sets to STDOUT or a file.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.6. dbm-rollback-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the state it was in when the tag was applied to STDOUT or a file.
+
+
+
+
Description
+
+
Requires that the named tag exists. You can create tags with the dbm-tag script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.7. dbm-rollback-to-date-sql
+
+
Purpose
+
+
Writes SQL to roll back the database to the state it was in at the given date/time to STDOUT or a file.
+
+
+
+
Description
+
+
You can specify just the date, or the date and time. The date format must be yyyy-MM-dd and the time format must be HH:mm:ss.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy],
+the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.8. dbm-rollback-to-date
+
+
Purpose
+
+
Rolls back the database to the state it was in at the given date/time.
+
+
+
+
Description
+
+
You can specify just the date, or the date and time. The date format must be yyyy-MM-dd and the time format must be HH:mm:ss.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.4.9. dbm-rollback
+
+
Purpose
+
+
Rolls back the database to the state it was in when the tag was applied.
+
+
+
+
Description
+
+
Requires that the named tag exists. You can create tags with the dbm-tag script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
9.5. Update Scripts
+
+
9.5.1. dbm-previous-changeset-sql
+
+
Purpose
+
+
Writes the SQL to STDOUT or a file for the specified number of previous changesets whether they have run or not.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
Writes the SQL that will partially update a database to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.3. dbm-update-count
+
+
Purpose
+
+
Partially updates a database.
+
+
+
+
Description
+
+
Runs the specifed number of un-run changesets from the Changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.4. dbm-update-sql
+
+
Purpose
+
+
Writes the SQL that will update the database to the current version to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
9.5.5. dbm-update
+
+
Purpose
+
+
Updates a database to the current version.
+
+
+
+
Description
+
+
Runs all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/introduction.html b/5.0.x/introduction.html
new file mode 100644
index 00000000..bb29852d
--- /dev/null
+++ b/5.0.x/introduction.html
@@ -0,0 +1,487 @@
+
+
+
+
+
+
+
+Introduction to the Database Migration Plugin
+
+
+
+
+
+
The Database Migration plugin helps you manage database changes while developing Grails applications. The plugin uses the Liquibase library.
+
+
+
Using this plugin (and Liquibase in general) adds some structure and process to managing database changes. It will help avoid inconsistencies, communication issues, and other problems with ad-hoc approaches.
+
+
+
Database migrations are represented in text form, either using a Groovy DSL or native Liquibase XML, in one or more changelog files. This approach makes it natural to maintain the changelog files in source control and also works well with branches. Changelog files can include other changelog files, so often developers create hierarchical files organized with various schemes. One popular approach is to have a root changelog named changlog.groovy (or changelog.xml) and to include a changelog per feature/branch that includes multiple smaller changelogs. Once the feature is finished and merged into the main development tree/trunk the changelog files can either stay as they are or be merged into one large file. Use whatever approach makes sense for your applications, but keep in mind that there are many options available for changelog management.
+
+
+
Individual changes have an ID that should be globally unique, although they also include the username of the user making the change, making the combination of ID and username unique (although technically the ID, username, and changelog location are the "unique key").
+
+
+
As you make changes in your code (typically domain classes) that require changes in the database, you add a new change set to the changelog. Commit the code changes along with the changelog additions, and the other developers on your team will get both when they update from source control. Once they apply the new changes their code and development database will be in sync with your changes. Likewise when you deploy to a QA, a staging server, or production, you’ll run the un-run changes that correspond to the code updates to being that environment’s database in sync. Liquibase keeps track of previously executed changes so there’s no need to think about what has and hasn’t been run yet.
+
+
+
Scripts
+
+
+
Your primary interaction with the plugin will be using the provided scripts. For the most part these correspond to the many Liquibase commands that are typically executed directly from the commandline or with its Ant targets, but there are also a few Grails-specific scripts that take advantage of the information available from the GORM mappings.
+
+
+
All the scripts start with dbm- to ensure that they’re unique and don’t clash with scripts from Grails or other plugins.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Diff Scripts/dbm-diff.html b/5.0.x/ref/Diff Scripts/dbm-diff.html
new file mode 100644
index 00000000..37b15178
--- /dev/null
+++ b/5.0.x/ref/Diff Scripts/dbm-diff.html
@@ -0,0 +1,550 @@
+
+
+
+
+
+
+
+dbm-diff
+
+
+
+
+
+
Compares two databases and creates a changelog that will make the changes required to bring them into sync.
+
+
+
+
Description
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev) and another configured datasource in application.[yml|groovy].
+
+
+
If a filename parameter is specified then the output will be written to the named file, otherwise it will be written to the console. If the filename ends with .groovy a Groovy DSL file will be created, otherwise a standard XML file will be created.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Diff Scripts/dbm-gorm-diff.html b/5.0.x/ref/Diff Scripts/dbm-gorm-diff.html
new file mode 100644
index 00000000..0cd75ce8
--- /dev/null
+++ b/5.0.x/ref/Diff Scripts/dbm-gorm-diff.html
@@ -0,0 +1,549 @@
+
+
+
+
+
+
+
+dbm-gorm-diff
+
+
+
+
+
+
Diffs GORM classes against a database and generates a changelog XML or Groovy DSL file.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Similar to dbm-diff but diffs the current configuration based on the application’s domain classes with the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
Doesn’t modify any existing files - you need to manually merge the output into the changeset along with any necessary modifications.
+
+
+
You can configure database objects to be ignored by this script - either in the GORM classes or in the target database. For example you may want domain objects that are transient, or you may have externally-managed tables, keys, etc. that you want left alone by the diff script. The configuration name for these ignored objects is grails.plugin.databasemigration.ignoredObjects, whose value is a list of strings.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Documentation Scripts/dbm-db-doc.html b/5.0.x/ref/Documentation Scripts/dbm-db-doc.html
new file mode 100644
index 00000000..d6f74812
--- /dev/null
+++ b/5.0.x/ref/Documentation Scripts/dbm-db-doc.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-db-doc
+
+
+
+
+
+
Generates Javadoc-like documentation based on current database and change log.
+
+
+
+
Description
+
+
Writes to the folder specified by the destination parameter, or to the grails.plugin.databasemigration.dbDocLocation configuration option (defaults to target/dbdoc).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-add-migration.html b/5.0.x/ref/Maintenance Scripts/dbm-add-migration.html
new file mode 100644
index 00000000..27a23a69
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-add-migration.html
@@ -0,0 +1,504 @@
+
+
+
+
+
+
+
+dbm-add-migration
+
+
+
+
+
+
+For the dataSource parameter if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-changelog-sync.html b/5.0.x/ref/Maintenance Scripts/dbm-changelog-sync.html
new file mode 100644
index 00000000..a329a176
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-changelog-sync.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-changelog-sync
+
+
+
+
+
+
Registers all changesets as having been run in the Liquibase control table. This is useful when the changes have already been applied, for example if you’ve just created a changelog from your database using the dbm-generate-changelog script.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-changelog-to-groovy.html b/5.0.x/ref/Maintenance Scripts/dbm-changelog-to-groovy.html
new file mode 100644
index 00000000..361da5bc
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-changelog-to-groovy.html
@@ -0,0 +1,501 @@
+
+
+
+
+
+
+
+dbm-changelog-to-groovy
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-create-changelog.html b/5.0.x/ref/Maintenance Scripts/dbm-create-changelog.html
new file mode 100644
index 00000000..11fdb7f6
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-create-changelog.html
@@ -0,0 +1,535 @@
+
+
+
+
+
+
+
+dbm-create-changelog
+
+
+
+
+
+
filename - The path to the output file to write to
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource creating a file named changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-drop-all.html b/5.0.x/ref/Maintenance Scripts/dbm-drop-all.html
new file mode 100644
index 00000000..c06824fc
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-drop-all.html
@@ -0,0 +1,531 @@
+
+
+
+
+
+
+
+dbm-drop-all
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-list-locks.html b/5.0.x/ref/Maintenance Scripts/dbm-list-locks.html
new file mode 100644
index 00000000..84829ba8
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-list-locks.html
@@ -0,0 +1,531 @@
+
+
+
+
+
+
+
+dbm-list-locks
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-list-tags.html b/5.0.x/ref/Maintenance Scripts/dbm-list-tags.html
new file mode 100644
index 00000000..b4263cb2
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-list-tags.html
@@ -0,0 +1,511 @@
+
+
+
+
+
+
+
+dbm-list-tags
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-register-changelog.html b/5.0.x/ref/Maintenance Scripts/dbm-register-changelog.html
new file mode 100644
index 00000000..c1a3162e
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-register-changelog.html
@@ -0,0 +1,533 @@
+
+
+
+
+
+
+
+dbm-register-changelog
+
+
+
+
+
+
filename - The path to the changelog file to include.
+
+
+
+
+
Optional arguments:
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource using changelog-<<dataSource>>.groovy if a filename is not given. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-diff "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy]
+the suffix of reports will be used as the parameter value.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-release-locks.html b/5.0.x/ref/Maintenance Scripts/dbm-release-locks.html
new file mode 100644
index 00000000..aa55bc1d
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-release-locks.html
@@ -0,0 +1,528 @@
+
+
+
+
+
+
+
+dbm-release-locks
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-status.html b/5.0.x/ref/Maintenance Scripts/dbm-status.html
new file mode 100644
index 00000000..90f8107d
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-status.html
@@ -0,0 +1,537 @@
+
+
+
+
+
+
+
+dbm-status
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-tag.html b/5.0.x/ref/Maintenance Scripts/dbm-tag.html
new file mode 100644
index 00000000..cf7b3d7b
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-tag.html
@@ -0,0 +1,538 @@
+
+
+
+
+
+
+
+dbm-tag
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Maintenance Scripts/dbm-validate.html b/5.0.x/ref/Maintenance Scripts/dbm-validate.html
new file mode 100644
index 00000000..f1e3f342
--- /dev/null
+++ b/5.0.x/ref/Maintenance Scripts/dbm-validate.html
@@ -0,0 +1,528 @@
+
+
+
+
+
+
+
+dbm-validate
+
+
+
+
+
+
dataSource - if provided will run the script for the specified dataSource. Not needed for the default dataSource.
+
+
+
+
+
+
+
+
+
+
+Note that the dataSource parameter name and value must be quoted if executed in Windows, e.g.
+
+
+
+
+
+
+
grails dbm-validate "--dataSource=<<dataSource>>"
+
+
+
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-future-rollback-sql.html b/5.0.x/ref/Rollback Scripts/dbm-future-rollback-sql.html
new file mode 100644
index 00000000..d4ae1d51
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-future-rollback-sql.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-future-rollback-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-generate-changelog.html b/5.0.x/ref/Rollback Scripts/dbm-generate-changelog.html
new file mode 100644
index 00000000..99be89cf
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-generate-changelog.html
@@ -0,0 +1,546 @@
+
+
+
+
+
+
+
+dbm-generate-changelog
+
+
+
+
+
+
Generates an initial changelog XML or Groovy DSL file from the database.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-generate-gorm-changelog.html b/5.0.x/ref/Rollback Scripts/dbm-generate-gorm-changelog.html
new file mode 100644
index 00000000..4259a8e2
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-generate-gorm-changelog.html
@@ -0,0 +1,540 @@
+
+
+
+
+
+
+
+dbm-generate-gorm-changelog
+
+
+
+
+
+
Generates an initial changelog XML or Groovy DSL file from current GORM classes.
+
+
+
+
Description
+
+
Creates a Groovy DSL file if the filename is specified and it ends with .groovy. If another extension is specified it creates a standard Liquibase XML file, and if no filename is specified it writes to the console.
+
+
+
File are written to the migrations folder, so specify the filename relative to the migrations folder (grails-app/migrations by default).
+
+
+
Executes against the database configured in DataSource.groovy for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback-count-sql.html b/5.0.x/ref/Rollback Scripts/dbm-rollback-count-sql.html
new file mode 100644
index 00000000..04deb2a9
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback-count-sql.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-rollback-count-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback-count.html b/5.0.x/ref/Rollback Scripts/dbm-rollback-count.html
new file mode 100644
index 00000000..9a0b6eeb
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback-count.html
@@ -0,0 +1,538 @@
+
+
+
+
+
+
+
+dbm-rollback-count
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback-sql.html b/5.0.x/ref/Rollback Scripts/dbm-rollback-sql.html
new file mode 100644
index 00000000..fa4e2adb
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback-sql.html
@@ -0,0 +1,544 @@
+
+
+
+
+
+
+
+dbm-rollback-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date-sql.html b/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date-sql.html
new file mode 100644
index 00000000..275498dc
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date-sql.html
@@ -0,0 +1,548 @@
+
+
+
+
+
+
+
+dbm-rollback-to-date-sql
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy],
+the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date.html b/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date.html
new file mode 100644
index 00000000..df71af1d
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback-to-date.html
@@ -0,0 +1,544 @@
+
+
+
+
+
+
+
+dbm-rollback-to-date
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Rollback Scripts/dbm-rollback.html b/5.0.x/ref/Rollback Scripts/dbm-rollback.html
new file mode 100644
index 00000000..66b0a563
--- /dev/null
+++ b/5.0.x/ref/Rollback Scripts/dbm-rollback.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-rollback
+
+
+
+
+
+
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Update Scripts/dbm-previous-changeset-sql.html b/5.0.x/ref/Update Scripts/dbm-previous-changeset-sql.html
new file mode 100644
index 00000000..9c0058e0
--- /dev/null
+++ b/5.0.x/ref/Update Scripts/dbm-previous-changeset-sql.html
@@ -0,0 +1,527 @@
+
+
+
+
+
+
+
+dbm-previous-changeset-sql
+
+
+
+
+
+
Writes the SQL to STDOUT or a file for the specified number of previous changesets whether they have run or not.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
Writes the SQL that will partially update a database to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for the specifed number of changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Update Scripts/dbm-update-count.html b/5.0.x/ref/Update Scripts/dbm-update-count.html
new file mode 100644
index 00000000..cbd74f1a
--- /dev/null
+++ b/5.0.x/ref/Update Scripts/dbm-update-count.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+
+
+dbm-update-count
+
+
+
+
+
+
Runs the specifed number of un-run changesets from the Changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Update Scripts/dbm-update-sql.html b/5.0.x/ref/Update Scripts/dbm-update-sql.html
new file mode 100644
index 00000000..dfc8555b
--- /dev/null
+++ b/5.0.x/ref/Update Scripts/dbm-update-sql.html
@@ -0,0 +1,540 @@
+
+
+
+
+
+
+
+dbm-update-sql
+
+
+
+
+
+
Writes the SQL that will update the database to the current version to STDOUT or a file.
+
+
+
+
Description
+
+
Generates SQL for all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+
+
+
This is useful for inspecting the generated SQL before running an update, or to generate SQL which can be tuned before running manually.
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/5.0.x/ref/Update Scripts/dbm-update.html b/5.0.x/ref/Update Scripts/dbm-update.html
new file mode 100644
index 00000000..05ba1f5f
--- /dev/null
+++ b/5.0.x/ref/Update Scripts/dbm-update.html
@@ -0,0 +1,534 @@
+
+
+
+
+
+
+
+dbm-update
+
+
+
+
+
+
Runs all un-run changeSets from the changelog. Executes against the database configured in application.[yml|groovy] for the current environment (defaults to dev).
+For the dataSource parameter, if the data source is configured as reports underneath the dataSources key in application.[yml|groovy], the value should be reports.
+
+
+
+
+
+
+
--dataSource=reports
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/latest/api/deprecated-list.html b/latest/api/deprecated-list.html
index 7447a1a5..6d06f5f2 100644
--- a/latest/api/deprecated-list.html
+++ b/latest/api/deprecated-list.html
@@ -24,7 +24,7 @@
- Deprecated API (database-migration 4.2.1 API)
+ Deprecated API (database-migration 5.0.0 API)
@@ -34,7 +34,7 @@
diff --git a/latest/api/help-doc.html b/latest/api/help-doc.html
index 7007378f..75082089 100644
--- a/latest/api/help-doc.html
+++ b/latest/api/help-doc.html
@@ -25,7 +25,7 @@
- API Help (database-migration 4.2.1 API)
+ API Help (database-migration 5.0.0 API)
@@ -34,7 +34,7 @@
diff --git a/latest/api/index-all.html b/latest/api/index-all.html
index 174c905e..088f1d5b 100644
--- a/latest/api/index-all.html
+++ b/latest/api/index-all.html
@@ -24,14 +24,14 @@
- Index (database-migration 4.2.1 API)
+ Index (database-migration 5.0.0 API)
diff --git a/latest/api/index.html b/latest/api/index.html
index db6ad509..6dabcf8e 100644
--- a/latest/api/index.html
+++ b/latest/api/index.html
@@ -21,7 +21,7 @@
-Index (database-migration 4.2.1 API)
+Index (database-migration 5.0.0 API)
diff --git a/latest/api/org/grails/plugins/databasemigration/DatabaseMigrationException.html b/latest/api/org/grails/plugins/databasemigration/DatabaseMigrationException.html
index c773c9c5..fab0dad4 100644
--- a/latest/api/org/grails/plugins/databasemigration/DatabaseMigrationException.html
+++ b/latest/api/org/grails/plugins/databasemigration/DatabaseMigrationException.html
@@ -27,7 +27,7 @@
- DatabaseMigrationException (Grails Database Migration Plugin 4.2.1)
+ DatabaseMigrationException (Grails Database Migration Plugin 5.0.0)
@@ -37,7 +37,7 @@
@@ -167,7 +167,7 @@