tentackle-sql:migrate

Full name:

org.tentackle:tentackle-sql-maven-plugin:25.20.0.0:migrate

Description:

Generates an SQL script to migrate the database tables according to the model.
Connects to each connectable backend, compares its metadata table by table against the model, and writes the SQL required to bring the database in line, optionally guided by MigrationHints . The script is only generated, never executed.

Attributes:

  • Requires a Maven project to be executed.
  • Executes as an aggregator goal.
  • The goal is thread-safe and supports parallel builds.

Optional Parameters

Name Type Since Description
<alienTables> List<String> - Optional list of table names not belonging to the model.
Could be just simple names, but in fact are regular expressions.
Must not contain the schema name, only the table name!
<asTemplate> boolean - Processes the generated migration file as a FreeMarker template.
The migration is first written to <sqlFileName with dots replaced by dashes>.ftl (e.g. migratemodel-sql.ftl), which is then rendered into the final SQL file and removed. See MigrateTemplateModel for the template variables, most notably migrate.<EntityName>, which is true if that entity's table needs migration.
Default: false
User Property: tentackle.migrateSqlAsTemplate
<backendNames> String - Comma-separated list of backend names.
The following special names are recognized:
  • all: all non-deprecated backends
  • none: does not match any backend
  • deprecated: all deprecated backends

User Property: tentackle.backendNames
<backendProperties> List<FileSet> - The backend property files.
<backends> List<BackendInfoParameter> - Backend configuration via the pom.
Combined with backendNames and backendProperties . For the same backend name, these definitions replace the others.
<bundleDir> File - Optional directory where to create bundle property files.
Contains all attribute- and relation names with their comments.
Useful to copy and paste into the project for auto table config or default editors.
<charset> String - The encoding to read and write files.
Applied JVM-wide, see org.tentackle.maven.AbstractTentackleMojo.determineEncoding() .
Default: ${project.build.sourceEncoding}
<checkBackendSpecificNames> boolean - Check for reserved backend-specific names.
Asserts that column-, schema-, table- and index-names don't conflict with reserved words of the configured backends.
Default: true
<checkModelNames> boolean - Checks the names used in the model via the org.tentackle.model.NameVerifier . Turn this off if you want to skip the name checks (to load legacy models, for example).
Default: true
<checkReservedTables> boolean - Check for reserved table names.
Invokes org.tentackle.sql.metadata.MetaDataUtilities.isReservedTable(java.lang.String) .
Default: true
<dumpAnnotationsAsOptions> String - List of annotations that should be printed as attribute options.
A comma separates multiple annotations.
If the annotation ends with a |, it matches only annotations without parameters.
The special annotation @* matches all annotations and @*| matches all annotations without parameters.

Example: @NotNull|, @NotZero

<dumpAsComment> boolean - Model dump should be dumped as comment blocks (default).
Default: true
<dumpColumnGap> int - Minimum number of spaces between columns in the attribute section (default = 2).
Default: 2
<dumpCompact> boolean - Compact model dump.
Omits implicit configuration in dumped model code.
By default, all configuration keywords are printed for proofreading.
In compact mode, however, only the keywords that are actually required are printed, making it more suitable as input for source code generation.
<dumpDir> File - Optional directory where to dump the model.
Useful for debugging to verify that the model was interpreted correctly or to pretty-print the model source.
<dumpModelIndex> File - Creates an additional file containing the names of the dumped files.
Usually combined with dumpModelSource to create META-INF/MODEL-INDEX.LIST in order to load the model from a jar file.
<dumpModelSource> boolean - Dumps the original model source instead of the parsed entity.
<dumpVariables> boolean - Model dump should include variables (default).
Default: true
<entityAliases> String - The entity aliases.
User Property: tentackle.entityAliases
<failOnUnexpectedTables> boolean - Fails if unexpected tables are found in the database.
Unexpected tables are user tables that are neither in the model nor match the alienTables. If set, the migration script contains DROP TABLE statements for them instead of just listing them as a comment.
Default: false
<filesets> List<FileSet> - Explicit filesets given instead of the model directory.
<generateHeaderComment> boolean - Create a header comment.
Default: true
<jdkToolchain> Map<String,String> - Toolchain for invocation of external tools.
Explicitly specifies the "jdk" toolchain for this plugin only. Overrides the toolchain selected by the maven-toolchain-plugin, if any.

Example:

  <jdkToolchain>
    <version>25</version>
  </jdkToolchain>
To deselect the toolchain configured by the maven-toolchain-plugin:
  <jdkToolchain></jdkToolchain>
<loadModelFromClassPath> boolean - Uses the model found in the resources of the classpath.
Useful to migrate the database tables for dependencies, for example, the Tentackle framework's model.
Requires that the plugin dependencies contain the model resources (see dumpModelIndex and dumpModelSource ).

Notice: for the migrate and validate goals, the model files in the filesets are ignored when this flag is true! If only the Tentackle tables should be migrated, make sure to set checkReservedTables to false.
The document goal loads the classpath model in addition to the local model files.


User Property: tentackle.loadModelFromClassPath
<mapSchemas> boolean - Map schema names to flat table names.
User Property: tentackle.mapSchemas
<minLogLevel> String - The minimum logging java.util.logging.Level to redirect java.util logging to the maven logger.
Any name or value accepted by java.util.logging.Level.parse(java.lang.String) .
Default: WARNING
<modelDefaults> String - The model defaults.
User Property: tentackle.modelDefaults
<modelDir> File - Directory holding the model files to be processed.
Ignored if fileset explicitly given.
Default: ${project.build.directory}/wurbel/model
User Property: tentackle.modelDir
<modelName> String - The model name.
Default: default
User Property: tentackle.modelName
<skip> Boolean - Skips processing.
If not set, defaults to true if packaging is "pom" and the execution is recursive (see org.tentackle.maven.AbstractTentackleMojo.isSkippedByDefault() ).
<split> boolean - Splits the generated migration into one file per migrated table.
This is especially useful if the migrations are processed any further, for example, by shell scripts.

Each migrated table gets its own sub-folder of the backend's SQL directory, numbered from 1 with leading zeros as necessary to keep the folder names in numeric order. The foreign key migrations follow the tables in a folder of their own (_foreign_keys.sql), then the after all hint (_after_all.sql) and finally the always after hint (_always_after.sql). The always before and before all hints go into folder zero, i.e. 0, 00, etc.

The main migration file just contains the statistics, the unexpected tables, the dropped tables and the warnings.

<sqlDir> File - Directory holding the generated SQL scripts, one sub-directory per backend.
Default: ${project.build.directory}/sql
User Property: tentackle.sqlDir
<sqlFileName> String - The name of the created sql file.
Default: migratemodel.sql
User Property: tentackle.migrateSqlFile
<useDropIfExists> boolean - Use IF EXISTS for drop index, constraint, and column if the backend supports it.
If not supported, a warning will be logged.
Applies to the migrate and validate goals only.
<validate> boolean - Fails if the model differs from the database metadata.
Useful to validate that no migrations are necessary.

Same as the validate goal. Notice that there is no user property for this parameter, i.e. -Dvalidate=true has no effect: use the validate goal instead.

<verbosity> String - The verbosity.
One of "default", "info" or "debug". Other values are treated as "default".
If not set, debug is turned on by Maven's global debug flag (see command line switch -X).
Default: ${tentackle.verbosity}

Parameter Details

<alienTables>

Optional list of table names not belonging to the model.
Could be just simple names, but in fact are regular expressions.
Must not contain the schema name, only the table name!
  • Type: java.util.List<java.lang.String>
  • Required: No

<asTemplate>

Processes the generated migration file as a FreeMarker template.
The migration is first written to <sqlFileName with dots replaced by dashes>.ftl (e.g. migratemodel-sql.ftl), which is then rendered into the final SQL file and removed. See MigrateTemplateModel for the template variables, most notably migrate.<EntityName>, which is true if that entity's table needs migration.
  • Type: boolean
  • Required: No
  • User Property: tentackle.migrateSqlAsTemplate
  • Default: false

<backendNames>

Comma-separated list of backend names.
The following special names are recognized:
  • all: all non-deprecated backends
  • none: does not match any backend
  • deprecated: all deprecated backends
  • Type: java.lang.String
  • Required: No
  • User Property: tentackle.backendNames

<backendProperties>

The backend property files.
  • Type: java.util.List<org.apache.maven.shared.model.fileset.FileSet>
  • Required: No

<backends>

Backend configuration via the pom.
Combined with backendNames and backendProperties . For the same backend name, these definitions replace the others.
  • Type: java.util.List<org.tentackle.maven.plugin.sql.BackendInfoParameter>
  • Required: No

<bundleDir>

Optional directory where to create bundle property files.
Contains all attribute- and relation names with their comments.
Useful to copy and paste into the project for auto table config or default editors.
  • Type: java.io.File
  • Required: No

<charset>

The encoding to read and write files.
Applied JVM-wide, see org.tentackle.maven.AbstractTentackleMojo.determineEncoding() .
  • Type: java.lang.String
  • Required: No
  • Default: ${project.build.sourceEncoding}

<checkBackendSpecificNames>

Check for reserved backend-specific names.
Asserts that column-, schema-, table- and index-names don't conflict with reserved words of the configured backends.
  • Type: boolean
  • Required: No
  • Default: true

<checkModelNames>

Checks the names used in the model via the org.tentackle.model.NameVerifier . Turn this off if you want to skip the name checks (to load legacy models, for example).
  • Type: boolean
  • Required: No
  • Default: true

<checkReservedTables>

Check for reserved table names.
Invokes org.tentackle.sql.metadata.MetaDataUtilities.isReservedTable(java.lang.String) .
  • Type: boolean
  • Required: No
  • Default: true

<dumpAnnotationsAsOptions>

List of annotations that should be printed as attribute options.
A comma separates multiple annotations.
If the annotation ends with a |, it matches only annotations without parameters.
The special annotation @* matches all annotations and @*| matches all annotations without parameters.

Example: @NotNull|, @NotZero

  • Type: java.lang.String
  • Required: No

<dumpAsComment>

Model dump should be dumped as comment blocks (default).
  • Type: boolean
  • Required: No
  • Default: true

<dumpColumnGap>

Minimum number of spaces between columns in the attribute section (default = 2).
  • Type: int
  • Required: No
  • Default: 2

<dumpCompact>

Compact model dump.
Omits implicit configuration in dumped model code.
By default, all configuration keywords are printed for proofreading.
In compact mode, however, only the keywords that are actually required are printed, making it more suitable as input for source code generation.
  • Type: boolean
  • Required: No

<dumpDir>

Optional directory where to dump the model.
Useful for debugging to verify that the model was interpreted correctly or to pretty-print the model source.
  • Type: java.io.File
  • Required: No

<dumpModelIndex>

Creates an additional file containing the names of the dumped files.
Usually combined with dumpModelSource to create META-INF/MODEL-INDEX.LIST in order to load the model from a jar file.
  • Type: java.io.File
  • Required: No

<dumpModelSource>

Dumps the original model source instead of the parsed entity.
  • Type: boolean
  • Required: No

<dumpVariables>

Model dump should include variables (default).
  • Type: boolean
  • Required: No
  • Default: true

<entityAliases>

The entity aliases.
  • Type: java.lang.String
  • Required: No
  • User Property: tentackle.entityAliases

<failOnUnexpectedTables>

Fails if unexpected tables are found in the database.
Unexpected tables are user tables that are neither in the model nor match the alienTables. If set, the migration script contains DROP TABLE statements for them instead of just listing them as a comment.
  • Type: boolean
  • Required: No
  • Default: false

<filesets>

Explicit filesets given instead of the model directory.
  • Type: java.util.List<org.apache.maven.shared.model.fileset.FileSet>
  • Required: No

<generateHeaderComment>

Create a header comment.
  • Type: boolean
  • Required: No
  • Default: true

<jdkToolchain>

Toolchain for invocation of external tools.
Explicitly specifies the "jdk" toolchain for this plugin only. Overrides the toolchain selected by the maven-toolchain-plugin, if any.

Example:

  <jdkToolchain>
    <version>25</version>
  </jdkToolchain>
To deselect the toolchain configured by the maven-toolchain-plugin:
  <jdkToolchain></jdkToolchain>
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<loadModelFromClassPath>

Uses the model found in the resources of the classpath.
Useful to migrate the database tables for dependencies, for example, the Tentackle framework's model.
Requires that the plugin dependencies contain the model resources (see dumpModelIndex and dumpModelSource ).

Notice: for the migrate and validate goals, the model files in the filesets are ignored when this flag is true! If only the Tentackle tables should be migrated, make sure to set checkReservedTables to false.
The document goal loads the classpath model in addition to the local model files.

  • Type: boolean
  • Required: No
  • User Property: tentackle.loadModelFromClassPath

<mapSchemas>

Map schema names to flat table names.
  • Type: boolean
  • Required: No
  • User Property: tentackle.mapSchemas

<minLogLevel>

The minimum logging java.util.logging.Level to redirect java.util logging to the maven logger.
Any name or value accepted by java.util.logging.Level.parse(java.lang.String) .
  • Type: java.lang.String
  • Required: No
  • Default: WARNING

<modelDefaults>

The model defaults.
  • Type: java.lang.String
  • Required: No
  • User Property: tentackle.modelDefaults

<modelDir>

Directory holding the model files to be processed.
Ignored if fileset explicitly given.
  • Type: java.io.File
  • Required: No
  • User Property: tentackle.modelDir
  • Default: ${project.build.directory}/wurbel/model

<modelName>

The model name.
  • Type: java.lang.String
  • Required: No
  • User Property: tentackle.modelName
  • Default: default

<skip>

Skips processing.
If not set, defaults to true if packaging is "pom" and the execution is recursive (see org.tentackle.maven.AbstractTentackleMojo.isSkippedByDefault() ).
  • Type: java.lang.Boolean
  • Required: No

<split>

Splits the generated migration into one file per migrated table.
This is especially useful if the migrations are processed any further, for example, by shell scripts.

Each migrated table gets its own sub-folder of the backend's SQL directory, numbered from 1 with leading zeros as necessary to keep the folder names in numeric order. The foreign key migrations follow the tables in a folder of their own (_foreign_keys.sql), then the after all hint (_after_all.sql) and finally the always after hint (_always_after.sql). The always before and before all hints go into folder zero, i.e. 0, 00, etc.

The main migration file just contains the statistics, the unexpected tables, the dropped tables and the warnings.

  • Type: boolean
  • Required: No

<sqlDir>

Directory holding the generated SQL scripts, one sub-directory per backend.
  • Type: java.io.File
  • Required: No
  • User Property: tentackle.sqlDir
  • Default: ${project.build.directory}/sql

<sqlFileName>

The name of the created sql file.
  • Type: java.lang.String
  • Required: No
  • User Property: tentackle.migrateSqlFile
  • Default: migratemodel.sql

<useDropIfExists>

Use IF EXISTS for drop index, constraint, and column if the backend supports it.
If not supported, a warning will be logged.
Applies to the migrate and validate goals only.
  • Type: boolean
  • Required: No

<validate>

Fails if the model differs from the database metadata.
Useful to validate that no migrations are necessary.

Same as the validate goal. Notice that there is no user property for this parameter, i.e. -Dvalidate=true has no effect: use the validate goal instead.

  • Type: boolean
  • Required: No

<verbosity>

The verbosity.
One of "default", "info" or "debug". Other values are treated as "default".
If not set, debug is turned on by Maven's global debug flag (see command line switch -X).
  • Type: java.lang.String
  • Required: No
  • Default: ${tentackle.verbosity}