db-migrate - ScyllaDB Migration Tool
A robust, production-ready database migration tool for ScyllaDB/Cassandra, written in Rust. Designed with extensibility in mind, it aims to bring a familiar approach to other databases as well. This tool offers Rails- and Django-style migrations, featuring advanced capabilities like checksum verification, rollback support, and schema drift detection.
🚀 Features
- Migration Tracking: Keeps track of applied migrations with checksums
- Idempotent Operations: Safe to run multiple times
- Rollback Support: Reverse migrations with DOWN sections
- Checksum Verification: Detect unauthorized changes to migration files
- Dry Run Mode: Preview changes before applying
- CI/CD Ready: JSON output and clear exit codes
- Environment Configuration: Config files + environment variables
- Force Operations: Handle edge cases safely
📦 Installation
From Source
Using Cargo
⚙️ Configuration
Configuration File (db-migrate.toml
)
[]
= ["127.0.0.1:9042"]
= "my_keyspace"
= ""
= ""
[]
= "./migrations"
= "schema_migrations"
[]
= true
= true
= false # Set to true for development
Environment Variables
🎯 Quick Start
1. Initialize Configuration
# Create default config file
# Or manually create db-migrate.toml with your settings
2. Create Your First Migration
This creates: migrations/20250128_143022_create_users_table.cql
3. Edit the Migration File
-- Migration: create_users_table
-- Created at: 2025-01-28 14:30:22 UTC
-- +migrate Up
(
id UUID PRIMARY KEY,
email TEXT,
name TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP
);
(email);
-- +migrate Down
IF EXISTS users_email_idx;
IF EXISTS users;
4. Apply Migrations
# See what would be applied
# Apply all pending migrations
# Apply only the next 2 migrations
5. Check Status
📋 Commands
create <description>
Create a new migration file with the given description.
up [options]
Apply pending migrations.
down [options]
Rollback applied migrations.
status [options]
Show current migration status.
verify [options]
Verify migration integrity and detect schema drift.
reset [options]
Reset all migrations (destructive).
📁 Migration File Format
File Naming Convention
Files must follow the pattern: YYYYMMDD_HHMMSS_description.cql
Example: 20250128_143022_create_users_table.cql
File Structure
-- Optional: Migration description and metadata
-- +migrate Up
-- Your forward migration statements here
(
id UUID PRIMARY KEY,
name TEXT
);
-- +migrate Down
-- Your rollback statements here (optional but recommended)
example;
Best Practices
- Always include DOWN sections for reversible migrations
- Use IF EXISTS/IF NOT EXISTS for idempotency
- One logical change per migration (single table, index, etc.)
- Test rollbacks before applying to production
- Descriptive names that explain the change
🔧 Advanced Usage
JSON Output for CI/CD
|
Environment-Specific Configurations
# Development
# Production
Handling Complex Migrations
For migrations that can't be easily reversed:
-- +migrate Up
users ADD COLUMN new_field TEXT;
-- Populate new_field with data transformation
UPDATE users SET new_field = transform(old_field);
-- +migrate Down
-- Note: This migration cannot be automatically reversed
-- Manual steps required:
-- 1. Verify no application dependencies on new_field
-- 2. Run: ALTER TABLE users DROP COLUMN new_field;
🚨 Production Considerations
Pre-deployment Checks
# 1. Verify all migrations
# 2. Dry run on production schema
# 3. Check pending count
|
Safe Deployment Pattern
# 1. Backup database (external tool)
# 2. Apply migrations with monitoring
# 3. Verify application health
# 4. If issues: rollback
CI/CD Integration
# Example GitHub Actions step
- name: Apply Database Migrations
run: |
./db-migrate verify
./db-migrate up
# Check exit code
if [ $? -eq 0 ]; then
echo "✅ Migrations applied successfully"
else
echo "❌ Migration failed"
exit 1
fi
🐛 Troubleshooting
Common Issues
Migration checksum mismatch:
Missing DOWN section:
Connection issues:
# Verify connection
# Check configuration
Schema drift:
Recovery Scenarios
Corrupted migration state:
# Last resort - reset and reapply (DANGEROUS)
Partial migration failure:
# Check what was applied
# Manual cleanup may be needed
# Then retry: ./db-migrate up
🤝 Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass:
cargo test
- Submit a pull request
📄 License
MIT License - see LICENSE file for details.
🆘 Support
- File issues on GitHub for bugs/features
- Check existing issues for common problems
- Include migration files and config when reporting issues