🐦 Songbird

Extract SQL statements from Rails migrations for manual review and execution. Perfect for debugging, review, or manual execution of schema changes.

Add this line to your application's Gemfile:

gem 'songbird'

And then execute:

$ bundle install

Or install it directly:

$ gem install songbird

Songbird provides Rake tasks that integrate seamlessly with your Rails application to generate SQL for migrations.

Generate SQL for a specific migration:

rake db:migrate:sql[20241201000000]

Running the command without a version will show usage instructions and list your three most recent migrations for easy reference.

Songbird also provides a convenient shortcut command:

rake songbird:sql[20241201000000]    # Generate SQL for specific migration

The generated SQL includes helpful comments and proper formatting:

-- Generated SQL for pending Rails migrations
-- Generated at: 2024-12-01 10:30:00 UTC

-- Migration: 20241201000001 - Create users
-- File: 20241201000001_create_users.rb
CREATE TABLE "users" (id SERIAL PRIMARY KEY);
ALTER TABLE "users" ADD COLUMN "name" VARCHAR NOT NULL;

-- Update schema_migrations table:
INSERT INTO schema_migrations (version) VALUES ('20241201000001');

-- Migration: 20241201000002 - Add email to users
-- File: 20241201000002_add_email_to_users.rb
ALTER TABLE "users" ADD COLUMN "email" VARCHAR;

-- Update schema_migrations table:
INSERT INTO schema_migrations (version) VALUES ('20241201000002');

• ✅ Database-Agnostic - Works with any ActiveRecord-supported database
• ✅ Rails Integration - Works seamlessly with Rails migration system
• ✅ Schema Metadata - Automatically generates schema_migrations INSERT statements
• ✅ Clean Output Format - Properly commented SQL ready for database execution
• ✅ Specific Migration Support - Generate SQL for individual migrations by version
• ✅ Complete Migration Support - Supports all Rails migration operations by intercepting at the SQL level

When Rails migrations timeout in production due to long-running operations, they can leave migrations in an incomplete state that requires manual intervention. With Songbird:

1. Run rake db:migrate:sql[specific_migration_version] for the failed migration
2. Execute the generated SQL manually in your database
3. Resume normal Rails migrations

For organizations requiring DBA approval of schema changes:

1. Generate SQL using Songbird
2. Submit SQL for review
3. Execute approved SQL manually
4. Update schema_migrations table

Debug migration issues by reviewing the generated SQL before execution:

1. Generate SQL to understand what operations will be performed
2. Identify potential issues (missing indexes, constraint violations, etc.)
3. Modify migrations as needed

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

The gem is available as open source under the terms of the MIT License.

Bug reports and pull requests are welcome on GitHub at https://github.com/elciok/songbird.