Managing Hibernate schema migrations during Scalingo rolling updates

The Recommended Strategy

To prevent errors in legacy containers during a rolling update, you must decouple schema migrations from the application startup process and ensure all database changes are backward-compatible. Relying on hibernate.hbm2ddl.auto=update is not recommended for production environments on Scalingo, as it lacks versioning and can cause race conditions or incompatible schema states when multiple versions of the application are active.

1. Implement Versioned Migrations

Replace automatic Hibernate updates with a dedicated migration tool such as Flyway or Liquibase. These tools maintain a schema history table to track which migrations have been applied, ensuring consistency across all containers.

2. Use Backward-Compatible Changes

Because Scalingo's rolling updates keep the old version running until the new version passes health checks, the database must support both versions simultaneously. Follow these rules for schema changes:

• Adding columns: New columns must be nullable or have a default value so the old version can still perform inserts.
• Renaming columns: Do not rename. Add a new column, write to both during a transition period, and remove the old column only after the old version is fully decommissioned.
• Removing columns: Only remove columns in a separate deployment after the new code no longer references them.

3. Sequence Updates via One-Off Containers

Scalingo does not provide a built-in "pre-deploy" hook for database migrations. To sequence updates independently of the application lifecycle, execute your migrations using a one-off container before triggering the rolling update.

Example workflow:

1. Package your migration scripts into your application artifact.
2. Run a one-off command to apply migrations:
   scalingo run "java -jar app.jar --migrate-only" (assuming your app has a migration-only mode).
3. Once the one-off container exits successfully, trigger the deployment of the new application version.

Verification and Safety

To verify the migration before the rolling update proceeds, check the migration history table:

SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 1;

If the latest version matches your current release, it is safe to proceed with the rollout. If you encounter SQLGrammarException or ColumnNotFoundException in the logs of legacy containers during the rollout, it indicates a breaking change was introduced without backward compatibility.

Diagnostic Detail Needed: Are you currently using a custom entrypoint script or a CI/CD pipeline (e.g., GitHub Actions, GitLab CI) to trigger your Scalingo deploys? This determines whether the one-off migration can be fully automated.