Refactor LiquibaseCommand API

Description

Currently, liquibase.Liquibase is the primary “porcelain” façade for working with Liquibase (https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain)). However, as Liquibase’s functionality has grown over the years, we have outgrown a single facade class.

A few years ago, we started the liquibase.command package as the replacement for the liquibase.Liquibase class and have been experimenting using it for a few commands. Now is the time to take what we have learned to finalize the design and apply it to all our existing commands.

Backwards Compatibility

Moving the code out of the liquibase.Liquibase facade methods will be a long term process, and should be backwards compatible, even as their implementations are replaced with calls to the new LiquibaseCommand classes.

Compatibility with the existing LiquibaseCommand classes specifically will be tracked in #1752

Requirements / Changes

NOTE: This section will evolve as we do the actual implementation and see the actual API changes in action. Follow along with the PR for the full details.

• LiquibaseCommands can be grouped by zero or more nested parent names
• LiquibaseCommand objects are pluggable by command group + name (e.g. liquibase hub registerChangelog) – in this example hub is a command group.
  • This is a new capability, however, it will only be testable when a future requirement is identified to create a new group.
• LiquibaseCommands follow a “pipeline” structure, where they are additive in logic/arguments rather than replacing.
• Add a CommandScope for managing a command including configuration and input/output
• Logic to execute a command will be moved from LiquibaseCommand to CommandScope
• LiquibaseCommand instances provide metadata of name, description, available parameters, required parameters, etc. which can be used to populate CLI etc. help.
• LiquibaseCommand parameters are exposed as CommandArgumentDefinitions for type-safe get/set logic. Similar to the updated LiquibaseConfiguration style
• Unconfigured LiquibaseCommand parameters will be set with values the LiquibaseConfiguration system as part of the execute() function

Acceptance Criteria

• Ability to define commands with new APIs
• API changes are reviewed and support what we need in the short-term and should not need breaking changes in the future
• API is well javadoc documented and unit tested
• Existing CLI/Maven/etc. user functionality works as before

[nvoxland]

We had an internal code review meeting to discuss the changes #1708 and we were happy with that direction.

The “hook”/pipeline style turned out to not add unneeded complexity, keeps the programmatic interactions cleaner/safer, and allows for some useful functionality such as cross-cutting logic.

I’ll update the description of this ticket to not have questions on the pipeline vs. replace, and the next steps wrapping up of #1708 and then moving on to converting code to use it.

[sync-by-unito[bot]]

➤ Erzsebet Carmean commented:

Not flagged for UAT; moving to ready to merge.