tdp 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 87527ee02b194f28bbf5a6a8c642884969b9e9ca
+  data.tar.gz: e19033289f7d1665f3be87e891fba2c14d30f00c
+SHA512:
+  metadata.gz: ef74cbb9f6cffba8d574af1c297c63ca34ce6e890fcacf69f95266992930615a5835f0ec88c4a7c80fb3a42710c73e88d76ffad916d34a29b1458873e6c55402
+  data.tar.gz: 26c3a905c281cdd957138b7b16090b6867b00227048caf44cf6b2b161f54f6bd99af8a58299467045c1bbeb603bb8373d878d4ec2f228fbc4e68750fddba5606

data/bin/tdp

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/tdp'
+
+HELP_BANNER = %(
+Usage: tdp <command> <database url> [<patches #1> [<patches #2> ...]]
+
+where
+  <command> is one of:
+    * bootstrap
+    * upgrade
+    * retrofit
+    * validate_upgradable
+    * validate_compatible
+
+  <database url> is database url, e.g.
+    sqlite://test.db
+    postgres://user:password@host:port/database_name
+
+  <patches #N> is a name of .sql file or a directory with .sql files
+
+).lstrip.freeze
+
+SUPPORTED_COMMANDS = %w(
+  bootstrap upgrade retrofit validate_upgradable validate_compatible
+).freeze
+
+def help
+  puts HELP_BANNER
+  exit(1)
+end
+
+help if ARGV.length < 2
+help unless SUPPORTED_COMMANDS.include? ARGV[0]
+
+begin
+  TDP.execute(ARGV[1], ARGV[2..-1], &ARGV[0].to_sym)
+rescue TDP::NotConfiguredError => e
+  puts e.message
+  exit(1)
+end

data/lib/tdp.rb

@@ -0,0 +1,442 @@
+
+require 'digest'
+require 'sequel'
+
+##
+# Tiny Database Patcher.
+#
+module TDP
+  ##
+  # Raised when there is a record that patch was applied to
+  # the database but the patch itself doesn't exist in the
+  # schema definition.
+  #
+  class NotConfiguredError < RuntimeError
+    ##
+    # * *patch_name* is the name of the patch
+    #
+    def initialize(patch_name)
+      super "No definition file for patch in database: #{patch_name}"
+    end
+  end
+
+  ##
+  # Raised when patch exists in the schema definition but
+  # wasn't applied to the database.
+  #
+  class NotAppliedError < RuntimeError
+    # Problematic patch (a Patch object)
+    attr_reader :patch
+
+    ##
+    # patch :: a problematic patch (a Patch object)
+    #
+    def initialize(patch)
+      super "Patch is not applied: #{patch.name}"
+      @patch = patch
+    end
+  end
+
+  ##
+  # Raised when signature of the patch in database doesn't match
+  # the signature of the patch in schema definition.
+  #
+  class MismatchError < RuntimeError
+    # Problematic patch (a Patch object)
+    attr_reader :patch
+
+    ##
+    # patch :: a problematic patch (a Patch object)
+    #
+    def initialize(patch)
+      super "Applied patch doesn't match definition: #{patch.name}"
+      @patch = patch
+    end
+  end
+
+  ##
+  # Raised when schema definition contains multiple patches
+  # with same name and different content.
+  #
+  class ContradictionError < RuntimeError
+    # Contradicting patches (Patch objects)
+    attr_reader :patches
+
+    ##
+    # patches :: an array of problematic patches (Patch objects)
+    def initialize(patches)
+      super('Patches with same name and different content: ' +
+        patches.map(&:full_filename).join(' / ')
+      )
+      @patches = patches.clone.freeze
+    end
+  end
+
+  ##
+  # A single patch.
+  #
+  class Patch
+    # Content of the patch.
+    attr_reader :content
+
+    # Full name of the patch file.
+    attr_reader :full_filename
+
+    # SHA-256 hash of content.
+    attr_reader :signature
+
+    # Name of the patch.
+    attr_reader :name
+
+    ##
+    # full_filename :: full path to +.sql+ file
+    #
+    def initialize(full_filename)
+      @full_filename = full_filename
+      _, @name = File.split(full_filename)
+      @content = File.read(full_filename)
+      @signature = Digest::SHA256.hexdigest(@content)
+    end
+
+    ##
+    # Returns true if patch is volatile.
+    #
+    def volatile?
+      TDP.volatile_patch_file?(@name)
+    end
+
+    ##
+    # Returns true if patch is permanent.
+    #
+    def permanent?
+      TDP.permanent_patch_file?(@name)
+    end
+
+    ##
+    # Comparison function. Any permanent patch takes precedence
+    # over any volatile one, if both patches are permanent or both
+    # are volatile, ordering is based on name.
+    #
+    def <=>(other)
+      return -1 if permanent? && other.volatile?
+      return 1 if volatile? && other.permanent?
+      @name <=> other.name
+    end
+  end
+
+  ##
+  # A set of patches.
+  #
+  class PatchSet
+    def initialize
+      @patches = {}
+    end
+
+    ##
+    # Adds a patch to the set. Raises ContradictionError in case
+    # if patch set already contains a patch with the same name and
+    # different content.
+    #
+    # patch :: Patch object to add
+    #
+    def <<(patch)
+      known_patch = @patches[patch.name]
+      if known_patch.nil?
+        @patches[patch.name] = patch
+      elsif patch.content != known_patch.content
+        raise ContradictionError, [known_patch, patch]
+      end
+    end
+
+    ##
+    # Calls the given block once for each patch in collection,
+    # passing that element as a parameter.
+    #
+    # Ordering of the patches is: first, all permanent patches
+    # alphanumerically sorted by name, then all volatile patches
+    # sorted in the same way.
+    #
+    def each
+      @patches.values.sort.each { |patch| yield patch }
+    end
+
+    ##
+    # Returns an array of patches for which given block returns
+    # a true value.
+    #
+    # Ordering of patches is same as in #self.each method.
+    #
+    def select
+      @patches.values.sort.select { |patch| yield patch }
+    end
+
+    ##
+    # Retrieves Patch by name. If there's no patch with this
+    # name, returns nil.
+    #
+    def [](name)
+      @patches[name]
+    end
+  end
+
+  ##
+  # Data access object that encapsulates all operations with
+  # the database.
+  class DAO
+    # Sequel::Database object
+    attr_reader :db
+
+    ##
+    # Creates a new DAO object.
+    #
+    # db :: must be either of:
+    # * instance of Sequel::Database class
+    # * database URL that can be passed to Sequel.connect()
+    #
+    def initialize(db)
+      case db
+      when Sequel::Database
+        @db = db
+      when String
+        @db = Sequel.connect(db)
+      else
+        raise ArgumentError, "Invalid argument #{db} of class #{db.class}"
+      end
+    end
+
+    ##
+    # Initializes database tables for keeping track of applied
+    # patches.
+    #
+    def bootstrap
+      return if @db.table_exists?(:tdp_patch)
+      @db << %{
+        CREATE TABLE tdp_patch(
+        name VARCHAR PRIMARY KEY
+        , signature VARCHAR NOT NULL
+        )
+      }
+    end
+
+    ##
+    # Fetches the information about applied patches and
+    # returns it as { name => signature } hash.
+    #
+    def applied_patches
+      result = {}
+      @db[:tdp_patch].select(:name, :signature).each do |row|
+        result[row[:name]] = row[:signature]
+      end
+      result
+    end
+
+    ##
+    # Looks up a signature of a patch by its name.
+    #
+    def patch_signature(name)
+      row = @db[:tdp_patch].select(:signature).where(name: name).first
+      row.nil? ? nil : row[:signature]
+    end
+
+    ##
+    # Applies a patch (a Patch object).
+    #
+    def apply(patch)
+      @db << patch.content
+      register(patch)
+    rescue Sequel::Error => ex
+      raise Sequel::Error,
+            "Failed to apply patch #{patch.full_filename}: #{ex}"
+    end
+
+    ##
+    # Registers a patch (a Patch object) as applied.
+    #
+    def register(patch)
+      q = @db[:tdp_patch].where(name: patch.name)
+      if q.empty?
+        @db[:tdp_patch].insert(
+          name: patch.name,
+          signature: patch.signature
+        )
+      else
+        q.update(signature: patch.signature)
+      end
+    end
+
+    ##
+    # Erases all data about applied patches.
+    #
+    def erase
+      @db[:tdp_patch].delete
+    end
+  end
+
+  ##
+  # Main class of the package.
+  #
+  class Engine
+    ##
+    # Creates a new Engine object.
+    #
+    # db :: must be one of:
+    # * instance of Sequel::Database class
+    # * database URL that can be passed to Sequel.connect()
+    #
+    def initialize(db)
+      @dao = DAO.new(db)
+      @patches = PatchSet.new
+    end
+
+    ##
+    # Registers patch files in the engine.
+    #
+    # filename :: may be either a name of .sql file or a name
+    # of directory (which would be recursively scanned for .sql
+    # files)
+    #
+    def <<(filename)
+      if File.directory?(filename)
+        Dir.foreach(filename) do |x|
+          self << File.join(filename, x) unless x.start_with?('.')
+        end
+      elsif TDP.patch_file?(filename)
+        @patches << Patch.new(filename)
+      end
+    end
+
+    ##
+    # Initializes database tables for keeping track of applied
+    # patches.
+    #
+    def bootstrap
+      @dao.bootstrap
+    end
+
+    ##
+    # Produces an ordered list of patches that need to be applied.
+    #
+    # May raise MismatchError in case if signatures of any permanent
+    # patches that are present in the definition don't match
+    # ones of the patches applied to the database.
+    #
+    def plan
+      @patches.select do |patch|
+        signature = @dao.patch_signature(patch.name)
+        next false if signature == patch.signature
+        next true if signature.nil? || patch.volatile?
+        raise MismatchError, patch
+      end
+    end
+
+    ##
+    # Applies all changes that need to be applied.
+    #
+    def upgrade
+      validate_upgradable
+      plan.each { |patch| @dao.apply(patch) }
+    end
+
+    ##
+    # Validates that it is safe run upgrade the database.
+    # In particular, the following conditions must be met:
+    # * there is an .sql file for every patch that is marked
+    #   as applied to database
+    # * every permanent patch has same signature as the corresponding
+    #   .sql file.
+    #
+    # May raise MismatchError or NotConfiguredError in case if those
+    # conditions aren't met.
+    #
+    def validate_upgradable
+      @dao.applied_patches.each_key do |name|
+        raise NotConfiguredError, name unless @patches[name]
+      end
+      plan
+    end
+
+    ##
+    # Validates that all patches are applied to the database.
+    #
+    # May raise MismatchError, NotConfiguredError or NotAppliedError
+    # in case if there are any problems.
+    #
+    def validate_compatible
+      validate_upgradable
+
+      @patches.each do |patch|
+        signature = @dao.patch_signature(patch.name)
+        next if signature == patch.signature
+        raise NotAppliedError, patch if signature.nil?
+        raise MismatchError, patch
+      end
+    end
+
+    ##
+    # Erases existing data about applied patches and replaces
+    # it with configured schema.
+    #
+    def retrofit
+      @dao.erase
+      @patches.each do |patch|
+        @dao.register(patch)
+      end
+    end
+  end
+
+  ##
+  # Returns true if argument is a valid file name of a permanent
+  # patch.
+  #
+  # To qualify for a permanent patch, file name must start with
+  # a number and end with ".sql" extension.
+  # E.g. _001-initial-schema.sql_ or _201611001_add_accounts_table.sql_
+  #
+  def self.permanent_patch_file?(filename)
+    /^\d+.*\.sql$/ =~ filename
+  end
+
+  ##
+  # Returns true if argument is a valid file name of a volatile
+  # patch.
+  #
+  # To qualify for a volatile patch, file name must end with ".sql"
+  # exception and *NOT* start with a number (otherwise it'd qualify
+  # for permanent patch instead). E.g. _views.sql_
+  # or _stored-procedures.sql_
+  #
+  def self.volatile_patch_file?(filename)
+    /^[^\d]+.*\.sql$/ =~ filename
+  end
+
+  ##
+  # Returns true if argument is a valid file name of a patch.
+  #
+  # To qualify for a patch, file name must end with ".sql"
+  # extension.
+  #
+  def self.patch_file?(filename)
+    filename.end_with?('.sql')
+  end
+
+  ##
+  # Main entrypoint of TDP package.
+  #
+  # Initializes an Engine with given database details and
+  # schema files locations and then calls the given block
+  # passing engine as a parameter.
+  #
+  # db :: must be one of:
+  # * instance of Sequel::Database class
+  # * database URL that can be passed to Sequel.connect()
+  #
+  # *paths* must be an array of names of .sql files and directories
+  # containing those files
+  #
+  def self.execute(db, paths = [])
+    engine = Engine.new(db)
+    paths.each { |x| engine << x }
+    engine.bootstrap
+    yield engine
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: tdp
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ivan Appel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.40'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.40'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: Tool for pure-SQL database migrations
+email: ivan.appel@gmail.com
+executables:
+- tdp
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/tdp
+- lib/tdp.rb
+homepage: http://github.com/geekyfox/tdp
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Tiny Database Patcher
+test_files: []