Issue/Introduction

Use this article to troubleshoot Flyway database migration failures during ZCenter startup or upgrade.

Symptoms

• Database migration fails when ZCenter starts or is upgraded.
• Errors such as checksum mismatch, an error indicating that a table already exists, or a version number conflict occur during migration.

Environment

• Product line: ZVF
• Component: ZCenter
• Version: 5.1.0

Possible causes

• A previously executed migration script was modified, causing a checksum mismatch.
• A table remains after the previous migration was interrupted, and the retry reports that the table already exists.
• The version number of a newly added migration script is not strictly incremental and conflicts with an executed version.

ZCenter uses Flyway to manage database versions. Migration scripts follow the naming convention V{version}__schema.sql.

Resolution

1. Check for a validation failure

• Check: Confirm whether the error contains checksum mismatch.
• Action: Correct the modified script so that it matches the database record.
• Limitation: The flyway_schema_history table can be cleared before running the migration again only in a development environment.

2. Check for a residual table

• Check: Confirm whether the error indicates that the target table already exists.
• Action: Manually clean up the table left behind after the interrupted migration, and then run the migration again.

3. Check the migration script version number

• Check: Confirm whether the version number of the newly added migration script conflicts with an executed version.
• Action: Ensure that the version number of the new script is strictly incremental.

4. Check the Flyway configuration

The relevant Flyway configuration is as follows:

flyway:
  validate-on-migrate: false
  placeholder-replacement: false

Additional information

• During troubleshooting, record the name of the failed migration script, the Flyway error message, and the corresponding record in the flyway_schema_history table.