turntables 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f3b7cb827f0bb39e3cc31e2ead6a8d271e3068bf
+  data.tar.gz: bd4970ab7927b33a741e17b331056d03b81e388d
+SHA512:
+  metadata.gz: 09104fc43b8e05ca2a45798b0d3742c3f70189e95cfcbfa4779e2dd8ed42b18b49b4a2e9ffe03055133523b53dff4b9d81f258048ad15eadd8986753fd72725e
+  data.tar.gz: 32404ef39e95bb8dd4a61e1f1faa5add76b315b9a9607c146615e29b78a9fb8adb525f795e3145d793dd9916ff6fc7d030236e39afbcffb3d4f2d3af0aa619ad

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.rdoc
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,6 @@
+*.swp
+.yardoc
+Gemfile.lock
+doc/
+pkg/
+vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+script: bundle exec rspec spec
+

data/.yardopts

@@ -0,0 +1 @@
+--markup rdoc --title "turntables Documentation" --protected

data/ChangeLog.rdoc

@@ -0,0 +1,10 @@
+=== 1.0.0 / 2013-07-03
+
+* Initial release:
+  * Can create db versioning with sequential transactions
+  * Can create db versioning with monolithic transactions
+  * Can detect malformed dirs / repos of said sql
+
+* TODO
+  * Want to have a way to set the database name
+

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 psyomn
+
+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.rdoc

@@ -0,0 +1,141 @@
+= turntables {<img src="https://codeclimate.com/github/psyomn/turntables.png" />}[https://codeclimate.com/github/psyomn/turntables] {<img src="https://travis-ci.org/psyomn/turntables.png?branch=master" alt="Build Status" />}[https://travis-ci.org/psyomn/turntables]
+
+* {Source}[http://github.com/psyomn/turntables]
+* {Homepage}[https://rubygems.org/gems/turntables]
+* {Documentation}[http://rubydoc.info/gems/turntables/frames]
+
+== Description
+
+This is not really ready, but putting it out there because I actually need it
+for something else I'm working on. If you can give a hand it will be very 
+appreciated (contact me).
+
+== Features
+
+== Examples
+This is a simple tutorial on how to invoke the database manager.
+
+You need a directory structure like this:
+
+  .
+  |-- main.rb
+  `-- sql
+      |-- mono
+      `-- seq
+          |-- 1.sql
+          |-- 2.sql
+          |-- 3.sql
+          `-- 4.sql
+
+The sql files can be like this for example. The comments that are prepended
+with '--$' are inserted in the version history table within the table manager
+so that if someone needs to diagnose issues on the long run, there are the 
+comments there at least (along with a version, and date field).
+
+1.sql: 
+
+  --$ First version will be created with this. The comments to be added in the
+  --$ versions history table can be prepended with the '$' sign in order for you
+  --$ specify comments (if needed). It's here if you want it. 
+  -- This is an example file to show how the turntables gem could work maybe
+  -- with people. and stuff.
+  -- This SQL file adds the person, and work_descriptions entities to the 
+  -- database. 
+  CREATE TABLE persons (
+    id      integer primary key autoincrement,
+    name    varchar(50),
+    surname varchar(50), 
+    age     integer
+  );
+
+  CREATE TABLE work_descriptions (
+    id          integer primary key autoincrement,
+    description text
+  );
+  
+2.sql:
+
+  --$ Bump to version 2. This is starting to look good!
+  -- And this is for the second revision of the database.
+  
+  CREATE TABLE inventory (
+    id integer primary key autoincrement, 
+    description text
+  );
+
+3.sql: 
+
+  --$ We did a mistake. We forgot to add a field to the persons table. The extra
+  --$ field to be added is the DOB. 
+  ALTER TABLE persons ADD COLUMN dob BIGINT;
+
+4.sql: 
+
+  --$ This table is added because now the system requires accounts as well.
+  --$ Sat Jul 13 21:45:40 EDT 2013
+  -- Table to create accounts for people.
+  CREATE TABLE accounts (
+    balance  float,
+    owner_id integer,
+    FOREIGN KEY(owner_id) references persons(id)
+  );
+
+main.rb should be like this: 
+
+  require 'turntables'
+  
+  include Turntables
+  
+  puts "This is to test the library and proof of concept of turntables"
+  
+  # Ideal way of calling this library
+  turntable = Turntable.new
+  
+  # sql is a directory containing two subdirs: seq, mono
+  # seq contains sequential transactions
+  # mono contains monolithic transactions
+  turntable.register('sql')
+  turntable.make!
+  
+  # Note: There should not be any other calls to the library. We give it the 
+  # sql repository location, and then it's the responsibility of Turntables to
+  # decide whether to take action or not.
+
+If you require that the database be made at a specified location, you should use
+the method `make_at!(location)`. To do this, just do what the above code does
+until `make!`. Then you need to call `make_at!` in the following way:
+
+  turntable.make_at!("path/to/database.db")
+
+Right now versions should be marked as the filename. Try to have intergers as
+versions, to avoid odd behaviour. So in this case versions {1,2,3} would
+respectively be in file form {1.sql, 2.sql, 3.sql}. 
+
+The monolithic transactions should be a combinations of all the versions, up to
+the one it denotes. In other words, version 4 would be the combination of all
+previous ones including itself {1.sql, 2.sql, 3.sql, 4.sql}.
+
+== Requirements
+
+* I've tested this with Ruby Versions = {2.0, 1.9.3}, though you should not
+  really have any issues in theory.
+
+* SQLite3 gem
+
+== Install
+
+  $ gem install turntables
+
+== Synopsis
+
+  $ turntables
+
+== Copyright
+
+Copyright (c) 2013 psyomn
+
+== License
+
+License is MIT regardless what you may see or find elsewhere; I might have not
+changed it due to lack of time.
+

data/Rakefile

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler."
+  exit -1
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems."
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require "bundler/gem_tasks"
+
+require 'yard'
+YARD::Rake::YardocTask.new  
+task :doc => :yard

data/bin/turntables

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require 'turntables'
+include Turntables
+
+if ARGV.count > 0
+  turntable = Turntable.new
+  turntable.register(ARGV[0])
+  turntable.make!
+else
+  puts "Usage: "
+  puts "  turtables <repo-dir>"
+end

data/lib/turntables/constants/repository_constants.rb

@@ -0,0 +1,6 @@
+module Turntables
+module RepositoryConstants
+  SeqDir  = "seq/"
+  MonoDir = "mono/"
+end
+end

data/lib/turntables/db_registry.rb

@@ -0,0 +1,83 @@
+require 'sqlite3'
+require 'singleton'
+
+require 'turntables/sql_modules/db_registry_sql'
+
+module Turntables
+# Database Registry pattern that connects to an sqlite 3 database.
+# @author Simon Symeonidis
+class DbRegistry
+  include Singleton
+  include DbRegistrySql
+
+  # Init with default db name
+  # @param dbname is the name of the database is if it not specified
+  # TODO we need to be able to set this somehow differently - applications
+  # might require to name their database with their own specific name.
+  def initialize(dbname="default.db")
+    @handle = SQLite3::Database.new(dbname)
+    @name   = dbname
+  end
+
+  # Execute (any sort) of sql 
+  # @param sql is the multiple arguments of the function to execute. Usually
+  #   you should give it first the sql you want that is to be prepared. Then
+  #   you specify the variables to be set in the query, in the right order.
+  # @example Simple usage
+  #   sql = "INSERT INTO person (name, surname) values (?,?)"
+  #   DbRegistry.instance.execute(sql,"jon","doe")
+  # @return sql data
+  def execute(*sql)
+    @handle.execute(*sql)
+  rescue => ex
+    puts ex.message
+    puts ex.backtrace
+    puts "Offending sql: "
+    puts sql
+  end
+
+  # For special queries that may contain multiple statements. For example a
+  # query that contains first a 'create table' query, and then some inserts to
+  # poppulate that table. Ideally this should be used in order to create the
+  # tables in sequence.
+  # @param sql is the sql that contains multiple statements
+  def execute_batch(sql)
+    @handle.execute_batch(sql)
+  rescue => ex
+    puts ex.message
+    puts ex.backtrace
+    puts "Offending sql: "
+    puts sql
+  end
+
+  # Check if a table exists in the database
+  # @param name is the name of the table to check if exists
+  # @return true if table exists, false if not
+  def table_exists?(name)
+    val = @handle.execute(ExistsSql, "table", name) 
+    1 == val.flatten[0]
+  end
+
+  # Close the current database. 
+  # @warn This is mainly here for the rspec testing, and should not be used 
+  #   unless you really know what you're doing.
+  def close!
+    @handle.close unless @handle.closed?
+  end
+
+  # Open the database, with the name given previously
+  # @warn This is mainly here for the rspec testing, and should not be used 
+  #   unless you really know what you're doing.
+  def open!
+    @handle = SQLite3::Database.new(@name) if @handle.closed?
+  end
+
+  # The database name
+  attr_accessor :name
+
+private 
+  # Other classes should not use the database handle directly
+  attr :handle
+end
+end
+

data/lib/turntables/repository.rb

@@ -0,0 +1,148 @@
+require 'fileutils'
+
+# lib
+require 'turntables/transaction'
+require 'turntables/version_history'
+require 'turntables/db_registry'
+require 'turntables/sql_modules/version_history_sql'
+require 'turntables/constants/repository_constants'
+
+module Turntables
+# @author Simon Symeonidis
+# A turntables repository. This class is responsible for handling the
+# versioning. This includes tasks such as checking database availability,
+# and pulling up the version history table and modifying where needed (for
+# example when completing a transaction, recording the date, the new version,
+# and comments about said transaction).
+class Repository
+  include RepositoryConstants
+
+  def initialize
+    @transactions = Array.new
+    @monolithics  = Array.new
+  end
+
+  # @param location is the location of the sql repository for now (a directory
+  #   for now).
+  def register(location)
+    @relative_dir = location
+    @sequential_dir = "#{@relative_dir}/#{SeqDir}/"
+    @monolithic_dir = "#{@relative_dir}/#{MonoDir}/"
+
+    # Initialize the transactions
+    init_sequential_transactions!
+    init_monolithic_transactions!
+  end
+
+  # Function to call in order to make the database. 
+  # 
+  # TODO: Here, it should detect in what state the current database is in, and
+  # go from there. In other words, whether it can skip sequential database
+  # transactions by loading a monolithic one to exclude previous transactions.
+  def make!
+    select_transactions!
+    @transactions.each do |transaction| 
+      vh = VersionHistory.new(transaction.version, transaction.comment)
+      VersionHistory.insert(vh)
+      DbRegistry.instance.execute_batch(transaction.data)
+    end
+  end
+
+  # Check to see if the directory structure is malformed.
+  # @return true if the directory structure is malformed
+  def malformed?
+    abs_seq = File.expand_path(@sequential_dir)
+    abs_mon = File.expand_path(@monolithic_dir)
+    !(File.exists?(abs_seq) && File.exists?(abs_mon))
+  end
+
+  attr_accessor :sequential_dir
+  attr_accessor :monolithic_dir
+  attr_accessor :relative_dir
+  # Array<Turntables::Transaction>
+  attr_accessor :transactions
+  # Array<Turntables::Transaction>
+  attr_accessor :monolithics
+
+private 
+
+  # Depending on what has been done before, we need to choose the proper 
+  # transactions.
+  # TODO: This probably can be done cleaner
+  def select_transactions!
+    check = VersionHistory.check
+    if check == :fresh
+      # Fresh db means, we create the version history table
+      prepend_monolithic_transactions!
+      VersionHistory.pull_up!
+    else 
+      last_version = VersionHistory.find_last.version
+      @transactions.select!{|tr| tr.version > last_version}
+    end
+  end
+
+  # This checks to see if any monolithic transactions exist, which can
+  # eliminate previous sequential transactions.
+  def prepend_monolithic_transactions!
+    max = @monolithics.max_by &:version
+    unless max.nil?
+      @transactions.select!{|tr| tr.version > max.version}
+      @transactions = @transactions.unshift(max)
+    end
+  end
+
+  # Find all the transactions that are to be processed sequentially
+  # @return nil
+  def init_sequential_transactions!
+    init_generic_transactions(sequential_files, @transactions)
+  end
+
+  # Find all the transactions that are to be processed only once
+  # @return nil
+  def init_monolithic_transactions!
+    init_generic_transactions(monolithic_files, @monolithics)
+  end
+
+  # this is a generic transaction reader
+  # return nil
+  def init_generic_transactions(file_list, transaction_holder)
+    file_list.each do |path|
+      data        = File.open(path).read
+      filename    = path.split(/\//).last
+      transaction_holder.push Transaction.new(data,filename)
+    end
+    nil
+  end
+
+  # Get the sequential transactional files
+  def sequential_files
+    get_files_in_dir(@sequential_dir)
+  end
+
+  # Get the monolithic transactional files
+  def monolithic_files
+    get_files_in_dir(@monolithic_dir)
+  end
+
+  # Return the files that are in the given directory
+  # @param path is the path to look for files in the directory
+  # @return Array<String> of files sorted by stringnum_comparison predicate
+  def get_files_in_dir(path)
+    Dir["#{path}*"].sort!{|e1,e2| stringnum_comparison(e1,e2)}
+  end
+
+  # Compare two strings with each other by extracting the digits
+  def stringnum_comparison(a,b)
+    extract_digits(a) <=> extract_digits(b)
+  end
+
+  # Extract the numbers from the string, and convert to Fixnum
+  # @param string is the string to extract the numbers from
+  # @return the number that was found in the string
+  def extract_digits(string)
+    string.gsub(/\D/,'').to_i
+  end
+
+end
+end
+

data/lib/turntables/sql_modules/db_registry_sql.rb

@@ -0,0 +1,7 @@
+module Turntables
+# @author Simon Symeonidis 
+# The sql for the db registry.
+module DbRegistrySql
+  ExistsSql = "SELECT COUNT(type) from sqlite_master where type=? and name=?"
+end
+end

data/lib/turntables/sql_modules/version_history_sql.rb

@@ -0,0 +1,30 @@
+module Turntables
+# @author Simon Symeonidis
+# Some static information factored out to avoid class variables, and to 
+# separate concerns.
+module VersionHistorySql
+  # Table name of this guy
+  TableName  = "version_histories"
+
+  # Table schema for the version history table.
+  Create     = "CREATE TABLE #{TableName} ("\
+    "id      INTEGER PRIMARY KEY AUTOINCREMENT, "\
+    "version BIGINT, "\
+    "date    BIGINT, "\
+    "comment TEXT)"
+
+  # Select last inserted transaction
+  SelectLast = "SELECT * FROM #{TableName} "\
+    " WHERE id=(SELECT MAX(id) FROM #{TableName});"
+
+  # Select a record by id
+  SelectById = "SELECT * FROM #{TableName} WHERE id=?"
+
+  # Select all the records
+  SelectAll  = "SELECT * FROM #{TableName}"
+ 
+  # Sql to insert a version history into the table
+  Insert     = "INSERT INTO #{TableName} (version,date,comment)"\
+               " values (?,?,?)"
+end
+end

data/lib/turntables/transaction.rb

@@ -0,0 +1,39 @@
+module Turntables
+# @author Simon Symeonidis  
+# @date   Wed Jul 10 19:51:42 EDT 2013
+# This class takes care of a single transaction
+class Transaction
+
+  # Initialize this object with the contents of the sql file
+  # @param sql_file_contents are the contents of the given sql file
+  # @param filename is the filename of the given sql file. We use the filenames
+  #   for the version that it is supposed to upgrade to.
+  def initialize(sql_file_contents,filename)
+    # Select only the lines that begin with '--$'
+    @comment = sql_file_contents.lines.select{|el| el.match(/--\$/)}.join
+    @comment.gsub!(/--\$/, '')
+    @version = filename.to_i
+    @data    = sql_file_contents
+  end
+
+  # The version should be obtained from the file name of the respective sql
+  # file.
+  attr_accessor :version
+  
+  # The comment should be parsed out from the respective sql file. We want to 
+  # keep the comments in the sql file to keep things organized. We do not want
+  # to alter the sql language to fit our needs. Therefore we just require the 
+  # user to comment lines as '--$ my comment here' in order to parse them out
+  # @example How to write comments that are to be parsed
+  #   --$ author jon doe
+  #   --$ This sql file will update the schema to version 1.2
+  #   --$ You should note this and that
+  #   -- This commen line would be ignored
+  #
+  #   CREATE TABLE accounts ( ... ) 
+  attr_accessor :comment
+
+  # The sql information to be passed on to the db registry 
+  attr_accessor :data
+end
+end

data/lib/turntables/turntable.rb

@@ -0,0 +1,40 @@
+require 'turntables/db_registry'
+require 'turntables/repository'
+require 'turntables/turntable_exception'
+
+module Turntables
+# @author Simon Symeonidis
+# The facade controller to the rest of this library.
+class Turntable
+  # Default constructor, that initializes some standard parameters
+  def initialize
+    @revisions = Array.new
+    @repository = Repository.new
+  end
+
+  # Register a revision that needs to be processed later
+  # @param repository_root_path is the root path to all the sql.
+  def register(repository_root_path)
+    @repository.register(repository_root_path)
+  end
+
+  # Make the repository at a specific location instead of default.
+  def make_at!(location)
+    DbRegistry.instance.close!
+    DbRegistry.instance.name = location
+    DbRegistry.instance.open!
+    make!
+  end 
+
+  # Create the tables by going through each revision
+  def make!
+    if @repository.malformed?
+      raise TurntableException, "The directory structure is malformed."
+    else
+      @repository.make!
+    end
+  end
+
+  attr_accessor :repository
+end
+end

data/lib/turntables/turntable_exception.rb

@@ -0,0 +1,7 @@
+module Turntables
+# @author Simon Symeonidis 
+# library exception. Raise this instead of RuntimeError
+class TurntableException < RuntimeError
+end
+end
+

data/lib/turntables/version.rb

@@ -0,0 +1,4 @@
+module Turntables
+  # turntables version
+  VERSION = "1.0.1"
+end