spanner-translator

Spanner::Translator

A quick-and-dirty Rubocop::AST based create_table Ruby source rewriting translator to facilitate migration from MySQL to Google Cloud Spanner.

Not intended to be a generally-useful gem, but available for use / fork as needed.

Installation

Add the gem as a github: dependency to your Gemfile:

group :development do
  gem 'spanner-translator', github: 'abachman/spanner-translator', branch: 'main', require: false
end

Usage

If you're in a Rails project, configure the library and use the spanner:translate Rake task:

# config/initializers/spanner_translator.rb

if Rails.env.development?
  require 'spanner/translator'

  Spanner::Translator.configure do |config|
    config.default_primary_keys = [:related_table_id, :id]
    config.db_schema = Rails.root.join('db/schema.rb')
  end
end

$ bundle exec rake spanner:translate[smalls]

Or in any project, call the library from a script:

# frozen_string_literal: true

require 'spanner/translator'

Spanner::Translator.configure do |config|
  config.default_primary_keys = [:id]
end

source = <<~RUBY
  create_table "smalls", id: { type: :bigint, unsigned: true, default: nil } do |t|
    t.string "name", null: false
    t.index ["name"], name: "index_smalls_on_name", order: { name: :asc }
  end
RUBY

puts Spanner::Translator::CLI.process_code!(source)

Or, maybe simplest, use bundler/inline to gem install and require the library from a one-off Ruby script that can be run from inside a Rails project directory:

require 'bundler/inline'
gemfile do
  source 'https://rubygems.org'
  gem 'spanner-translator', github: 'recurly/spanner-translator', branch: 'main'
end

require 'spanner/translator'
Spanner::Translator.configure do |config|
  # use a composite primary key for every converted table
  config.default_primary_keys = [:owner_id, :id]
  # spanner-translator assumes schema exists at ./db/schema.rb
end

tables = %w(users blog_posts comments)

tables.each do |table_name|
  # load the corresponding `create_table` statement from db/schema.rb
  source = Spanner::Translator::Schema.extract_create_table(table_name)

  # print the translated Spanner `create_table` statement
  puts Spanner::Translator::CLI.process_code!(source)
end

Safely Rewriting a File

Rewriting a source file in your project boils down to:

• Read file source
• Process source with rules
• Write file
• Run test
• Revert if test fails

Development

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.

Run the test suite with bundle exec rspec.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/abachman/spanner-translator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Spanner::Translator project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.