Liquibase Database Migration in Kubernetes
Liquibase database migration is essential for managing databases in a microservices environment, especially when using Kubernetes (k8s). Improper migration management can lead to locked databases and failed deployments. In this article, we explore a proven approach using Init Containers to run migrations reliably while maintaining production stability.
Why Database Migration Can Fail in Kubernetes
Kubernetes may terminate pods if a deployment takes too long or fails a startup probe. Consequently, ongoing Liquibase database migration processes can be interrupted, leaving the database locked. Liquibase uses the DATABASECHANGELOGLOCK table to ensure only one migration runs at a time. If the process is terminated unexpectedly, the LOCKED field remains set, preventing further migrations.
For more on best practices, see the Liquibase official documentation.
How Liquibase Database Migration Works
Liquibase tracks database changes using a changelog file, applying migrations in sequence. Each migration locks the database, runs the changes, and releases the lock. Kubernetes interruptions, however, can leave the database in a locked state.
To solve this, Init Containers can run migrations first, before application pods start. This guarantees that only one Liquibase database migration runs at a time, preventing conflicts.
ZippyOPS offers consulting, implementation, and managed services in DevOps, DevSecOps, DataOps, Cloud, Automated Ops, AIOps, MLOps, Microservices, Infrastructure, and Security, helping teams implement these processes seamlessly. Learn more about our services and solutions.
Case Study: Running Database Migration with Init Containers
Liquibase provides official Docker images, but production environments often require additional tools like awscli for secret-based database access.
Our approach:
- Use JDK 11 base image for Java dependencies.
- Install Liquibase and AWS CLI in a custom Dockerfile.
- Run a bash script in the Init Container to handle migration from start to finish.
If the service is already live, ensure the changeLogFile parameter matches the FILENAME field in the DATABASECHANGELOG table. Mismatched files may cause migrations to reapply, risking data integrity.
Configuring Kubernetes for Database Migration
To implement Liquibase database migration with Init Containers:
- Name your main application container, e.g.,
"app". - Name the Init Container
"migrations". - Disable Spring Boot migrations in the main app:
spring: liquibase: enabled: false
This ensures migrations are executed exclusively by the Init Container. For test environments, migrations can still run automatically with H2 or other test databases.
Managing Exceptions in Liquibase Database Migration
Even with Init Containers, migrations may occasionally fail. We implemented a script that checks migration locks. If a lock persists over 15 minutes, it safely releases it using the release-locks command.
This approach provides full control over Liquibase database migration, reducing downtime and maintaining database integrity.
Benefits of Using Liquibase Database Migration in Kubernetes
- Reliable deployments: Minimize database lock issues.
- Controlled migrations: Only one migration process runs at a time.
- Custom dependencies: Supports AWS CLI and other tools.
- Test-friendly: Enables safe migrations in non-production environments.
ZippyOPS can assist with migration automation and Kubernetes deployment. Learn more about our products or watch tutorials on our YouTube channel.
Conclusion
Liquibase database migration using Init Containers is a robust solution to prevent locked databases in Kubernetes environments. While not entirely failproof, it significantly improves deployment stability and operational efficiency.
For consulting, implementation, or managed services in DevOps, Microservices, Cloud, Security, and more, contact ZippyOPS at sales@zippyops.com.
