squixtures 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'logjam'
+gem 'sequel'
+
+# Specify your gem's dependencies in squixtures.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Peter Wood
+
+MIT License
+
+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,148 @@
+# Squixtures
+
+Squixtures is a library that provides a simple data fixtures facility, ala
+the fixtures generally used in unit tests. The library came about because it
+is quite difficult to make use of Rails fixtures outside of the Rails
+framework itself.
+
+The Squixtures library makes use of the Sequel library in an attempt to
+attain database independence. At the moment it has only been coded for and
+tested with SQLite3 and Postgres. Squixtures also makes use of the LogJam
+library to centralize it's logging.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'squixtures'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install squixtures
+
+## Usage
+
+Squixtures is a library so the first thing to do is to incorporated it
+into the file where you plan to use it. This can be done with a simple
+require such as the following...
+
+    require 'rubygems'
+    require 'squixtures'
+
+Squixtures is based around amodule so how you deploy it will depend heavily
+on how you want to use it. If, for example, you only want to deploy fixtures
+once, when a class definition is loaded, you can use the extend statement
+to incorporate the functionality at the class level and then invoke the
+fixtures you want. For example...
+
+    class MyClass
+        # Extend the class with Squixtures functionality.
+        extend Squixtures::Fixtures
+
+        # Load the fixtures required.
+        fixtures :users, :accounts, :orders
+    end
+
+Alternatively, if you want the fixtures reloaded regularly, say as part of
+the set up process for a unit test, you would include the squixtures
+functionality like this...
+
+    class TestMyClass
+        # Incorporate the Squixtures functionality.
+        include Squixtures::Fixtures
+
+        def setup
+            # Load the desired fixtures.
+            fixtures :users, :accounts, :orders
+        end
+    end
+
+By default the Squixtures fixture loader empties the target table between
+fixture loads. This feature is configurable but you should be aware of it
+as it could cause data loss. Squixtures currently only recognises YAML
+style fixtures which, as an example, follow this format...
+
+    one:
+        id: 1
+        email: jsmith@blah.com
+        password: password
+        status: 1
+        created_at: <%= Time.now %>
+        updated_at: <%= Time.now %>
+
+A file containing this would define a single record made up of 6 fields.
+The first line specifies the record name and isn't really relevant except
+in that it must be unique within the file that defines it. Note that the
+fixture files are run through ERB as part of the load process so it's
+possible to include simple Ruby statements into the definitions. In the
+example above Ruby code is used to generate values for the created_at
+and updated_at field values.
+
+## Advanced Usage
+The Squixtures library makes a set of assumptions to attempt to ease the
+process of using fixtures. For example, the library assumes that a database.yml
+file can be found and that fixtures will be loaded into the test database
+specified in the database configuration. This is convenient but facilities
+have also been provided to work around these assumptions.
+
+To change the database configuration entry that the library will use you can
+change the environment setting for Squixtures by executing a line like the
+following before performing any fixtures loads...
+
+   Squixtures.environment = "development"
+
+If you want to alter the location that the Squixtures library obtains fixture
+files from you can do so with a line such as the following...
+
+   Squixtures.fixtures_dir = "/my/fixtures/directory"
+
+By default Squixtures does not make use of transactions when loading fixtures.
+You can specifying the use of transactions on a per fixture basis with a line
+such as the following...
+
+   Squixtures.transactional = true
+
+## Platform Independence
+The Sequel library has been used in minimize the amount of RDBMS specific code
+exists in the library. Unfortunately, it's impossible to be complete free of
+such considerations. There are two main areas where the underlying database
+system impinges on the code...
+
+    * Database connections. The Sequel library requires a URL like string to
+      obtain a database connection. The form and content of this string are
+      very much dictated by the underlying database.
+
+    * Referential integrity. Database systems which enforce strict referential
+      integrity can make the injection of fixtures more difficult, especially
+      in the case where the data model has circular references. This can, in
+      part, be avoided by proper ordering of the fixtures load. This is not
+      a complete solution however and the Squixtures library takes steps to
+      deactivate relational integrity temporarily where this will alleviate
+      the issue. Unfortunately the facilities for doing this are very much
+      specific to the database.
+
+At the moment the Squixtures library only supports (i.e. has been tested with)
+the SQLite3 and Postgres databases. Adding support for additional databases
+would require that the library be extended to accommodate the specified database
+in the areas detailed above.
+
+The approach currently taken to this issue is to provide a database specific
+helper class. These helper classes provide three basic pieces of functionality.
+First they provide a class level function that takes a Hash of database
+connection configuration parameters and generates a connection URL from them.
+Second they provide before and after load functionality that is currently
+intended to be the location where referential integrity is deactivate on the
+appropriate table prior to the data load. There are currently two such classes
+defined in the library - PostgresHelper and SQLite3Helper.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/squixtures.rb

@@ -0,0 +1,170 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2012 Peter Wood
+
+require "logjam"
+require "sequel"
+require "stringio"
+require "squixtures/version"
+require "squixtures/exceptions"
+require "squixtures/fixture"
+require "squixtures/fixtures"
+require "squixtures/loader"
+require "squixtures/postgres_helper"
+require "squixtures/sqlite3_helper"
+require "squixtures/helper_factory"
+
+module Squixtures
+   # Definition of the default fixtures directory.
+   DEFAULT_FIXTURES_DIR                = "#{Dir.getwd}/test/fixtures"
+
+    # Definition for the default database configuration file name.
+   DEFAULT_DATABASE_CFG_FILE           = "database.yml"
+
+   # Definition of the default configuration search paths.
+   DEFAULT_CFG_SEARCH_PATHS            = ["#{Dir.getwd}/config",
+                                          "#{Dir.getwd}/test/fixtures",
+                                          Dir.getwd]
+
+   # Definition of the fixtures search paths.
+   FIXTURES_SEARCH_PATHS               = ["#{Dir.getwd}/test/fixtures",
+                                          "#{Dir.getwd}/fixtures"]
+
+   # Definition of the configuration defaults.
+   CONFIGURATION_DEFAULTS              = {:clear_tables  => true,
+                                          :database      => nil,
+                                          :environment   => "test",
+                                          :search_paths  => DEFAULT_CFG_SEARCH_PATHS,
+                                          :transactional => false}
+
+   # Module configuration store.
+   @@configuration                     = {}.merge(CONFIGURATION_DEFAULTS)
+
+   # This method performs the actual configuration and load of a set of
+   # fixtures.
+   #
+   # ==== Parameters
+   # *names::  The list of fixture names to be loaded.
+   def self.fixtures(*names)
+      load_database_configuration if !@@configuration[:database]
+      Loader.new(@@configuration).load(*names)
+   end
+
+   # This method allows the configuration of the Squixtures module.
+   def self.configuration=(configuration)
+      @@configuration = CONFIGURATION_DEFAULTS.merge(configuration)
+   end
+
+   # This method fetches configuration associated with the Squixtures module.
+   # Note that, due to the late loading of the database configuration, the
+   # connection details will not be available until after a load.
+   def self.configuration
+      @@configuration
+   end
+
+   # This method is used to set the environment that the Squixtures module
+   # will use when loading fixtures. Note that calling this method will also
+   # invoke an immediate reload of database adapter/connection details.
+   #
+   # ==== Parameters
+   # setting::  A String, usually one of "test", "development" or "production"
+   #            but can be anything else as long as it matches an entry in the
+   #            database configuration settings.
+   def self.environment=(setting)
+      @@configuration[:environment] = setting
+      Squixtures.load_database_configuration
+   end
+
+   # This method fetches the current environment setting for the Squixtures
+   # module.
+   def self.environment
+      @@configuration[:environment]
+   end
+
+   # This method provides a means of fetching the path to the directory that
+   # is expected to contain the fixtures files.
+   def self.fixtures_dir
+      @@configuration[:fixtures_dir].nil? ? Squixtures.find_fixtures_dir : @@configuration[:fixtures_dir]
+   end
+
+   # This method allows for the specification of the directory that contains
+   # the fixture files.
+   #
+   # ==== Parameters
+   # path::  The path of the fixtures directory.
+   def self.fixtures_dir=(path)
+      @@configuration[:fixtures_dir] = path
+   end
+
+   # This method provides a means of checking whether transactional fixtures
+   # have been activated in the library.
+   def self.transactional?
+      @@configuration[:transactional]
+   end
+
+   # This method allows the toggling of transactional fixture loading.
+   #
+   # ==== Parameters
+   # setting::  A boolean value indicating whether transactional loading should
+   #            be used with the fixtures.
+   def self.transactional=(setting)
+      @@configuration[:transactional] = setting
+   end
+
+   # This method loads the database configuration details into the current
+   # Squixtures configuration.
+   def self.load_database_configuration
+      log = LogJam.get_logger("squixtures")
+      log.debug "Loading database configuration."
+      success = @@configuration[:search_paths].find do |path|
+         found     = false
+         file_path = "#{path}/#{DEFAULT_DATABASE_CFG_FILE}"
+         log.debug "Checking for the existence of #{file_path}."
+         if File.exist?(file_path)
+            begin
+               log.debug "#{file_path} exists, attempting a load."
+               settings    = YAML.load_file(file_path)
+               environment = @@configuration[:environment]
+               if settings.include?(environment)
+                  @@configuration[:database] = settings[environment]
+                  found = true
+                  log.debug "Database configuration loaded from #{file_path}."
+               else
+                  log.warn "The #{file_path} database configuration does not contain a #{environment} entry."
+               end
+            rescue => error
+               log.warn "Load of the #{file_path} database configuration file failed."
+            end
+         end
+         found
+      end
+
+      if !success
+         raise SquixtureError.new("Unable to locate a database configuration file.")
+      end
+   end
+
+   # This method searches for a directory containing fixtures files, returning
+   # a string with a path to the directory if it's found or nil if it isn't.
+   def self.find_fixtures_dir
+      return @@configuration[:fixtures_dir] if !@@configuration[:fixtures_dir].nil?
+      FIXTURES_SEARCH_PATHS.find do |entry|
+         found = false
+         if File.exist?(entry)
+            found = Dir.glob("#{entry}/*.yml").size > 0
+            @@configuration[:fixtures_dir] = entry if found
+         end
+         found
+      end
+   end
+
+   # This method provides a means of converting a typical set of database
+   # connection settings, such as those in a Rails database.yml file, into
+   # the URL to be used to connect to the database using the Sequel library.
+   #
+   # ==== Parameters
+   # settings::  A Hash of the settings that will be used to generate the
+   #             connection URL.
+   def self.get_connection_url(settings)
+      HelperFactory.create_helper(settings).get_connection_url(settings)
+   end
+end

data/lib/squixtures/exceptions.rb

@@ -0,0 +1,38 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2012 Peter Wood
+
+require 'stringio'
+
+module Squixtures
+   # This class provides the exception class used by the Squixtures library.
+   class SquixtureError < StandardError
+      # Attribute accessor/mutator declarations.
+      attr_accessor :verbose
+
+      # Constructor for the SquixtureError class.
+      #
+      # ==== Parameters
+      # message::  The message to be associated with the error.
+      # cause::    Any underlying exception to be associated with the error.
+      #            Defaults to nil.
+      def initialize(message, cause=nil, verbose=true)
+         super(message)
+         @cause   = cause
+         @verbose = verbose
+      end
+
+      # This method fetches a stringified interpretation of an exception.
+      def to_s()
+         text = StringIO.new
+         text << super
+         if @verbose
+            text << "\n" + self.backtrace.join("\n")
+            if !@cause.nil?
+               text << "\n\nCause: #{@cause}"
+               text << "\n" + @cause.backtrace.join("\n")
+            end
+         end
+         text.string
+      end
+   end
+end

data/lib/squixtures/fixture.rb

@@ -0,0 +1,96 @@
+#! /usr/bin/env ruby
+# Copyright (c), 2012 Peter Wood
+
+require 'erb'
+require 'yaml'
+
+module Squixtures
+   # This class represents a single fixtures and provides the functionality
+   # to load it's contents into the database.
+   class Fixture
+      # Add logging to the class.
+      LogJam.apply(self, 'squixtures')
+
+      # Constructor for the Fixture class.
+      #
+      # ==== Parameters
+      # name::           The name of the fixture. This will be used to work out
+      #                  the fixture file and table names.
+      # configuration::  The configuration to be used by the Fixture.
+      def initialize(name, configuration)
+         @name          = name
+         @configuration = configuration
+      end
+
+      # This method attempts to locate a fixture file, load it's contents and
+      # then insert the details held with the fixture file into the database.
+      #
+      # ==== Parameters
+      # connection::  The database connection to be used to insert the fixture
+      #               details into the database.
+      def load(connection)
+         Fixture.log.debug "Loading the #{@name} fixture."
+         fixture_path = file_path
+         if fixture_path.nil?
+             raise SquixtureError.new("Unable to locate a data file for the #{@name} fixture.")
+         end
+
+         begin
+            Fixture.log.debug "Loading the data for the #{@name} fixture from #{fixture_path}."
+            content = File.open(fixture_path, "r") {|file| file.readlines.join("")}
+            #Fixture.log.debug "Read:\n#{content}"
+            entries = YAML.load(ERB.new(content).result)
+            if entries && entries.size > 0
+               data_set = connection[@name.intern]
+               data_set.delete if @configuration[:clear_tables]
+               entries.each do |key, values|
+                  data_set.insert(convert_values(values))
+               end
+            end
+         rescue => error
+             message = "Load of the #{@name} fixture failed."
+             Fixture.log.error "#{message}\nCause: #{error}\n" + error.backtrace.join("\n")
+             raise SquixtureError.new(message, error)
+         end
+      end
+
+      # This method returns the name of the database table that the fixture
+      # will load data into.
+      def table_name
+         @name.to_s
+      end
+
+      # This method fetches the path and name of the file that the fixture
+      # will load it's data from. This will be nil if a file cannot be located
+      # for the fixture.
+      def file_path
+         path      = nil
+         full_path = "#{@configuration[:fixtures_dir]}/#{@name}.yml"
+         Fixture.log.debug "Checking for the existence of #{full_path}."
+         if !File.exist?(full_path)
+            @configuration[:search_paths].find do |entry|
+                full_path = "#{entry}/#{@name}.yml"
+                Fixture.log.debug "Checking for the existence of #{full_path}."
+                path = full_path if File.exist?(full_path)
+                !path.nil?
+            end
+         else
+            path = full_path
+         end
+         path.nil? ? path : File.expand_path(path)
+      end
+
+      private
+
+      # This method converts a standard string keyed hash into a symbol keyed
+      # one.
+      #
+      # ==== Parameters
+      # input::  The Hash to be converted.
+      def convert_values(input)
+         output = {}
+         input.each {|key, value| output[key.intern] = value} if input
+         output
+      end
+   end
+end