CommandLine Help / Usage for Community Editions shows PRO commands and options

[cdavid15]

What version of Flyway are you using?

Flyway Community Edition 5.0.7

Which client are you using? (Command-line, Java API, Maven plugin, Gradle plugin, SBT plugin, ANT tasks)

Commnd-line

What database are you using (type & version)?

N/A

What operating system are you using?

N/A

What did you do?

(Please include the content causing the issue, any relevant configuration settings, and the command you ran)
Familarising myself with v5 i ran the usage command (flyway -?) and was trying out different options when i found out some do not apply to the community edition and are Flyway Pro only but appear in the community edition usage output.

What did you expect to see?

Usage instructions for what is applicable to the open source version only as it makes it crystal clear what is permitted usage. Including it in the usage output suggests these options and commands are available.

C:\> flyway -?
Flyway Community Edition 5.0.7 by Boxfuse

Usage
=====

flyway [options] command

By default, the configuration will be read from conf/flyway.conf.
Options passed from the command-line override the configuration.

Commands
--------
migrate  : Migrates the database
clean    : Drops all objects in the configured schemas
info     : Prints the information about applied, current and pending migrations
validate : Validates the applied migrations against the ones on the classpath
baseline : Baselines an existing database at the baselineVersion
repair   : Repairs the schema history table

Options (Format: -key=value)
-------
driver                       : Fully qualified classname of the JDBC driver
url                          : Jdbc url to use to connect to the database
user                         : User to use to connect to the database
password                     : Password to use to connect to the database
schemas                      : Comma-separated list of the schemas managed by Flyway
table                        : Name of Flyway's schema history table
locations                    : Classpath locations to scan recursively for migrations
resolvers                    : Comma-separated list of custom MigrationResolvers
skipDefaultResolvers         : Skips default resolvers (jdbc, sql and Spring-jdbc)
sqlMigrationPrefix           : File name prefix for versioned SQL migrations
undoSqlMigrationPrefix       : File name prefix for undo SQL migrations
repeatableSqlMigrationPrefix : File name prefix for repeatable SQL migrations
sqlMigrationSeparator        : File name separator for sql migrations
sqlMigrationSuffixes         : Comma-separated list of file name suffixes for sql migrations
mixed                        : Allow mixing transactional and non-transactional statements
encoding                     : Encoding of sql migrations
placeholderReplacement       : Whether placeholders should be replaced
placeholders                 : Placeholders to replace in sql migrations
placeholderPrefix            : Prefix of every placeholder
placeholderSuffix            : Suffix of every placeholder
installedBy                  : Username that will be recorded in the schema history table
target                       : Target version up to which Flyway should use migrations
outOfOrder                   : Allows migrations to be run "out of order"
callbacks                    : Comma-separated list of FlywayCallback classes
skipDefaultCallbacks         : Skips default callbacks (sql)
validateOnMigrate            : Validate when running migrate
ignoreMissingMigrations      : Allow missing migrations when validating
ignoreFutureMigrations       : Allow future migrations when validating
cleanOnValidationError       : Automatically clean on a validation error
cleanDisabled                : Whether to disable clean
baselineVersion              : Version to tag schema with when executing baseline
baselineDescription          : Description to tag schema with when executing baseline
baselineOnMigrate            : Baseline on migrate against uninitialized non-empty schema
configFiles                  : Comma-separated list of config files to use
configFileEncoding           : Encoding to use when loading the config files
jarDirs                      : Comma-separated list of dirs for Jdbc drivers & Java migrations
dryRunOutput                 : File where to output the SQL statements of a migration dry run
errorHandlers                : Comma-separated list of handlers for errors and warnings

Flags
-----
-X : Print debug output
-q : Suppress all output, except for errors and warnings
-n : Suppress prompting for a user and password
-v : Print the Flyway version and exit
-? : Print this usage info and exit

Example
-------
flyway -user=myuser -password=s3cr3t -url=jdbc:h2:mem -placeholders.abc=def migrate

More info at https://flywaydb.org/documentation/commandline

What did you see instead?

Usage instructions indicating the undo command can be used along with the following options being applicable but are in fact not:

• undoSqlMigrationPrefix
• errorHandlers
• dryRunOutput

C:\> flyway -?
Flyway Community Edition 5.0.7 by Boxfuse

Usage
=====

flyway [options] command

By default, the configuration will be read from conf/flyway.conf.
Options passed from the command-line override the configuration.

Commands
--------
migrate  : Migrates the database
clean    : Drops all objects in the configured schemas
info     : Prints the information about applied, current and pending migrations
validate : Validates the applied migrations against the ones on the classpath
undo     : Undoes the most recently applied versioned migration
baseline : Baselines an existing database at the baselineVersion
repair   : Repairs the schema history table

Options (Format: -key=value)
-------
driver                       : Fully qualified classname of the JDBC driver
url                          : Jdbc url to use to connect to the database
user                         : User to use to connect to the database
password                     : Password to use to connect to the database
schemas                      : Comma-separated list of the schemas managed by Flyway
table                        : Name of Flyway's schema history table
locations                    : Classpath locations to scan recursively for migrations
resolvers                    : Comma-separated list of custom MigrationResolvers
skipDefaultResolvers         : Skips default resolvers (jdbc, sql and Spring-jdbc)
sqlMigrationPrefix           : File name prefix for versioned SQL migrations
repeatableSqlMigrationPrefix : File name prefix for repeatable SQL migrations
sqlMigrationSeparator        : File name separator for sql migrations
sqlMigrationSuffixes         : Comma-separated list of file name suffixes for sql migrations
mixed                        : Allow mixing transactional and non-transactional statements
encoding                     : Encoding of sql migrations
placeholderReplacement       : Whether placeholders should be replaced
placeholders                 : Placeholders to replace in sql migrations
placeholderPrefix            : Prefix of every placeholder
placeholderSuffix            : Suffix of every placeholder
installedBy                  : Username that will be recorded in the schema history table
target                       : Target version up to which Flyway should use migrations
outOfOrder                   : Allows migrations to be run "out of order"
callbacks                    : Comma-separated list of FlywayCallback classes
skipDefaultCallbacks         : Skips default callbacks (sql)
validateOnMigrate            : Validate when running migrate
ignoreMissingMigrations      : Allow missing migrations when validating
ignoreFutureMigrations       : Allow future migrations when validating
cleanOnValidationError       : Automatically clean on a validation error
cleanDisabled                : Whether to disable clean
baselineVersion              : Version to tag schema with when executing baseline
baselineDescription          : Description to tag schema with when executing baseline
baselineOnMigrate            : Baseline on migrate against uninitialized non-empty schema
configFiles                  : Comma-separated list of config files to use
configFileEncoding           : Encoding to use when loading the config files
jarDirs                      : Comma-separated list of dirs for Jdbc drivers & Java migrations

Flags
-----
-X : Print debug output
-q : Suppress all output, except for errors and warnings
-n : Suppress prompting for a user and password
-v : Print the Flyway version and exit
-? : Print this usage info and exit

Example
-------
flyway -user=myuser -password=s3cr3t -url=jdbc:h2:mem -placeholders.abc=def migrate

More info at https://flywaydb.org/documentation/commandline

[axelfontaine]

I certainly agree we could do a better job at making the distinction clearer. I am currently leaning towards adding [pro] as a prefix to the description of these features. This would be consistent with the style used in the docs on the website.

[cdavid15]

I can understand the thought process aligning with the website but I personally think it would be better to strip out the additional options from the community edition.

The website documentation covers all 3 products and that's very clear but if have chose to use the community edition library it would cleaner to only have the features available to use in the usage for that library. We are talking about documentation in the runtime library and users would know what version they have. If maybe understand if the community edition has these features disabled that could be activated by a key it's separate builds with features stripped out so why not strip out the help too?

At the moment there are 4 differences (that I can see) but what stopping that being 10, or 20 differences in future versions which would clutter the community edition usage instructions.

Should the community edition only show the community options, the pro shows it's, and enterprise its own (if they differ)?

I'm all for clean, concise and transparency especially when it's documentation and usage.

[axelfontaine]

I opted for the [pro] marker. However your comments have been duly noted and I'll happily revisit this decision should the number of differences increase in the future.