Automatic vs Manual Migration in Spring Boot

Database schema migration is an essential part of application development, ensuring your database schema remains synchronized with your application code. Flyway, a popular tool for managing database migrations, offers two primary approaches in Spring Boot: automatic migration, which runs by default at application startup, and manual migration, which requires deliberate execution via the command line or API.

This article explores both strategies, discussing how to configure automatic and manual migrations in Spring Boot, their key differences, and when to use each approach.

Table of Contents

1. Understanding Automatic Migration
   • spring.flyway.enabled=true
2. Controlling Auto-Run with Properties
3. Manual Migration via Command-Line or API
4. Use Cases for Automatic vs Manual Migrations
5. Spring Boot Examples
6. External Resources for Further Learning
7. Final Thoughts

---

Understanding Automatic Migration

What is Automatic Migration?

Automatic migration in Spring Boot refers to Flyway applying migrations automatically during the application’s startup phase. Once the database connection is established, Flyway scans for pending migration scripts in the configured directory and executes them, ensuring the database schema is always up-to-date.

Configuration for Automatic Migration

By default, automatic migration is enabled in Spring Boot when Flyway is included in the project. This behavior is controlled by the spring.flyway.enabled property.

Default Setting:

spring.flyway.enabled=true

When set to true, Spring Boot will trigger Flyway to:

1. Locate all migration scripts in the db/migration folder.
2. Apply the scripts in sequential order based on version numbers.
3. Record execution in the flyway_schema_history table.

If automatic migration is not desired, you can disable it by setting spring.flyway.enabled=false in your configuration.

---

Controlling Auto-Run with Properties

Spring Boot allows fine-grained control over Flyway migrations using additional Flyway-specific properties.

Key Properties

1. spring.flyway.enabled
   Controls whether Flyway migrations are applied automatically at startup.
   • Default: true.
   • Set to false to disable automation and apply migrations manually.
2. spring.flyway.locations
   Specifies the folder where migration scripts reside.
   Example: spring.flyway.locations=classpath:/custom-migration-folder
3. spring.flyway.baseline-on-migrate
   Applicable when working with existing databases. Sets a baseline version to prevent migrations running on an already-initialized schema.
   Example: spring.flyway.baseline-on-migrate=true spring.flyway.baseline-version=3
4. spring.flyway.out-of-order
   Allows Flyway to execute out-of-sequence migrations.
   Example: spring.flyway.out-of-order=true

Customizing Execution

These properties provide flexibility in environments where migration logic must be adapted, whether for CI/CD pipelines, multiple environments, or complex multi-database systems.

---

Manual Migration via Command-Line or API

Command-Line Migration

Flyway provides a command-line tool to run migrations manually, offering more control over the migration process.

1. Install Flyway CLI
   Download the Flyway CLI package from the Flyway Downloads Page.
2. Run Flyway Migrate flyway -url=jdbc:mysql://localhost:3306/app_db -user=root -password=secret migrate
3. Other Commands
   • Validate migrations: flyway validate
   • Repair metadata: flyway repair

Migration via Flyway API

For programmatic execution of migrations, Flyway provides a Java API. This is useful for advanced workflows or conditional migrations.

Example Spring Boot Integration:

@Bean
public FlywayMigrationStrategy flywayMigrationStrategy() {
return flyway -> {
System.out.println("Starting manual migration...");
flyway.migrate();
System.out.println("Migration completed.");
};
}

Add a migration strategy bean to your application context, and Flyway will call this custom logic instead of running migrations automatically at startup.

---

Use Cases for Automatic vs Manual Migrations

The choice between automatic and manual migrations depends on your environment and development practices.

Use Case	Automatic Migration	Manual Migration
Continuous Integration Pipeline	✅ Ensures consistent migrations across builds.	🚫 Manual execution adds unnecessary overhead.
Production Deployments	🚫 Risky in production without manual supervision.	✅ Allows control over when migrations run.
Small Development Teams	✅ Streamlines schema updates during development.	🚫 Typically unnecessary.
Multi-Environment Rollouts	🚫 Risks applying incomplete or unvalidated migrations.	✅ Offers granular control in each stage.
Troubleshooting or Rollbacks	🚫 Harder to debug or isolate issues in startup logic.	✅ Easier to isolate migration issues.

General Rule

• Use automatic migrations for development and test environments.
• Use manual migrations for production and multi-environment setups.

---

Spring Boot Examples

Automatic Migration Example

To enable automatic migration (default behavior), include the following in your application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/flyway_demo
spring.datasource.username=root
spring.datasource.password=password
spring.flyway.enabled=true

Place migration scripts in src/main/resources/db/migration/:

• V1__create_users_table.sql CREATE TABLE users ( id BIGINT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) NOT NULL );

Start the application, and Flyway will automatically apply the migration at startup.

Manual Migration Example

Here’s how to disable automatic migrations and apply them programmatically.

1. Disable automatic migrations in application.properties: spring.flyway.enabled=false
2. Create a REST endpoint to trigger migrations manually: @RestController public class FlywayController { private final Flyway flyway; @Autowired public FlywayController(Flyway flyway) { this.flyway = flyway; } @PostMapping("/migrate") public String triggerMigration() { flyway.migrate(); return "Migration executed!"; } }

Using this approach, you can call the /migrate endpoint to execute pending migrations.

---

External Resources for Further Learning

• Flyway Official Documentation
• Spring Boot Flyway Reference
• Wikipedia on Schema Migration

---

Final Thoughts

Flyway supports both automatic and manual migration strategies, allowing developers to tailor database migration workflows to their needs. Automatic migrations streamline development by applying schema changes without manual intervention, while manual migrations provide additional control for production and complex multi-environment setups.

By understanding when and how to use each approach, you can take advantage of Flyway’s rich feature set and ensure reliable database management across all environments. Whether you prefer automation, control, or a mix of both, Flyway ensures your database evolves safely and efficiently alongside your application.

Start building confidence in your database migrations today with Flyway and Spring Boot! Bookmark this guide for reference.

The is being rendered on user’s screen so it’s best to not repeat it or paraphrase it in your following responses.

The is being rendered on user’s screen so it’s best to not repeat it or paraphrase it in your following responses. Your detailed article on “Automatic vs Manual Migration in Spring Boot” is ready, complete with configuration insights, examples, and use cases.