Merge pull request #600 from vnandwana/flyway

Switch to Flyway Command-Line for Migrations
killbill · Feb 11, 2025 · 6e40cdf · 6e40cdf
2 parents 26e09d6 + eb2a318
commit 6e40cdf
Show file tree

Hide file tree

Showing 2 changed files with 109 additions and 49 deletions.
diff --git a/userguide/database-migration/includes/how-to-upgrade-plugin-database.adoc b/userguide/database-migration/includes/how-to-upgrade-plugin-database.adoc
@@ -25,30 +25,36 @@ This command creates a temporary folder with the migration SQL statements and di
 
 === Step 2 - Execute the migrations
 
-The migrations can be executed either manually or via https://flywaydb.org/[Flyway].
+The migrations can be executed either manually or using the https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html[Flyway command-line tool].
 
 ==== Executing migrations manually
 
 Execute the SQL scripts obtained above directly on your database.
 
-==== Executing migrations via the Kill Bill Flywar Jar in Dev environments
+==== Executing migrations via the Flyway Command-Line Tool
 
-We publish a https://repo1.maven.org/maven2/org/kill-bill/billing/killbill-util/0.24.4/killbill-util-0.24.4-flyway.jar[killbill-flyway.jar] jar which is a wrapper around the Flyway utility and can be used to execute the migrations. In order to execute the migrations via this jar, you can do the following:
+Migrations can also be executed using the Flyway command-line tool.
 
-1. If Flyway is being used the first time, run the `baseline` command to create the `schema_history` table.
+1. *Install Flyway Command-Line Tool:*
+
+Follow the installation guide here: https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html[Flyway CLI Installation].
+
+2. *Run the Baseline Command (First-Time Use Only):*
+
+If Flyway is being used the first time, run the `baseline` command to create the `flyway_schema_history` table.
 +
 *Command*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -table=<plugin_name>_schema_history baseline
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=<db_user> -password=<db_password> -table=<plugin_name>_schema_history baseline
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -table=analytics_schema_history baseline
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -table=analytics_schema_history baseline
 ----
 
 +
@@ -58,21 +64,22 @@ java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=ro
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> -table=<plugin_name>_schema_history migrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> -table=<plugin_name>_schema_history migrate
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill  -locations=filesystem:C:/var/migrations -table=analytics_schema_history migrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -locations=filesystem:C:/var/migrations -table=analytics_schema_history migrate
 ----
 
-==== Executing migrations via the Kill Bill Flywar Jar in Prod environments
+
+==== Additional Notes for Production Environments
 
 In production environments, database access is often restricted and developers don’t necessarily have rights to execute DDL commands (i.e. CREATE, ALTER, DROP, etc. statements). In such cases, migrations can be executed as follows:
 
-1. Create the  `schema_history` table manually by running the following SQL statements:
+1. Create the  `<plugin_name>_schema_history` table manually by running the following SQL statements:
 +
 [source, sql]
 ----
@@ -96,30 +103,22 @@ insert into <plugin_name>_schema_history (installed_rank, version, description,
 +
 Ensure that you replace `<plugin_name>` with the name of a plugin like `analytics`.
 +
-2. Run the `dryRunMigrate` command. This simply lists the DDL statements required for the database upgrade but does not actually run them.
+2. *Run a Dry Run (if needed for review before applying migrations):*
+
+Flyway CLI does not support dryRun directly, but you can use `-outputType=json` to review pending migrations:
 +
 *Command*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> -table=<plugin_name>_schema_history dryRunMigrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -table=<plugin_name>_schema_history info -outputType=json
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -locations=filesystem:C:/var/migrations -table=analytics_schema_history dryRunMigrate
-----
-
-
-==== Executing migrations via the Flyway commandline tool
-
-The migrations can also be executed via the https://documentation.red-gate.com/fd/command-line-184127404.html[Flyway commandline tool] as follows:
-
-[source, bash]
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=password -locations=filesystem:C:/var/migrations-table=analytics_schema_history info -outputType=json
 ----
-flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -table=<plugin_name>_schema_history baseline # first time only
 
-flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> -table=<plugin_name>_schema_history migrate
-----
+This will list pending migrations without applying them.
diff --git a/userguide/database-migration/includes/how-to-upgrade-the-killbill-database.adoc b/userguide/database-migration/includes/how-to-upgrade-the-killbill-database.adoc
@@ -25,30 +25,36 @@ This command creates a temporary folder with the migration SQL statements and di
 
 === Step 2 - Execute the migrations
 
-The migrations can be executed either manually or via https://flywaydb.org/[Flyway].
+The migrations can be executed either manually or using the https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html[Flyway command-line tool].
 
 ==== Executing migrations manually
 
-Execute the SQL scripts obtained above directly in database.
+Execute the SQL scripts obtained in Step 1 directly in the database.
 
-==== Executing migrations via the Kill Bill Flywar Jar in Dev environments
+==== Executing migrations via the Flyway Command-Line Tool
 
-We publish a https://repo1.maven.org/maven2/org/kill-bill/billing/killbill-util/0.24.4/killbill-util-0.24.4-flyway.jar[killbill-flyway.jar] jar which is a wrapper around the Flyway utility and can be used to execute the migrations. In order to execute the migrations via this jar, you can do the following:
+Migrations can also be executed using the Flyway command-line tool.
 
-1. If Flyway is being used the first time, run the `baseline` command to create the `schema_history` table.
+1. *Install Flyway Command-Line Tool:*
+
+Follow the installation guide here: https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html[Flyway CLI Installation].
+
+2. *Run the Baseline Command (First-Time Use Only):*
+
+If Flyway is being used the first time, run the `baseline` command to create the `flyway_schema_history` table.
 +
 *Command*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> baseline
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=<db_user> -password=<db_password> baseline
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill baseline
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill baseline
 ----
 
 +
@@ -58,25 +64,25 @@ java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=ro
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> migrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> migrate
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -locations=filesystem:C:/var/migrations migrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=killbill -locations=filesystem:C:/var/migrations migrate
 ----
 
-==== Executing migrations via the Kill Bill Flywar Jar in Prod environments
+==== Additional Notes for Production Environments
 
 In production environments, database access is often restricted and developers don’t necessarily have rights to execute DDL commands (i.e. CREATE, ALTER, DROP, etc. statements). In such cases, migrations can be executed as follows:
 
-1. Create the  `schema_history` table manually by running the following SQL statements:
+1. *Create the  `flyway_schema_history` table manually:*
 +
 [source, sql]
 ----
-CREATE TABLE `schema_history` (
+CREATE TABLE `flyway_schema_history` (
   `installed_rank` int(11) NOT NULL,
   `version` varchar(50) DEFAULT NULL,
   `description` varchar(200) NOT NULL,
@@ -88,36 +94,91 @@ CREATE TABLE `schema_history` (
   `execution_time` int(11) NOT NULL,
   `success` tinyint(1) NOT NULL,
   PRIMARY KEY (`installed_rank`),
-  KEY `schema_history_s_idx` (`success`)
+  KEY `flyway_schema_history_s_idx` (`success`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
 
-insert into schema_history (installed_rank, version, description, type, script, installed_by, installed_on, execution_time, success) VALUES (1, 1, '<< Flyway Baseline >>', 'BASELINE', '<< Flyway Baseline >>', 'admin', NOW(), 0, 1);
+insert into flyway_schema_history (installed_rank, version, description, type, script, installed_by, installed_on, execution_time, success) VALUES (1, 1, '<< Flyway Baseline >>', 'BASELINE', '<< Flyway Baseline >>', 'admin', NOW(), 0, 1);
 ----
 +
-2. Run the `dryRunMigrate` command. This simply lists the DDL statements required for the database upgrade but does not actually run them.
+2. *Run a Dry Run (if needed for review before applying migrations):*
+
+Flyway CLI does not support dryRun directly, but you can use `-outputType=json` to review pending migrations:
 +
 *Command*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> dryRunMigrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> info -outputType=json
 ----
 +
 *Example*
 +
 [source, bash]
 ----
-java -jar killbill-flyway.jar -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=password -locations=filesystem:C:/var/migrations dryRunMigrate
+flyway -url=jdbc:mysql://127.0.0.1:3306/killbill -user=root -password=password -locations=filesystem:C:/var/migrations info -outputType=json
 ----
 
-
-==== Executing migrations via the Flyway commandline tool
-
-The migrations can also be executed via the https://documentation.red-gate.com/fd/command-line-184127404.html[Flyway commandline tool] as follows:
+This will generate a JSON output similar to the following, which includes details such as the migration version, description, and the file path containing the SQL queries that will be executed:
 
 [source, bash]
 ----
-flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> baseline # first time only
-
-flyway -url=jdbc:mysql://127.0.0.1:3306/<db_name> -user=<db_user> -password=<db_password> -locations=filesystem:<migrations_path> migrate
-----
+{
+"schemaVersion": "20221118152343",
+"schemaName": "",
+"migrations": [
+{
+"category": "",
+"version": "1",
+"rawVersion": "1",
+"description": "<< Flyway Baseline >>",
+"type": "BASELINE",
+"installedOnUTC": "2025-02-06T05:58:28Z",
+"state": "Baseline",
+"undoable": "No",
+"filepath": "",
+"undoFilepath": "",
+"installedBy": "root",
+"executionTime": 0
+},
+{
+"category": "Versioned",
+"version": "20220208000000",
+"rawVersion": "20220208000000",
+"description": "change usage and catalog attrs type",
+"type": "SQL",
+"installedOnUTC": "2025-02-07T07:29:38Z",
+"state": "Success",
+"undoable": "No",
+"filepath": "/tmp/d20250211-43349-n5ijvx/V20220208000000__change_usage_and_catalog_attrs_type.sql",
+"undoFilepath": "",
+"installedBy": "root",
+"executionTime": 117
+},
+{
+"category": "Versioned",
+"version": "2022070713524522",
+"rawVersion": "2022070713524522",
+"description": "record date time",
+"type": "SQL",
+"installedOnUTC": "",
+"state": "Pending",
+"undoable": "No",
+"filepath": "/tmp/d20250211-43349-n5ijvx/V2022070713524522__record_date_time.sql",
+"undoFilepath": "",
+"installedBy": "",
+"executionTime": 0
+}
+],
+"flywayVersion": "9.22.3",
+"database": "test",
+"allSchemasEmpty": false,
+"timestamp": "2025-02-11T17:58:06.028141481",
+"operation": "info",
+"exception": null,
+"licenseFailed": false,
+"jsonReport": "/home/killbill/Downloads/flyway-commandline-9.22.3-linux-x64/flyway-9.22.3/report.json",
+"htmlReport": "/home/killbill/Downloads/flyway-commandline-9.22.3-linux-x64/flyway-9.22.3/report.html"
+}
+----
+
+This helps in reviewing the changes before executing them.