scenic-cascade 0.1.0

data/README.md

@@ -0,0 +1,95 @@
+# scenic-cascade
+
+[![Ruby](https://github.com/akiomik/scenic-cascade/actions/workflows/ci.yml/badge.svg)](https://github.com/akiomik/scenic-cascade/actions/workflows/ci.yml)
+
+`scenic-cascade` is a [scenic](https://github.com/scenic-views/scenic) migration file generator that supports cascading view updates.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'scenic-cascade'
+```
+
+And then execute:
+
+```shell-session
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell-session
+$ gem install scenic-cascade
+```
+
+## Usage
+
+To generate migration files, use `scenic:view:cascade` generator instead of `scenic:view`.
+The following example generates migration files for `search_results` view.
+
+```shell-session
+$ bin/rails generate scenic:view:cascade search_results
+      create db/views/search_results_v01.sql
+      create db/migrate/20220714233704_create_search_results.rb
+```
+
+## How it works
+
+Consider a situation where the following three views exist:
+
+* `first_results` is a parent view (version 1)
+* `second_results` is a materialized view that depends on `first_results` (version 3)
+* `third_results` is a view that depends on `first_results` and `second_results` (version 2)
+
+```sql
+-- first_results
+SELECT 'foo' AS bar;
+
+-- second_results
+SELECT * FROM first_results;
+
+-- third_results
+SELECT * FROM first_results UNION SELECT * FROM second_results;
+```
+
+Executing the `scenic:view:cascade` generator for `first_results` in this state will generate the following migration file:
+
+```shell-session
+$ bin/rails generate scenic:view:cascade first_results
+      create db/views/first_results_v02.sql
+      create db/migrate/20220714233704_update_first_results_to_version_2.rb
+```
+
+Since all dependencies are described, you can execute `bin/rails db:migrate` without changing the migration file.
+
+> [!WARNING]
+> Currently, index re-creation is not supported.
+> Please change a migration file to recreate indexes if it contains `drop_view` for materialized views.
+
+```ruby
+class UpdateSearchResultsToVersion2 < ActiveRecord::Migration
+  def change
+    drop_view :third_results, revert_to_version: 2, materialized: false
+    drop_view :second_results, revert_to_version: 3, materialized: true
+    replace_view :first_results, version: 2, revert_to_version: 1
+    create_view :second_results, version: 3, materialized: true
+    create_view :third_results, version: 2, materialized: false
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akiomik/scenic-cascade. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/akiomik/scenic-cascade/blob/main/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+Everyone interacting in the `scenic-cascade' project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/akiomik/scenic-cascade/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new('spec:small') do |task|
+  task.rspec_opts = '--tag size:small'
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+desc 'Run `bundle exec steep check`'
+task 'steep:check' do
+  sh 'bundle exec steep check'
+end
+
+task steep: ['steep:check']
+
+task default: %i[spec rubocop steep:check]

data/Steepfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+target :lib
+
+# target :test do
+#   signature "sig", "sig-private"
+#
+#   check "spec"
+# end

data/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.9'
+services:
+  lib:
+    build: .
+    volumes:
+      - .:/scenic-cascade
+    env_file:
+      .env
+    links:
+      - postgres
+  postgres:
+    image: postgres:14-alpine
+    env_file:
+      .env
+    ports:
+      - 5432:5432

data/lib/generators/scenic/view/cascade/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Create a database view migration with re-creating of dependent views.
+
+Example:
+    bin/rails generate scenic:view:cascade search_results
+
+    This will create:
+      db/views/search_results_v01.sql
+      db/migrate/20220714233704_create_search_results.rb
+
+    bin/rails generate scenic:view:cascade search_results
+
+    This will create:
+      db/views/search_results_v02.sql
+      db/migrate/20220714234219_update_search_results_to_version_2.rb

data/lib/generators/scenic/view/cascade/cascade_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'generators/scenic/view/view_generator'
+
+module Scenic
+  module Generators
+    module View
+      # Create a database view migration with re-creating of dependent views
+      class CascadeGenerator < Scenic::Generators::ViewGenerator
+        source_root File.expand_path('templates', __dir__ || '.')
+
+        def create_migration_file
+          if creating_new_view? || destroying_initial_view?
+            migration_template('db/migrate/create_view.rb.erb',
+                               "db/migrate/create_#{plural_file_name}.rb")
+          else
+            migration_template('db/migrate/update_view.rb.erb',
+                               "db/migrate/update_#{plural_file_name}_to_version_#{version}.rb")
+          end
+        end
+
+        private
+
+        def dependents
+          return @dependents if @dependents.present?
+
+          deps = Scenic::Cascade.view_dependents_of(plural_name, recursive: true)
+          @dependents ||= deps.map do |dep|
+            name = dep.from.name
+            version = Scenic::Cascade.find_latest_definition_of(name).version.to_i
+            is_materialized = dep.from.materialized?
+            Scenic::Cascade::ViewWithVersion.new(name: name, version: version, materialized: is_materialized)
+          end.uniq
+        end
+      end
+    end
+  end
+end

data/lib/generators/scenic/view/cascade/templates/db/migrate/create_view.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+    create_view <%= formatted_plural_name %><%= create_view_options %>
+  end
+end

data/lib/generators/scenic/view/cascade/templates/db/migrate/update_view.rb.erb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+  <%- dependents.reverse_each do |dep| -%>
+    drop_view <%= dep.formatted_name %>,
+              revert_to_version: <%= dep.version %>,
+              materialized: <%= dep.materialized? %>
+  <%- end -%>
+
+  <%- if materialized? -%>
+    update_view <%= formatted_plural_name %>,
+      version: <%= version %>,
+      revert_to_version: <%= previous_version %>,
+      materialized: <%= no_data? ? "{ no_data: true }" : true %>
+  <%- else -%>
+    update_view <%= formatted_plural_name %>, version: <%= version %>, revert_to_version: <%= previous_version %>
+  <%- end -%>
+
+  <%- dependents.each do |dep| -%>
+    create_view <%= dep.formatted_name %>,
+                version: <%= dep.version %>,
+                materialized: <%= dep.materialized? %>
+  <%- end -%>
+  end
+end

data/lib/scenic/cascade/definition_finder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'scenic/definition'
+
+module Scenic
+  # Visualize database view dependencies for Scenic
+  module Cascade
+    # Finds view definitions
+    module DefinitionFinder
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Provides class methods to injected class
+      module ClassMethods
+        def find_definitions_of(view_name)
+          go(view_name, 1)
+        end
+
+        def find_latest_definition_of(view_name)
+          latest_definition = find_definitions_of(view_name).last
+          unless latest_definition.nil?
+            # @type var latest_definition: Scenic::Definition
+            return latest_definition
+          end
+
+          raise ArgumentError, "View #{view_name} does not exist"
+        end
+
+        private
+
+        def go(view_name, version)
+          definition = Scenic::Definition.new(view_name, version)
+          return [] unless File.exist?(definition.full_path)
+
+          [definition, *go(view_name, version + 1)]
+        end
+      end
+    end
+  end
+end

data/lib/scenic/cascade/dependency.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'view'
+
+module Scenic
+  module Cascade
+    # Represents a view dependency
+    class Dependency
+      attr_reader :from, :to
+
+      def initialize(from:, to:)
+        raise TypeError unless from.is_a?(Scenic::Cascade::View)
+        raise TypeError unless to.is_a?(Scenic::Cascade::View)
+
+        @from = from
+        @to = to
+      end
+
+      def ==(other)
+        from == other.from && to == other.to
+      end
+
+      # mermaid-like syntax
+      def to_s
+        "#{from.name}[#{from}] --> #{to.name}[#{to}]"
+      end
+
+      alias inspect to_s
+
+      def self.from_hash(hash)
+        from = Scenic::Cascade::View.new(name: hash['from'], materialized: hash['from_materialized'])
+        to = Scenic::Cascade::View.new(name: hash['to'], materialized: hash['to_materialized'])
+        new(from: from, to: to)
+      end
+    end
+  end
+end

data/lib/scenic/cascade/dependency_finder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'dependency'
+
+module Scenic
+  module Cascade
+    # Finds database views which the specified view depends
+    module DependencyFinder
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Provides class methods to injected class
+      module ClassMethods
+        DEPENDENCY_SQL = <<-SQL
+             SELECT DISTINCT
+                    dependee.relname AS to
+                  , dependee.relkind = 'm' AS to_materialized
+                  , depender.relname AS from
+                  , depender.relkind = 'm' AS from_materialized
+               FROM pg_depend d
+               JOIN pg_rewrite r
+                 ON d.objid = r.oid
+               JOIN pg_class AS dependee
+                 ON d.refobjid = dependee.oid
+               JOIN pg_class AS depender
+                 ON r.ev_class = depender.oid
+              WHERE depender.relname = ?
+                AND dependee.relname != depender.relname
+                AND dependee.relkind in ('m', 'v')
+           ORDER BY dependee.relname;
+        SQL
+
+        private_constant :DEPENDENCY_SQL
+
+        def view_dependencies_of(view_name, recursive: false)
+          query = ActiveRecord::Base.sanitize_sql_array([DEPENDENCY_SQL, view_name])
+          raw_dependencies = ActiveRecord::Base.connection.select_all(query).to_a
+          dependencies = raw_dependencies.map { |dep| Scenic::Cascade::Dependency.from_hash(dep) }
+
+          return [] if dependencies.empty?
+          return dependencies unless recursive
+
+          dependencies.flat_map do |dependency|
+            [dependency, *view_dependencies_of(dependency.to.name)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/scenic/cascade/dependent_finder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'dependency'
+
+module Scenic
+  module Cascade
+    # Finds database views that depend on the specified view
+    module DependentFinder
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Provides class methods to injected class
+      module ClassMethods
+        DEPENDANT_SQL = <<-SQL
+             SELECT DISTINCT
+                    dependee.relname AS to
+                  , dependee.relkind = 'm' AS to_materialized
+                  , depender.relname AS from
+                  , depender.relkind = 'm' AS from_materialized
+               FROM pg_depend d
+               JOIN pg_rewrite r
+                 ON d.objid = r.oid
+               JOIN pg_class AS dependee
+                 ON d.refobjid = dependee.oid
+               JOIN pg_class AS depender
+                 ON r.ev_class = depender.oid
+              WHERE dependee.relname = ?
+                AND depender.relname != dependee.relname
+                AND depender.relkind in ('m', 'v')
+           ORDER BY depender.relname;
+        SQL
+
+        private_constant :DEPENDANT_SQL
+
+        def view_dependents_of(view_name, recursive: false)
+          query = ActiveRecord::Base.sanitize_sql_array([DEPENDANT_SQL, view_name])
+          raw_dependencies = ActiveRecord::Base.connection.select_all(query).to_a
+          dependencies = raw_dependencies.map { |dep| Scenic::Cascade::Dependency.from_hash(dep) }
+
+          return [] if dependencies.empty?
+          return dependencies unless recursive
+
+          dependencies.flat_map do |dependency|
+            [dependency, *view_dependents_of(dependency.from.name)]
+          end
+        end
+
+        alias view_dependants_of view_dependents_of
+      end
+    end
+  end
+end

data/lib/scenic/cascade/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Scenic
+  module Cascade
+    VERSION = '0.1.0'
+  end
+end

data/lib/scenic/cascade/view.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Scenic
+  module Cascade
+    # Represents a view
+    class View
+      attr_reader :name
+
+      def initialize(name:, materialized:)
+        raise TypeError unless name.is_a?(String)
+        raise TypeError unless materialized.is_a?(TrueClass) || materialized.is_a?(FalseClass)
+
+        @name = name
+        @materialized = materialized
+      end
+
+      def materialized?
+        @materialized
+      end
+
+      def formatted_name
+        name.include?('.') ? %("#{name}") : ":#{name}"
+      end
+
+      def ==(other)
+        name == other.name && materialized? == other.materialized?
+      end
+
+      def to_s
+        "#{name} (#{materialized? ? 'MV' : 'V'})"
+      end
+
+      alias inspect to_s
+    end
+  end
+end

data/lib/scenic/cascade/view_with_version.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Scenic
+  module Cascade
+    # Represents a view with version
+    class ViewWithVersion < Scenic::Cascade::View
+      attr_reader :version
+
+      def initialize(name:, version:, materialized:)
+        super(name: name, materialized: materialized)
+
+        raise TypeError unless version.is_a?(Integer)
+
+        @version = version
+      end
+
+      def ==(other)
+        name == other.name && version == other.version && materialized? == other.materialized?
+      end
+
+      def to_s
+        "#{name}_v#{formatted_version} (#{materialized? ? 'MV' : 'V'})"
+      end
+
+      alias inspect to_s
+
+      private
+
+      def formatted_version
+        version.to_s.rjust(2, '0')
+      end
+    end
+  end
+end

data/lib/scenic/cascade.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'scenic'
+
+require_relative 'cascade/version'
+require_relative 'cascade/definition_finder'
+require_relative 'cascade/dependency_finder'
+require_relative 'cascade/dependent_finder'
+
+module Scenic
+  # Manage database view dependencies for Scenic
+  module Cascade
+    include Scenic::Cascade::DefinitionFinder
+    include Scenic::Cascade::DependencyFinder
+    include Scenic::Cascade::DependentFinder
+  end
+end

data/manifest.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  - name: pathname