sp-squealer 1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/
+tags
+tmp/

data/.rvmrc

@@ -0,0 +1,6 @@
+# These are the rubies that squealer has been tested on. Uncomment the one you want to use right now.
+# 1.8.7-p249 segfaults postgres.
+#
+rvm use 1.8.7-p174@squealer
+# rvm use 1.9.1@squealer #-p378
+# rvm use 1.9.2@squealer #-preview3

data/.watchr

@@ -0,0 +1,27 @@
+# ~/.vim/ftdetect/watchr.vim
+#
+# This should have only the following line in it:
+#
+# autocmd BufNewFile,BufRead *.watchr setf ruby
+#
+# This will enable vim to recognize this file as ruby code should you wish to
+# edit it.
+def run(cmd)
+  puts cmd
+  system cmd
+end
+
+def spec(file)
+  run "spec -O spec/spec.opts #{file}"
+end
+
+watch("spec/.*/*_spec\.rb") do |match|
+  p match[0]
+  spec(match[0])
+end
+
+watch("lib/(.*/.*)\.rb") do |match|
+  p match[1]
+  spec("spec/#{match[1]}_spec.rb")
+end
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Joshua A. Graham and authors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Squealer
+
+## Usage
+See lib/example_squeal.rb for the example squeal.
+
+To run standalone, simply make your data squeal thusly:
+
+`ruby example_squeal.rb`
+
+where the squeal script includes a `require 'squealer'`.
+
+## Rationale
+* For some reason cranky old data guys think there exists no other than the relational theory for modelling data
+* Josh Graham is crankier and in many cases older (although much better looking) than your cranky old DBA, so he remembers when RDBMS were not prolific, and one had to construct queries that explicitly traversed the network or hierarchical databases of the time (or even the indexed file systems). CODASYL, can you spell it?
+* Although many business problems are best expressed in terms of a spreadsheet (a tuple space), and despite the somewhat disturbing fact that the majority of the world's critical commercial systems hinge on Excel spreadsheets, not every problem is best modelled this way
+* MongoDB (along with a growing number of other noSQL == "not only SQL" databases) provides an alternate mechanism to store data in a way that naturally reflects the real-world problem. Simpler application code, higher performance and straight-forward scalabiltity are natural benefits of modelling in a way that most closely reflects reality
+* At the inaugural QCon San Francisco in a discussion with Martin Fowler and Ola Bini, Josh postulated that ORMs had it the wrong way around: that the application should be persisting its data in a manner natural to it, and that external systems (like reporting and decision support systems - or even numbskull integration at the persistence layer) should bear the cost of mapping. With the huge efforts put into noSQL engines like MongoDB, neo4j, Redis, Hadoop, CouchDB, Memcached, et cetera, has come a rise in popularity. With this increased and broader usage comes people who are looking for tools to make these data stores more accessible. The application is no longer bearing the cost of mapping - it's now time for the ancillary and external systems to pick up the bill!
+* squealer provides a simple, declarative language for mapping values from trees into relations. It is inherently flexibile by being an internal Ruby DSL, so any imperative traversal or mapping logic can be expressed
+* It can be used both in bulk operations on many documents (e.g. a periodic batch job) or executed for one document asynchronously as part of an after_save method (e.g. via a Resque job). It is possible that more work may done on this event-driven approach, perhaps in the form of a squealerd, to reduce latency.
+* For more on rationale, see my [blog post](http://grahamis.com/blog/2010/06/10/squealer-intro/ "Why squealer") and another from [Debasish Ghosh](http://debasishg.blogspot.com/2010/06/phase-shift-for-orm.html "A Phase Shift for the ORM")
+
+## Release Notes
+### v2.2
+* Adds support for PostgreSQL database as an export target
+* Uses EXPORT_DBMS environment variable to specify database adapter. `EXPORT_DMBS=mysql` or `EXPORT_DBMS=postgres`. MySQL is default if not specified
+* Switched to using DataMapper's DataObjects SQL wrapper
+* Removed the need for some typecasting and export schema restrictions (e.g. true/false maps to whatever is idiomatic for the specified DBMS)
+* NB: The pg gem for PostgreSQL segfaults on Ruby 1.8.7-p249 so we've reverted to supporting up to 1.8.7-p174
+
+### v2.1
+* Ruby 1.8.6 back-compatibility added. Using `eval "", binding, __FILE__, __LINE__` instead of `binding.eval`
+* Target SQL script using backtick-quoted (MySQL) identifiers to avoid column-name / keyword conflict
+* Automatically typecast Ruby `Boolean` (to integer), `Symbol` (to string), `Array` (to comma-seperated string)
+* Improved handling and reporting of Target SQL errors
+* Schaefer's Special "skewer" Script to reflect on Mongoid models and generate an initial squeal script and SQL schema DDL script. This tool is intended to build the _initial_ scripts only. It is extremely useful to get you going, but do think about the needs of the consumer of the export database, and adjust the scripts to suit. [How do you make something squeal? You skewer it!]
+
+### v2.0
+* `Object#import` now wraps a MongoDB cursor to provide counters and timings. Only `each` is supported for now, however `source` takes optional conditions.
+* Progress bar and summary.
+
+### v1.2.1
+* `Object#import` syntax has changed. Now `import.source(collection).each` rather than `import.collection(collection).find({}).each`. `source` returns a MongoDB cursor like `find` does. See lib/example_squeal.rb for options.
+
+### v1.2
+* `Object#target` verifies there is a variable in scope with the same name as the `table_name` being targetted, it must be a `Hash` and must have an `_id` key
+* Block to `Object#assign` not required, infers value from source scope
+* A block returning `nil` now uses `nil` as the value to `Object#assign`, rather than inferring value from source scope
+
+## Warning
+Squealer is for _standalone_ operation. DO NOT use it directly from within your Ruby application. To make the DSL easy to use, we alter some core types:
+
+* `Hash#method_missing` - You prefer dot notation. JSON uses dot notation. You are importing from a data store which represents collections as arrays of hashmaps. Dot notation for navigating those collections is convenient. If you use a field name that happens to be a method on Hash you will have to use index notation. (e.g. `kitten.toys` is good, however `kitten.freeze` is not good. Use `kitten['freeze']` instead.)
+* `NilClass#each` - As you are importing from schemaless repositories and you may be trying to iterate on fields that contain embedded collections, if a specific parent does not contain one of those child collections, the driver will be returning `nil` as the value for that field. Having `NilClass#each` return a `[]` for a nil is convenient, semantically correct in this context, and removes the need for many `nil` checks in the block you provide to `Object#assign`
+* `Object` - `#import`, `#export`, `#target`, and `#assign` "keywords" are provided for convenience
+* You need to remember that all temporal data (date, time, datetime, timestamp, whatever) are all converted to a full UTC date and time. This means that if you want to use the simple assign expression (with no block), the target column must be defined as a SQL type that can automatically accept a full date and time. If you just want to store the date or time portion, or do any other manipulation, you must use a block to convert the source value. 
+
+## It is a data mapper, it doesn't use one.
+Squealer doesn't use your application classes. It doesn't use your ActiveRecord models. It doesn't use mongoid (as awesome as that is), mongodoc, or mongomapper. It's an ETL tool. It could even be called a HRM (Hashmap-Relational-Mapper), but only in hushed tones in the corner boothes of dark pubs. It directly uses the Ruby driver for MongoDB and the Ruby driver for MySQL.
+
+## Databases supported
+For now, this is specifically for importing _MongoDB_ documents and exporting to either _MySQL_ or _PostgreSQL_.
+
+## Notes
+Tested on Ruby 1.8.7(-p174) and Ruby 1.9.1(-p378)
+
+The target SQL database _must_ have no foreign keys (because it can't rely on the primary key values and referential integrity is the responsibility of the source data store or the application that uses it).
+
+The target SQL database must use a primary key of `CHAR(24)`. For now, we've assumed that column name is `id`. Each record's `id` value will get the source document `_id` value. There are some plans to make this more flexible. If you are actively requiring this, let Josh know.
+
+It is assumed the target data will be quite denormalized - particularly that the hierarchy keys for embedded documents are flattened. This means that a document from `office.room.box` will be exported to a record containing the `id` for `office`, the `id` for `room` and the `id` for `box`.
+
+It is assumed no indexes are present in the target database table (performance drag). You may want to create indexes for pulling data out of the database Squealer exports to. Run a SQL DDL script on your MySQL database after squealing to add the indexes. You should drop the indexes before squealing again.
+
+The target row is inserted, or updated if present. When MySQL is the export DBMS, we are using it's non-standard `INSERT ... UPDATE ON DUPLICATE KEY` extended syntax to achieve this. For PostgreSQL, we use an UPDATE followed by an INSERT. Doing update-or-insert allows an idempotent event-driven update of exported data (e.g. through redis queues) as well as a bulk batch process.
+
+## Copyright
+
+Copyright © 2010 Joshua A Graham and authors.
+
+## License
+
+See [LICENSE](blob/master/LICENSE "License").
+

data/Rakefile

@@ -0,0 +1,44 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+require 'metric_fu'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "squealer"
+    gemspec.summary = "Export document-oriented database to RDBMS"
+    gemspec.description = "A Ruby DSL for exporting MongoDB to MySQL or PostgreSQL. You don't need to install both, just one. Use EXPORT_DBMS=[mysql|postgres] environment variable to specify the appropriate adapter."
+    gemspec.email = "joshua.graham@grahamis.com"
+    gemspec.homepage = "http://github.com/delitescere/squealer/"
+    gemspec.authors = ["Josh Graham", "Durran Jordan", "Matt Yoho", "Bernerd Schaefer"]
+
+    gemspec.default_executable = "skewer"
+    gemspec.executables = ["skewer"]
+
+    # import DBMS
+    gemspec.add_dependency('mongo', '>= 0.18.3')
+    gemspec.add_dependency('bson_ext', '>= 1.0.1')
+
+    # export DBMS
+    gemspec.add_dependency('data_objects', '>= 0.10.2')
+    gemspec.add_dependency('do_mysql', '>= 0.10.2')
+    gemspec.add_dependency('do_postgres', '>= 0.10.2')
+
+    gemspec.add_development_dependency('rspec', '>= 1.3.0')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', "\"#{File.dirname(__FILE__)}/spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*/*_spec.rb']
+end
+
+task :default => [:spec]

data/VERSION

@@ -0,0 +1 @@
+2.2.2

data/bin/skewer

@@ -0,0 +1,161 @@
+#!/usr/bin/env ruby
+
+model = ARGV[0]
+abort "usage: skewer ModelName" unless model
+
+require 'config/boot'
+require 'config/environment'
+
+model = Object.const_get(model)
+
+unless defined?(Mongoid) && Mongoid::Document > model
+  abort "#{model} must be a Mongoid::Document"
+end
+
+write_schema = true
+write_squeal = true
+
+schema_filename = "#{model.name.underscore}_schema.sql"
+squeal_filename = "#{model.name.underscore}_squeal.rb"
+
+schema_exists = File.exists?(schema_filename)
+squeal_exists = File.exists?(squeal_filename)
+
+if schema_exists || squeal_exists
+  $stdout.print "#{schema_filename} already exists, overwrite? [Y/n] "
+  write_schema = $stdin.gets.chomp != "n"
+
+  $stdout.print "#{squeal_filename} already exists, overwrite? [Y/n] "
+  write_squeal = $stdin.gets.chomp != "n"
+end
+
+fields = model.fields.values.sort_by(&:name)
+associations = model.associations
+
+# SQL #
+def create_table(model, parent = nil)
+  fields = model.fields.values.sort_by(&:name)
+  columns = []
+  columns << "`#{parent.name.underscore}_id` CHAR(24)" if parent
+
+  fields.each do |field|
+    mysql_type = case field.type.name
+                 when "Boolean"
+                   "BOOLEAN"
+                 when "Time"
+                   "TIMESTAMP NULL DEFAULT NULL"
+                 when "Date"
+                   "DATE"
+                 when "Float"
+                   "FLOAT"
+                 when "Integer"
+                   "INT"
+                 else
+                   "TEXT"
+                 end
+    columns << "`#{field.name[0..63]}` #{mysql_type}"
+  end
+
+  table_name = if parent
+                 "#{parent.name.underscore}_#{model.name.underscore}"
+               else
+                 "#{model.name.underscore}"
+               end
+
+  table_sql = []
+  table_sql << "DROP TABLE IF EXISTS `#{table_name}`;"
+  table_sql << "CREATE TABLE `#{table_name}` (`id` CHAR(24) PRIMARY KEY);"
+  columns.each do |column|
+    table_sql << "ALTER TABLE `#{table_name}` ADD COLUMN #{column};"
+  end
+
+  table_sql.join("\n") + "\n"
+end
+
+# SQUEAL #
+def create_squeal(model, indent=false, parents = [])
+  fields = model.fields.values.sort_by(&:name)
+
+  parent = parents.last
+  table_name = if parent
+                 "#{parent.name.underscore}_#{model.name.underscore}"
+               else
+                 "#{model.name.underscore}"
+               end
+
+  squeal = if parent
+    "#{parent.name.underscore}.#{model.name.tableize}.each do |#{model.name.underscore}|\n" \
+    "  #{table_name} = #{model.name.underscore}"
+  else
+    "import.source(\"#{model.name.tableize}\").each do |#{model.name.underscore}|"
+  end
+
+  schemas = [create_table(model, parent)]
+
+  squeal << <<-EOS
+
+  target(:#{table_name}) do
+  EOS
+  if parent
+    squeal << <<-EOS
+    assign(:#{parent.name.underscore}_id)
+    EOS
+  end
+
+  fields.each do |field|
+    field_name = field.name
+    case
+    when %w(type target).include?(field.name)
+      value = " { #{table_name}['#{field.name}'] }"
+    when field.name.size > 64
+      field_name = field.name[0..63]
+      value = " { #{table_name}.#{field.name} }"
+    when field.name =~ /(.*)_id$/
+      value = " { #{table_name}.#{$1} }"
+    end
+    squeal << <<-EOS
+    assign(:#{field_name})#{value}
+    EOS
+  end
+
+  model.associations.values.each do |association|
+    begin
+      if [Mongoid::Associations::HasMany, Mongoid::Associations::HasOne].include?(association.association)
+        unless parents.include?(association.klass)
+          ruby, sql = create_squeal(association.klass, true, parents | [model]) 
+          squeal << "\n" + ruby + "\n"
+          schemas |= sql
+        end
+      end
+    rescue NameError
+    end
+  end
+
+  squeal << <<-EOS
+  end
+end # #{table_name}
+  EOS
+  squeal.gsub!(/^/, "    ") if indent
+  return squeal, schemas
+end
+
+squeal, schema = create_squeal(model)
+
+if write_squeal
+  File.open(squeal_filename, "w") do |file|
+    file.write <<-EOS
+require 'squealer'
+
+import('mysql', 'localhost', 27017, 'development') # <--- Change this as needed
+export('mysql', 'localhost', 'root', '', 'export') # <--- Change this as needed
+
+EOS
+    file.write(squeal)
+  end
+end
+
+if write_schema
+  File.open(schema_filename, "w") do |file|
+    file.write(schema.join("\n"))
+  end
+end

data/lib/example_squeal.rb

@@ -0,0 +1,59 @@
+require 'squealer'
+
+# connect to the source mongodb database
+import 'localhost', 27017, 'development'
+
+# connect to the target mysql database
+export 'mysql', 'localhost', 'root', '', 'reporting_export'
+
+import.source('users').each do |user|
+  target(:user) do
+    assign(:name) { "#{user.last_name.upcase}, #{user.first_name}" }
+    assign(:dob) { user.date_of_birth }
+    assign(:gender) #or# assign(:gender) { user.gender }
+
+    # You can normalize the export...
+    # home_address and work_address are a formatted string like: "661 W Lake St, Suite 3NE, Chicago IL, 60611, USA"
+    addresses = []
+    addresses << atomize_address(user.home_address) # atomize_address is some custom method of yours
+    addresses << atomize_address(user.work_address)
+    addresses.each do |address|
+      target(:address) do
+        assign(:street)
+        assign(:city)
+        assign(:state)
+        assign(:zip)
+      end
+    end
+
+    # You can denormalize the export...
+    # user.home_address = { street: '661 W Lake St', city: 'Chicago', state: 'IL' }
+    assign(:home_address) { flatten_address(user.home_address) } # flatten_address is some custom method of yours
+    assign(:work_address) { flatten_address(user.work_address) }
+
+    user.activities.each do |activity|
+      target(:activity) do
+        assign(:user_id) #or# assign(:user_id) { user._id }
+        assign(:name)
+        assign(:due_date)
+      end
+
+      activity.tasks.each do |task|
+        target(:task) do
+          assign(:user_id)
+          assign(:activity_id)
+          assign(:due_date)
+        end
+      end #activity.tasks
+    end #user.activities
+  end
+end #collection("users")
+
+# Here we use a procedural "join" on related collections to update a target...
+import.source('organizations', {'disabled_date' => {'exists' => true}}).each do |organization|
+  import.source('users', {'organization_id' => organization.id}) do |user|
+    target(:user) do
+      assign(:disabled) { true }
+    end
+  end
+end

data/lib/squealer.rb

@@ -0,0 +1,6 @@
+require 'squealer/hash'
+require 'squealer/object'
+
+require 'squealer/database'
+require 'squealer/progress_bar'
+require 'squealer/target'

data/lib/squealer/database.rb

@@ -0,0 +1,87 @@
+require 'singleton'
+
+require 'mongo'
+# data_objects required under export_to dependant on adapter requested in EXPORT_DBMS
+
+module Squealer
+  class Database
+    include Singleton
+
+    def import_from(host, port, name)
+      @import_dbc = Mongo::Connection.new(host, port, :slave_ok => true).db(name)
+      @import_connection = Connection.new(@import_dbc)
+    end
+
+    def export_to(adapter, host, username, password, name)
+      require "do_#{adapter}"
+
+      @export_do.release if @export_do
+      creds = ""
+      creds << username if username
+      creds << ":#{password}" if password
+      at_host = ""
+      at_host << "#{creds}@" unless creds.empty?
+      at_host << host
+      @export_do = DataObjects::Connection.new("#{adapter}://#{at_host}/#{name}")
+    end
+
+    def import
+      @import_connection
+    end
+
+    def export
+      @export_do
+    end
+
+    def upsertable?
+      defined?(DataObjects::Mysql) && @export_do.is_a?(DataObjects::Mysql::Connection)
+    end
+
+    class Connection
+      attr_reader :collections
+
+      def initialize(dbc)
+        @dbc = dbc
+        @collections = {}
+      end
+
+      def source(collection, conditions = {}, &block)
+        source = Source.new(@dbc, collection)
+        @collections[collection] = source
+        source.source(conditions, &block)
+      end
+
+      def eval(string)
+        @dbc.eval(string)
+      end
+    end # Connection
+
+    class Source
+      attr_reader :counts, :cursor
+
+      def initialize(dbc, collection)
+        @counts = {:exported => 0, :imported => 0}
+        @collection = dbc.collection(collection)
+      end
+
+      def source(conditions)
+        @cursor = block_given? ? yield(@collection) : @collection.find(conditions)
+        @counts[:total] = cursor.count
+        @progress_bar = Squealer::ProgressBar.new(cursor.count)
+        self
+      end
+
+      def each
+        @progress_bar.start if @progress_bar
+        @cursor.each do |row|
+          @counts[:imported] += 1
+          yield row
+          @progress_bar.tick if @progress_bar
+          @counts[:exported] += 1
+        end
+        @progress_bar.finish if @progress_bar
+      end
+    end # Source
+
+  end
+end