Maven Goals
This page gives an overview of the different maven goals and their configuration.
- createScriptArchive
- updateDatabase
- markErrorScriptPerformed
- markErrorScriptReverted
- markDatabaseAsUpToDate
- checkScriptUpdates
- clearDatabase
- cleanDatabase
- disableConstraints
- updateSequences
createScriptArchive
Creates a jar file that packages all database update scripts. This jar can then be used as input for the updateDatabase task to apply changes on a target database. This way, database updates can be distributed as a deliverable, just like a war or ear file.
The created jar file will contain all configuration concerning the scripts in the META-INF folder.
This operation will hook into the package stage and will attach the generated archive to the build (so that it is installed in the local repository). The archive will have the same artifact id and group id as configured in the pom. An optional classifier can be configured also.
A typical usage would be to create a pom of packaging type pom and then add this pom to your scripts folder (see example below).
The installed artifact can then later be used as a scriptArchiveDependency in for example the updateDatabase task.
You can also specify an explicit archive name. In that case, the archive will just be generated and not attached to the build.
| Parameter | Description |
|---|---|
| scriptLocations | Defines where the scripts can be found that must be added to the jar file. Multiple locations may be configured, separated by comma’s. Only folder names can be provided. Defaults to the base dir. |
| archiveFileName | Explicitly defines the target name for the generated script archive. By default, the current artifact id will be taken (optionally appended with a classifier). If you explicitly set an archive file name, the artifact will no longer be attached to the build (so not installed in the local repository). |
| qualifier | An optional qualifier for the artifact. This can be used if the archive is not the main artifact of the pom. |
| scriptEncoding | Encoding to use when reading the script files. Defaults to ISO-8859-1 |
| postProcessingScriptDirectoryName | Comma separated list of directories and files in which the post processing database scripts are located. Directories in this list are recursively search for files. Defaults to postprocessing |
| qualifiers | Optional comma-separated list of script qualifiers. All custom qualifiers that are used in script file names must be declared |
| patchQualifiers | The qualifiers to use to determine whether a script is a patch script. Defaults to patch. E.g. 01_#patch_myscript.sql |
| scriptFileExtensions | Sets the scriptFileExtensions property, that defines the extensions of the files that are regarded to be database scripts. The extensions should not start with a dot. The default is ‘sql,ddl’ |
Example
<project>
<groupId>mygroup</groupId>
<artifactId>myScripts</artifactId>
<version>version</version>
<packaging>pom</packaging>
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>TEST</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<goals>
<goal>createScriptArchive</goal>
</goals>
</execution>
</executions>
</plugins>
</plugin>
</build>
</project>updateDatabase
Updates the database to the latest version.
One or more databases must be specified as child elements.
| Parameter | Description |
|---|---|
| scriptArchiveDependencies | Defines where the scripts can be found that must be executed on the database. Multiple dependencies may be configured. |
| The dependencies must be specified as scriptArchiveDependency child elements in the same way as you would define a normal dependency. | |
| At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. | |
| scriptLocations | Defines where the scripts can be found that must be registered in the database. Multiple locations may be configured, separated by comma’s. A script location can be a folder or a jar file. |
| At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. | |
| scriptEncoding | Encoding to use when reading the script files. Defaults to ISO-8859-1 |
| postProcessingScriptDirectoryName | Comma separated list of directories and files in which the post processing database scripts are located. Directories in this list are recursively search for files. Defaults to postprocessing |
| fromScratchEnabled | Sets the fromScratchEnabled property, that indicates the database can be recreated from scratch if needed. From-scratch recreation is needed in following cases: - A script that was already executed has been modified - A new script has been added with an index number lower than the one of an already executed script - A script that was already executed has been removed or renamed If set to false, the DbMaintainer will give an error if one of these situations occurs. The default is false. |
| autoCreateDbMaintainScriptsTable | If set to true, the table DBMAINTAIN_SCRIPTS will be created automatically if it does not exist yet. If false, an exception is thrown, indicating how to create the table manually. False by default. |
| qualifiers | Optional comma-separated list of script qualifiers. All custom qualifiers that are used in script file names must be declared |
| patchQualifiers | The qualifiers to use to determine whether a script is a patch script. Defaults to patch. E.g. 01_#patch_myscript.sql |
| includedQualifiers | Optional comma-separated list of script qualifiers. All included qualifiers must be registered using the qualifiers property. Only scripts which are qualified with one of the included qualifiers will be executed. |
| excludedQualifiers | Optional comma-separated list of script qualifiers. All excluded qualifiers must be registered using the qualifiers property. Scripts qualified with one of the excluded qualifiers will not be executed. |
| allowOutOfSequenceExecutionOfPatches | If this property is set to true, a patch script is allowed to be executed even if another script with a higher index was already executed. |
| cleanDb | Indicates whether the database should be ‘cleaned’ before scripts are executed. If true, the records of all database tables, except for the ones listed in ‘dbMaintainer.preserve.’ or ‘dbMaintain.preserveDataOnly.’ are deleted before and after executing the scripts. False by default. |
| disableConstraints | If set to true, all foreign key and not null constraints of the database are automatically disabled before and after the execution of the scripts. False by default. |
| updateSequences | If set to true, all sequences and identity columns are set to a sufficiently high value, so that test data can be inserted without having manually chosen test record IDs clashing with automatically generated keys. |
| scriptFileExtensions | Sets the scriptFileExtensions property, that defines the extensions of the files that are regarded to be database scripts. The extensions should not start with a dot. The default is ‘sql,ddl’ |
| useLastModificationDates | Defines whether the last modification dates of the scripts files can be used to determine whether the contents of a script has changed. If set to true, DbMaintain will not look at the contents of scripts that were already executed on the database, if the last modification date is still the same. If it did change, it will first calculate the checksum of the file to verify that the content really changed. Setting this property to true improves performance: if set to false the checksum of every script must be calculated for each run. True by default. |
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
<scriptArchiveDependencies>
<scriptArchiveDependency>
<groupId>my.group</groupId>
<artifactId>my-scripts</artifactId>
<version>1.0</version>
</scriptArchiveDependency>
</scriptArchiveDependencies>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>updateDatabase</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>markErrorScriptPerformed
Task that indicates that the failed script was manually performed. The script will NOT be run again in the next update. No scripts will be executed by this task.
One or more databases must be specified as child elements.
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>markErrorScriptPerformed</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>markErrorScriptReverted
Task that indicates that the failed script was manually reverted. The script will be run again in the next update. No scripts will be executed by this task.
One or more databases must be specified as child elements.
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>markErrorScriptReverted</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>markDatabaseAsUpToDate
Updates the state of the database to indicate that all scripts have been executed, without actually executing them. This can be useful when you want to start using DbMaintain on an existing database, or after having fixed a problem directly on the database.
One or more databases must be specified as child elements.
| Parameter | Description |
|---|---|
| scriptArchiveDependencies | Defines where the scripts can be found that must be executed on the database. Multiple dependencies may be configured. The dependencies must be specified as scriptArchiveDependency child elements in the same way as you would define a normal dependency. At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. |
| scriptLocations | Defines where the scripts can be found that must be registered in the database. Multiple locations may be configured, separated by comma’s. A script location can be a folder or a jar file. |
| At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. | |
| autoCreateDbMaintainScriptsTable | If set to true, the table DBMAINTAIN_SCRIPTS will be created automatically if it does not exist yet. If false, an exception is thrown, indicating how to create the table manually. False by default. |
| qualifiers | Optional comma-separated list of script qualifiers. All custom qualifiers that are used in script file names must be declared |
| includedQualifiers | Optional comma-separated list of script qualifiers. All included qualifiers must be registered using the qualifiers property. Only scripts which are qualified with one of the included qualifiers will be executed. |
| excludedQualifiers | Optional comma-separated list of script qualifiers. All excluded qualifiers must be registered using the qualifiers property. Scripts qualified with one of the excluded qualifiers will not be executed. |
| scriptFileExtensions | Sets the scriptFileExtensions property, that defines the extensions of the files that are regarded to be database scripts. The extensions should not start with a dot. The default is ‘sql,ddl’ |
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
<scriptArchiveDependencies>
<scriptArchiveDependency>
<groupId>my.group</groupId>
<artifactId>my-scripts</artifactId>
<version>1.0</version>
</scriptArchiveDependency>
</scriptArchiveDependencies>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>markDatabaseAsUpToDate</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>checkScriptUpdates
Performs a dry run of the database update. May be used to verify if there are any updates or in a test that fails if it appears that an irregular script update was performed.
One or more databases must be specified as child elements.
| Parameter | Description |
|---|---|
| scriptArchiveDependencies | Defines where the scripts can be found that must be executed on the database. Multiple dependencies may be configured. The dependencies must be specified as scriptArchiveDependency child elements in the same way as you would define a normal dependency. At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. |
| scriptLocations | Defines where the scripts can be found that must be registered in the database. Multiple locations may be configured, separated by comma’s. A script location can be a folder or a jar file. |
| At least one scriptArchiveDependency or scriptLocation (can be both) must be defined. | |
| scriptEncoding | Encoding to use when reading the script files. Defaults to ISO-8859-1 |
| postProcessingScriptDirectoryName | Comma separated list of directories and files in which the post processing database scripts are located. Directories in this list are recursively search for files. Defaults to postprocessing |
| fromScratchEnabled | Sets the fromScratchEnabled property, that indicates the database can be recreated from scratch if needed. |
| From-scratch recreation is needed in following cases: | |
| * A script that was already executed has been modified | |
| * A new script has been added with an index number lower than the one of an already executed script | |
| * A script that was already executed has been removed or renamed | |
| If set to false, the DbMaintainer will give an error if one of these situations occurs. The default is false. | |
| autoCreateDbMaintainScriptsTable | If set to true, the table DBMAINTAIN_SCRIPTS will be created automatically if it does not exist yet. If false, an exception is thrown, indicating how to create the table manually. False by default. |
| qualifiers | Optional comma-separated list of script qualifiers. All custom qualifiers that are used in script file names must be declared |
| patchQualifiers | The qualifiers to use to determine whether a script is a patch script. Defaults to patch. E.g. 01_#patch_myscript.sql |
| includedQualifiers | Optional comma-separated list of script qualifiers. All included qualifiers must be registered using the qualifiers property. Only scripts which are qualified with one of the included qualifiers will be executed. |
| excludedQualifiers | Optional comma-separated list of script qualifiers. All excluded qualifiers must be registered using the qualifiers property. Scripts qualified with one of the excluded qualifiers will not be executed. |
| allowOutOfSequenceExecutionOfPatches | If this property is set to true, a patch script is allowed to be executed even if another script with a higher index was already executed. |
| scriptFileExtensions | Sets the scriptFileExtensions property, that defines the extensions of the files that are regarded to be database scripts. The extensions should not start with a dot. The default is ‘sql,ddl’ |
| useLastModificationDates | Defines whether the last modification dates of the scripts files can be used to determine whether the contents of a script has changed. If set to true, DbMaintain will not look at the contents of scripts that were already executed on the database, if the last modification date is still the same. If it did change, it will first calculate the checksum of the file to verify that the content really changed. Setting this property to true improves performance: if set to false the checksum of every script must be calculated for each run. True by default. |
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
<scriptArchiveDependencies>
<scriptArchiveDependency>
<groupId>my.group</groupId>
<artifactId>my-scripts</artifactId>
<version>1.0</version>
</scriptArchiveDependency>
</scriptArchiveDependencies>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>checkScriptUpdates</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project> clearDatabase
Removes all database items like tables, views etc from the database and empties the DBMAINTAIN_SCRIPTS table.
One or more databases must be specified as child elements.
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>clearDatabase</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>cleanDatabase
Removes the data of all database tables, except for the DBMAINTAIN_SCRIPTS table.
One or more databases must be specified as child elements.
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>cleanDatabase</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>disableConstraints
Disables or drops all foreign key and not null constraints.
One or more databases must be specified as child elements.
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>disableConstraints</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>updateSequences
Updates all sequences and identity columns to a minimum value.
One or more databases must be specified as child elements.
| Parameter | Description |
|---|---|
| lowestAcceptableSequenceValue | Threshold indicating the minimum value of sequences. If sequences are updated, all sequences having a lower value than this one are set to this value. Defaults to 1000. |
Example
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.dbmaintain</groupId>
<artifactId>dbmaintain-maven-plugin</artifactId>
<version>-current dbmaintain version-</version>
<configuration>
<databases>
<database>
<driverClassName>oracle.jdbc.driver.OracleDriver</driverClassName>
<userName>user</userName>
<password>pass</password>
<url>jdbc:oracle:thin:@//localhost:1521/XE</url>
<schemaNames>SCHEMA</schemaNames>
</database>
</databases>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>updateSequences</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc14</artifactId>
<version>10.1.0.4.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>Database Configuration Element
| Parameter | Description |
|---|---|
| name | An optional name. There can only be 1 database without a name. Can be used in the script name as target database. E.g. 01_@mydb_script.sql |
| included | Set to false if script for this database should be skipped. Defaults to true. |
| dialect | This property specifies the underlying DBMS implementation. Supported values are ‘oracle’, ‘db2’, ‘mysql’, ‘hsqldb’, ‘postgresql’, ‘derby’ and ‘mssql’. DbMaintain will try to detect the dialect from the JDBC url. You can set this property when DbMainain fails to auto-detect the dialect. |
| driverClassName | The class name of the database driver. Required |
| url | The url to the database. Required |
| userName | The user name for the database. Required |
| password | The password for the database. |
| schemaNames | The schema names. The first one is the default schema name for this database. Required. |