cassie 1.0.0.beta.33 → 1.0.0.1

data/lib/cassie/schema/structure_dumper.rb

@@ -0,0 +1,117 @@
+module Cassie::Schema
+  require_relative 'queries'
+
+  class StructureDumper
+    attr_reader :destination_path
+
+    def initialize(opts={})
+      @destination_path = opts[:destination_path] || default_destination_path
+    end
+
+    def stream
+      @stream ||= begin
+        prepare_stream
+        File.open(destination_path, "w+")
+      end
+    end
+
+    # Fetch the CQL that can be used to recreate the current environment's keyspace
+    # @return [String] CQL commands
+    # @raise [RuntimeError] if the {Cassie.configuration[:keyspace]} keyspace could not be described.
+    def keyspace_structure
+      @keyspace_structure ||= begin
+        args = ["-e", "'DESCRIBE KEYSPACE #{Cassie.configuration[:keyspace]}'"]
+        runner = Cassie::Support::SystemCommand.new("cqlsh", args)
+        runner.succeed
+
+        runner.output
+      end
+    end
+
+    # Fetch the CQL that can be used to recreat the schema metadata keyspace,
+    # if it has been defined. If it could not be fetched (likely because it doesn't exist),
+    # an empty string is returned.
+    # @return [String] CQL commands
+    def schema_meta_structure
+      @schema_meta_structure ||= begin
+        args = ["-e", "'DESCRIBE KEYSPACE #{Cassie::Schema.schema_keyspace}'"]
+        runner = Cassie::Support::SystemCommand.new("cqlsh", args)
+        runner.run
+
+        if runner.success?
+          runner.output
+        else
+          ""
+        end
+      end
+    end
+
+    def versions
+      @versions ||= begin
+        versions_query.fetch
+      rescue Cassandra::Errors::InvalidError => e
+        log_versions_not_found(e)
+        []
+      end
+    end
+
+    def versions_insert_cql
+      inserts = versions.map do |v|
+        InsertVersionQuery.new(version: v).to_cql
+      end
+      inserts.join("\n")
+    end
+
+    # Dump the CQL for the current environment's keyspace,
+    # the schema metadata keyspace, and the versions rows
+    # that are currently in the schema versions table.
+    def dump
+      stream << keyspace_structure
+      stream << schema_meta_structure
+      stream << "\n\n"
+      stream << versions_insert_cql
+      stream << "\n"
+
+      close_stream
+    end
+
+    def versions_table_name
+      "#{Cassie::Schema.schema_keyspace}.#{Cassie::Schema.versions_table}"
+    end
+
+    def destination_path
+      @destination_path || raise("Unconfigured schema file path: `Cassie::Schema.paths[:schema_file]` is empty")
+    end
+
+    protected
+
+    def versions_query
+      SelectVersionsQuery.new
+    end
+
+    def default_destination_path
+      Cassie::Schema.paths[:schema_file]
+    end
+
+    def prepare_stream
+      dir = File.dirname(destination_path)
+      Dir.mkdir(dir) unless File.directory?(dir)
+    end
+
+    def close_stream
+      stream.close
+      @stream = nil
+    end
+
+    def log_versions_not_found(error)
+      msg = "WARNING: Cassie Schema Versions table not found at '#{versions_table_name}'. Initialize your schema with `cassie schema:init` or `cassie:migrations:import` for versioned migration support."
+      msg << "\n\t- "
+      msg << error.message.split("\n").join("\n\t- ")
+      logger.warn(msg)
+    end
+
+    def logger
+      Cassie.logger
+    end
+  end
+end

data/lib/cassie/{migration → schema}/structure_loader.rb

@@ -1,4 +1,4 @@
-module Cassie::Migration
+module Cassie::Schema
  class StructureLoader
    attr_reader :source_path
 
@@ -9,7 +9,7 @@ module Cassie::Migration
 
   def load
     args = ["-f", source_path]
-    runner = Cassie::Support::CommandRunner.new("cqlsh", args)
+    runner = Cassie::Support::SystemCommand.new("cqlsh", args)
 
     runner.run
     raise runner.failure_message unless runner.success?
@@ -18,7 +18,7 @@ module Cassie::Migration
   protected
 
   def default_source_path
-    Cassie.paths[:schema_structure]
+    Cassie::Schema.paths[:schema_file]
   end
  end
 end

data/lib/cassie/schema/version.rb

@@ -0,0 +1,143 @@
+module Cassie::Schema
+  class Version
+    include Comparable
+    PARTS = [:major, :minor, :patch, :build].freeze
+
+    # The version uuid, if persisted
+    # @return [Cassandra::TimeUuid]
+    attr_accessor :id
+    # The major, minor, patch, and build parts making up the semantic version
+    # @return [Array<Fixnum>]
+    attr_accessor :parts
+    # The description of the changes introduced in this version
+    # @return [String]
+    attr_accessor :description
+    # The OS username of the user that migrated this version up
+    # @return [String]
+    attr_accessor :executor
+    # The time this version was migrated up
+    # @return [DateTime]
+    attr_accessor :executed_at
+
+
+    def initialize(version_number, description=nil, id=nil, executor=nil, executed_at=nil)
+      @parts = build_parts(version_number)
+      @description    = description
+      @id             = id
+      @executor       = executor
+      @executed_at    = executed_at
+    end
+
+    def number
+      parts.join('.')
+    end
+
+    # The major part of the semantic version
+    # @!parse attr_reader :major
+    def major
+      parts[0].to_i
+    end
+
+    # The minor part of the semantic version
+    # @!parse attr_reader :minor
+    def minor
+      parts[1].to_i
+    end
+
+    # The patch part of the semantic version
+    # @!parse attr_reader :patch
+    def patch
+      parts[2].to_i
+    end
+
+    # The build part of the semantic version
+    # @!parse attr_reader :build
+    def build
+      parts[3].to_i
+    end
+
+    # Builds a new version, wiht a version number incremented from this
+    # object's version. Does not propogate any other attributes
+    # @option bump_type [Symbol] :build Bump the build version
+    # @option bump_type [Symbol] :patch Bump the patch version, set build to 0
+    # @option bump_type [Symbol] :minor Bump the minor version, set patch and build to 0
+    # @option bump_type [Symbol] :major Bump the major version, set minor, patch, and build to 0
+    # @option bump_type [nil] nil Default, bumps patch, sets build to 0
+    # @return [Version]
+    def next(bump_type=nil)
+      bump_type ||= :patch
+      bump_index = PARTS.index(bump_type.to_sym)
+
+      # 0.2.1 - > 0.2
+      bumped_parts = parts.take(bump_index + 1)
+      # 0.2 - > 0.3
+      bumped_parts[bump_index] = bumped_parts[bump_index].to_i + 1
+      # 0.3 - > 0.3.0.0
+      bumped_parts += [0]*(PARTS.length - (bump_index + 1))
+      self.class.new(bumped_parts.join('.'))
+    end
+
+    # Compares versions by semantic version number
+    def <=>(other)
+      case other
+      when Version
+        Gem::Version.new(self.number) <=> Gem::Version.new(other.number)
+      when String
+        Gem::Version.new(self.number) <=> Gem::Version.new(other)
+      else
+        nil
+      end
+    end
+    alias :eql? :==
+
+    # @return [Boolean] indicating whether the version has been persisted
+    #   in the schema metatdata versions persistence store.
+    def recorded?
+      !!self.id
+    end
+
+    def hash
+      parts.hash
+    end
+
+    # The migration class name, as implied by the version number
+    # @example 1.2.3
+    #   migration_class_name
+    #   #=> "Migration_1_2_3_0"
+    def migration_class_name
+      "Migration_#{major}_#{minor}_#{patch}_#{build}"
+    end
+
+    # The migration associated with this version
+    # @return [Cassie::Schema::Migration, nil] if the expected migration class is not defined
+    # @!parse attr_reader :migration
+    def migration
+      @migration ||= begin
+        migration_class_name.constantize.new
+      rescue NameError
+        nil
+      end
+    end
+
+    def to_h
+      {
+        id: id,
+        number: number,
+        description: description,
+        executor: executor,
+        executed_at: executed_at
+      }
+    end
+
+    def to_s
+      number
+    end
+
+    protected
+
+    def build_parts(version_number)
+      included = version_number.to_s.split('.').map{|p| p.to_i}
+      included + [0]*(PARTS.length - included.length)
+    end
+  end
+end

data/lib/cassie/schema/version_file_loader.rb

@@ -0,0 +1,34 @@
+require_relative 'version_loader'
+
+module Cassie::Schema
+  class VersionFileLoader < VersionLoader
+
+    def initialize(filename)
+      @filename = filename
+      @version = build_version
+    end
+
+    protected
+
+    def build_version
+      unapplied_version = build_unapplied_version
+
+      # return the applied version if it exists, since it will
+      # have the full and current information about the version
+      # fall back to this unapplied_version if version is not applied
+      Cassie::Schema.applied_versions.find{ |v| v == unapplied_version } || unapplied_version
+    rescue Cassie::Schema::UninitializedError => e
+      # version cannot be applied if cassie schema meta is not initialized
+      unapplied_version
+    end
+
+    def build_unapplied_version
+      matches = File.basename(filename).match(/([0-9_]+)_?(.*).rb$/).captures
+
+      number = matches.first.tr('_','.')
+      description = matches.last.try(:humanize)
+
+      Version.new(number, description)
+    end
+  end
+end

data/lib/cassie/schema/version_loader.rb

@@ -0,0 +1,31 @@
+require 'etc'
+
+module Cassie::Schema
+  class VersionLoader
+    attr_reader :filename, :version
+
+    # Requires the ruby file, thus loading the Migration class into the ObjectSpace.
+    #
+    # @return [Version, Boolean] The Version object if successful. In other words, if
+    #   object representing the version returns a Cassie::Schema::Migration object.
+    #   Otherwise returns false.
+    #
+    # @raise [NameError] if the migration class could not be loaded
+    def load
+      return false unless filename
+      require filename
+
+      begin
+        # ensure the migration class is now defined
+        version.migration_class_name.constantize
+        if version.migration.is_a?(Cassie::Schema::Migration)
+          version
+        else
+          false
+        end
+      rescue NameError
+        raise NameError.new("Expected #{version.migration_class_name} to be defined in #{filename}, but it was not.")
+      end
+    end
+  end
+end

data/lib/cassie/schema/version_object_loader.rb

@@ -0,0 +1,19 @@
+require 'etc'
+require_relative 'version_loader'
+
+module Cassie::Schema
+  class VersionObjectLoader < VersionLoader
+
+    def initialize(version)
+      @version = version
+      @filename = build_filename
+    end
+
+    protected
+
+    def build_filename
+      path = VersionWriter.new(version).existing_file
+      File.absolute_path(path) if path
+    end
+  end
+end

data/lib/cassie/schema/version_writer.rb

@@ -0,0 +1,108 @@
+require 'fileutils'
+
+module Cassie::Schema
+  class VersionWriter
+    attr_reader :io
+    attr_reader :version
+
+    attr_accessor :up_code
+    attr_accessor :down_code
+
+    def initialize(version, io=nil)
+      @io = io
+      @version = version
+      @up_code = default_up_code
+      @down_code = default_down_code
+
+      ensure_dir_exist
+    end
+
+    def write
+      with_io do |io|
+        io << migration_contents
+      end
+    end
+
+    def with_io
+      if io.respond_to?(:<<)
+        yield io
+      else
+        ensure_unique_version
+        File.open(filename, 'w'){ |file| yield file }
+        # load the file, so the definition for source
+        # for the methods will come from that file
+        # instead of (eval)
+        load File.absolute_path(filename)
+      end
+    end
+
+    def migration_contents=(contents)
+      @migration_contents = contents
+    end
+
+    def migration_contents
+      return @migration_contents if defined?(@migration_contents)
+      build_migration_contents
+    end
+
+    def filename
+      "#{directory}/#{basename}"
+    end
+
+    def directory
+      Cassie::Schema.paths["migrations_directory"]
+    end
+
+    def basename
+      "#{version_prefix}#{description_suffix}.rb"
+    end
+
+    def existing_file
+      Dir.glob("#{directory}/#{version_prefix}*.rb").first
+    end
+
+    protected
+
+    def ensure_dir_exist
+      FileUtils.makedirs(directory) unless File.directory?(directory)
+    end
+
+    def ensure_unique_version
+      if existing_file
+        raise IOError.new("A migration already exists for #{version.parts.join('.')} in #{existing_file}. Try bumping the version.")
+      end
+    end
+
+    def build_migration_contents
+      return @migration_contents if defined?(@migration_contents)
+      <<-EOS
+class #{version.migration_class_name} < Cassie::Schema::Migration
+  def up
+    #{up_code}
+  end
+
+  def down
+    #{down_code}
+  end
+end
+      EOS
+    end
+
+    def version_prefix
+      version.parts.map{|p| p.to_s.rjust(4, "0") }.join('_')
+    end
+
+    def description_suffix
+      return nil unless version.description
+      "_" + version.description.parameterize('_')
+    end
+
+    def default_up_code
+      "# Code to execute when applying this migration"
+    end
+
+    def default_down_code
+      "# Code to execute when rolling back this migration"
+    end
+  end
+end

data/lib/cassie/schema/versioning.rb

@@ -0,0 +1,162 @@
+require 'etc'
+require_relative 'migration'
+require_relative 'version_writer'
+require_relative 'version_file_loader'
+require_relative 'version_object_loader'
+require_relative 'migrator'
+
+module Cassie::Schema
+  require_relative 'version'
+
+  class AlreadyInitiailizedError < StandardError; end
+  class UninitializedError < StandardError; end
+
+  module Versioning
+
+    # The current schema version
+    # @return [Version]
+    def version
+      SelectVersionsQuery.new.fetch_first || Version.new('0')
+    rescue Cassandra::Errors::InvalidError
+      raise uninitialized_error
+    end
+
+    # The versions that have been migrated up for the Cassandra database
+    # This lists the versions stored in the persistence layer, in reverse
+    # chronological order (newest first).
+    # @return [Enumerable<Version>]
+    def applied_versions
+      @applied_versions ||= load_applied_versions
+    end
+
+    # Create the keyspace and table for tracking schema versions
+    # in the Cassandra database
+    # @return [void]
+    def initialize_versioning
+      create_schema_keyspace unless keyspace_exists?
+      raise Cassie::Schema::AlreadyInitiailizedError if version_exists?
+      create_versions_table unless versions_table_exists?
+    end
+
+    # Record a version in the schema version store.
+    # This should only be done if the version has been sucesfully migrated
+    # @param [Version] The version to record
+    # @param [Boolean] set_execution_metadata Determines whether or not to populate
+    #   the version object with execution tracking info (+id+, +executed_at+, and +executor+).
+    # @return [Boolean] whether succesfull or not
+    # @raises [StandardError] if version could not be recorded. If this happens,
+    #   execution_metadata will not be preset on the version object.
+    def record_version(version, set_execution_metadata=true)
+      version.id ||= Cassandra::TimeUuid::Generator.new.at(time)
+      if set_execution_metadata
+        time = Time.now
+        version.executed_at = time
+        version.executor = Etc.getlogin rescue '<unknown>'
+      end
+
+      InsertVersionQuery.new(version: version).execute!
+      @applied_versions = nil
+    rescue StandardError
+      version.id = nil
+      version.executed_at = nil
+      version.executor = nil
+    end
+
+    # Remove the version from the schema version store.
+    # This should only be done if the version has been sucesfully reverted
+    # @param [Version] version A persisted version
+    # @return [Boolean] whether succesfull or not
+    def forget_version(version)
+      DeleteVersionQuery.new(id: version.id).execute
+      @applied_versions = nil
+    end
+
+    # Absolute paths to the migration files in the migration directory
+    # @return [Array<String>]
+    def migration_files
+      Dir[root.join(paths["migrations_directory"], "[0-9]*_*.rb")]
+    end
+
+    # Versions for the {#migration_files}
+    # If a migration is applied versions, the object for that
+    # version will be the applied version, containing the full
+    # information about the applied version
+    # @return [Enumeration<Version>]
+    def local_versions
+      @local_versions ||= load_local_versions
+    end
+
+    # A version with an incremented version number that would be
+    # applied after the latest (local or applied) migration.
+    # @param [Symbol, nil] bump_type Which semantic version to bump
+    # @option bump_type [Symbol] :build Bump the build version
+    # @option bump_type [Symbol] :patch Bump the patch version, set build to 0
+    # @option bump_type [Symbol] :minor Bump the minor version, set patch and build to 0
+    # @option bump_type [Symbol] :major Bump the major version, set minor, patch, and build to 0
+    # @option bump_type [nil] nil Default, bumps patch, sets build to 0
+    # @return [Version] The initialized, bumped version
+    def next_version(bump_type=nil)
+      local_max = local_versions.max || Version.new('0')
+      applied_max = applied_versions.max || Version.new('0')
+      max_version  = [local_max, applied_max].max
+      max_version.next(bump_type)
+    end
+
+    protected
+
+    def default_version
+      '0.0.1.0'
+    end
+
+    def keyspace_exists?
+      Cassie.keyspace_exists?(Cassie::Schema.schema_keyspace)
+    end
+
+    # load version migration class from disk
+    def load_applied_versions
+      database_versions.tap do |versions|
+        versions.each{|v| VersionObjectLoader.new(v).load }
+      end
+    rescue Cassandra::Errors::InvalidError
+      raise uninitialized_error
+    end
+
+    def database_versions
+      SelectVersionsQuery.new.fetch
+    end
+
+    def load_local_versions
+      migration_files.map do |filename|
+        VersionFileLoader.new(filename).load
+      end.sort!
+    end
+
+    def version_exists?
+      !!Cassie::Schema.version
+    rescue Cassie::Schema::UninitializedError
+      false
+    end
+
+    def versions_table_exists?
+      !!SelectVersionsQuery.new(limit: 1).fetch
+    rescue Cassandra::Errors::InvalidError
+      false
+    end
+
+    def create_schema_keyspace
+      CreateKeyspaceQuery.new(name: Cassie::Schema.schema_keyspace).execute
+    end
+
+    def create_versions_table
+      CreateVersionsTableQuery.new.execute
+    end
+
+    def uninitialized_error
+      UninitializedError.new(uninitialized_message)
+    end
+
+    def uninitialized_message
+      "Cassie Schema Versions table not found at '#{schema_keyspace}.#{versions_table}'. Enable versioned migration support with `cassie schema:init`."
+    end
+  end
+end

data/lib/cassie/schema.rb

@@ -0,0 +1,24 @@
+module Cassie
+  # Contains interface and components for managing
+  # Cassandra schema using semantically versioned,
+  # incremental migration files.
+  #
+  # * Versioned migration files are stored in-repo in ruby files defining +up+ and +down+ mutation methods.
+  # * Data about what migrations have been applied is stored in Cassandra persistence.
+  # * The schema state is stored in an in-repo schema file that contains the CQL required to recreate the current schema state/version from scratch.
+  # * Various +cassie+ executable commands provide an interface to manage migrations and versioning.
+  #
+  # Run +cassie --help+ to see a list of commands and their descriptions for managing the schema through versioned migrations.
+  #
+  # @see file:lib/cassie/schema/README.md Schema README for information on task usage and the migration DSL.
+  module Schema
+    require_relative 'schema/configuration'
+    require_relative 'schema/versioning'
+
+    extend Configuration
+    extend Versioning
+  end
+
+  require_relative 'schema/structure_dumper'
+  require_relative 'schema/structure_loader'
+end