scenic-jets 1.5.4

data/lib/scenic.rb

@@ -0,0 +1,31 @@
+require "scenic/configuration"
+require "scenic/adapters/postgres"
+require "scenic/command_recorder"
+require "scenic/definition"
+require "scenic/schema_dumper"
+require "scenic/statements"
+require "scenic/version"
+require "scenic/view"
+require "scenic/index"
+
+# Scenic adds methods `ActiveRecord::Migration` to create and manage database
+# views in Rails applications.
+module Scenic
+  # Hooks Scenic into Rails.
+  #
+  # Enables scenic migration methods, migration reversability, and `schema.rb`
+  # dumping.
+  def self.load
+    ActiveRecord::ConnectionAdapters::AbstractAdapter.include Scenic::Statements
+    ActiveRecord::Migration::CommandRecorder.include Scenic::CommandRecorder
+    ActiveRecord::SchemaDumper.prepend Scenic::SchemaDumper
+  end
+
+  # The current database adapter used by Scenic.
+  #
+  # This defaults to {Adapters::Postgres} but can be overridden
+  # via {Configuration}.
+  def self.database
+    configuration.database
+  end
+end

data/lib/scenic/adapters/postgres.rb

@@ -0,0 +1,256 @@
+require_relative "postgres/connection"
+require_relative "postgres/errors"
+require_relative "postgres/index_reapplication"
+require_relative "postgres/indexes"
+require_relative "postgres/views"
+require_relative "postgres/refresh_dependencies"
+
+module Scenic
+  # Scenic database adapters.
+  #
+  # Scenic ships with a Postgres adapter only but can be extended with
+  # additional adapters. The {Adapters::Postgres} adapter provides the
+  # interface.
+  module Adapters
+    # An adapter for managing Postgres views.
+    #
+    # These methods are used interally by Scenic and are not intended for direct
+    # use. Methods that alter database schema are intended to be called via
+    # {Statements}, while {#refresh_materialized_view} is called via
+    # {Scenic.database}.
+    #
+    # The methods are documented here for insight into specifics of how Scenic
+    # integrates with Postgres and the responsibilities of {Adapters}.
+    class Postgres
+      # Creates an instance of the Scenic Postgres adapter.
+      #
+      # This is the default adapter for Scenic. Configuring it via
+      # {Scenic.configure} is not required, but the example below shows how one
+      # would explicitly set it.
+      #
+      # @param [#connection] connectable An object that returns the connection
+      #   for Scenic to use. Defaults to `ActiveRecord::Base`.
+      #
+      # @example
+      #  Scenic.configure do |config|
+      #    config.database = Scenic::Adapters::Postgres.new
+      #  end
+      def initialize(connectable = ActiveRecord::Base)
+        @connectable = connectable
+      end
+
+      # Returns an array of views in the database.
+      #
+      # This collection of views is used by the [Scenic::SchemaDumper] to
+      # populate the `schema.rb` file.
+      #
+      # @return [Array<Scenic::View>]
+      def views
+        Views.new(connection).all
+      end
+
+      # Creates a view in the database.
+      #
+      # This is typically called in a migration via {Statements#create_view}.
+      #
+      # @param name The name of the view to create
+      # @param sql_definition The SQL schema for the view.
+      #
+      # @return [void]
+      def create_view(name, sql_definition)
+        execute "CREATE VIEW #{quote_table_name(name)} AS #{sql_definition};"
+      end
+
+      # Updates a view in the database.
+      #
+      # This results in a {#drop_view} followed by a {#create_view}. The
+      # explicitness of that two step process is preferred to `CREATE OR
+      # REPLACE VIEW` because the former ensures that the view you are trying to
+      # update did, in fact, already exist. Additionally, `CREATE OR REPLACE
+      # VIEW` is allowed only to add new columns to the end of an existing
+      # view schema. Existing columns cannot be re-ordered, removed, or have
+      # their types changed. Drop and create overcomes this limitation as well.
+      #
+      # This is typically called in a migration via {Statements#update_view}.
+      #
+      # @param name The name of the view to update
+      # @param sql_definition The SQL schema for the updated view.
+      #
+      # @return [void]
+      def update_view(name, sql_definition)
+        drop_view(name)
+        create_view(name, sql_definition)
+      end
+
+      # Replaces a view in the database using `CREATE OR REPLACE VIEW`.
+      #
+      # This results in a `CREATE OR REPLACE VIEW`. Most of the time the
+      # explicitness of the two step process used in {#update_view} is preferred
+      # to `CREATE OR REPLACE VIEW` because the former ensures that the view you
+      # are trying to update did, in fact, already exist. Additionally,
+      # `CREATE OR REPLACE VIEW` is allowed only to add new columns to the end
+      # of an existing view schema. Existing columns cannot be re-ordered,
+      # removed, or have their types changed. Drop and create overcomes this
+      # limitation as well.
+      #
+      # However, when there is a tangled dependency tree
+      # `CREATE OR REPLACE VIEW` can be preferable.
+      #
+      # This is typically called in a migration via
+      # {Statements#replace_view}.
+      #
+      # @param name The name of the view to update
+      # @param sql_definition The SQL schema for the updated view.
+      #
+      # @return [void]
+      def replace_view(name, sql_definition)
+        execute "CREATE OR REPLACE VIEW #{quote_table_name(name)} AS #{sql_definition};"
+      end
+
+      # Drops the named view from the database
+      #
+      # This is typically called in a migration via {Statements#drop_view}.
+      #
+      # @param name The name of the view to drop
+      #
+      # @return [void]
+      def drop_view(name)
+        execute "DROP VIEW #{quote_table_name(name)};"
+      end
+
+      # Creates a materialized view in the database
+      #
+      # @param name The name of the materialized view to create
+      # @param sql_definition The SQL schema that defines the materialized view.
+      # @param no_data [Boolean] Default: false. Set to true to create
+      #   materialized view without running the associated query. You will need
+      #   to perform a non-concurrent refresh to populate with data.
+      #
+      # This is typically called in a migration via {Statements#create_view}.
+      #
+      # @raise [MaterializedViewsNotSupportedError] if the version of Postgres
+      #   in use does not support materialized views.
+      #
+      # @return [void]
+      def create_materialized_view(name, sql_definition, no_data: false)
+        raise_unless_materialized_views_supported
+
+        execute <<-SQL
+  CREATE MATERIALIZED VIEW #{quote_table_name(name)} AS
+  #{sql_definition.rstrip.chomp(';')}
+  #{'WITH NO DATA' if no_data};
+        SQL
+      end
+
+      # Updates a materialized view in the database.
+      #
+      # Drops and recreates the materialized view. Attempts to maintain all
+      # previously existing and still applicable indexes on the materialized
+      # view after the view is recreated.
+      #
+      # This is typically called in a migration via {Statements#update_view}.
+      #
+      # @param name The name of the view to update
+      # @param sql_definition The SQL schema for the updated view.
+      # @param no_data [Boolean] Default: false. Set to true to create
+      #   materialized view without running the associated query. You will need
+      #   to perform a non-concurrent refresh to populate with data.
+      #
+      # @raise [MaterializedViewsNotSupportedError] if the version of Postgres
+      #   in use does not support materialized views.
+      #
+      # @return [void]
+      def update_materialized_view(name, sql_definition, no_data: false)
+        raise_unless_materialized_views_supported
+
+        IndexReapplication.new(connection: connection).on(name) do
+          drop_materialized_view(name)
+          create_materialized_view(name, sql_definition, no_data: no_data)
+        end
+      end
+
+      # Drops a materialized view in the database
+      #
+      # This is typically called in a migration via {Statements#update_view}.
+      #
+      # @param name The name of the materialized view to drop.
+      # @raise [MaterializedViewsNotSupportedError] if the version of Postgres
+      #   in use does not support materialized views.
+      #
+      # @return [void]
+      def drop_materialized_view(name)
+        raise_unless_materialized_views_supported
+        execute "DROP MATERIALIZED VIEW #{quote_table_name(name)};"
+      end
+
+      # Refreshes a materialized view from its SQL schema.
+      #
+      # This is typically called from application code via {Scenic.database}.
+      #
+      # @param name The name of the materialized view to refresh.
+      # @param concurrently [Boolean] Whether the refreshs hould happen
+      #   concurrently or not. A concurrent refresh allows the view to be
+      #   refreshed without locking the view for select but requires that the
+      #   table have at least one unique index that covers all rows. Attempts to
+      #   refresh concurrently without a unique index will raise a descriptive
+      #   error.
+      #
+      # @raise [MaterializedViewsNotSupportedError] if the version of Postgres
+      #   in use does not support materialized views.
+      # @raise [ConcurrentRefreshesNotSupportedError] when attempting a
+      #   concurrent refresh on version of Postgres that does not support
+      #   concurrent materialized view refreshes.
+      #
+      # @example Non-concurrent refresh
+      #   Scenic.database.refresh_materialized_view(:search_results)
+      # @example Concurrent refresh
+      #   Scenic.database.refresh_materialized_view(:posts, concurrently: true)
+      #
+      # @return [void]
+      def refresh_materialized_view(name, concurrently: false, cascade: false)
+        raise_unless_materialized_views_supported
+
+        if cascade
+          refresh_dependencies_for(name, concurrently: concurrently)
+        end
+
+        if concurrently
+          raise_unless_concurrent_refresh_supported
+          execute "REFRESH MATERIALIZED VIEW CONCURRENTLY #{quote_table_name(name)};"
+        else
+          execute "REFRESH MATERIALIZED VIEW #{quote_table_name(name)};"
+        end
+      end
+
+      private
+
+      attr_reader :connectable
+      delegate :execute, :quote_table_name, to: :connection
+
+      def connection
+        Connection.new(connectable.connection)
+      end
+
+      def raise_unless_materialized_views_supported
+        unless connection.supports_materialized_views?
+          raise MaterializedViewsNotSupportedError
+        end
+      end
+
+      def raise_unless_concurrent_refresh_supported
+        unless connection.supports_concurrent_refreshes?
+          raise ConcurrentRefreshesNotSupportedError
+        end
+      end
+
+      def refresh_dependencies_for(name, concurrently: false)
+        Scenic::Adapters::Postgres::RefreshDependencies.call(
+          name,
+          self,
+          connection,
+          concurrently: concurrently,
+        )
+      end
+    end
+  end
+end

data/lib/scenic/adapters/postgres/connection.rb

@@ -0,0 +1,57 @@
+module Scenic
+  module Adapters
+    class Postgres
+      # Decorates an ActiveRecord connection with methods that help determine
+      # the connections capabilities.
+      #
+      # Every attempt is made to use the versions of these methods defined by
+      # Rails where they are available and public before falling back to our own
+      # implementations for older Rails versions.
+      #
+      # @api private
+      class Connection < SimpleDelegator
+        # True if the connection supports materialized views.
+        #
+        # Delegates to the method of the same name if it is already defined on
+        # the connection. This is the case for Rails 4.2 or higher.
+        #
+        # @return [Boolean]
+        def supports_materialized_views?
+          if undecorated_connection.respond_to?(:supports_materialized_views?)
+            super
+          else
+            postgresql_version >= 90300
+          end
+        end
+
+        # True if the connection supports concurrent refreshes of materialized
+        # views.
+        #
+        # @return [Boolean]
+        def supports_concurrent_refreshes?
+          postgresql_version >= 90400
+        end
+
+        # An integer representing the version of Postgres we're connected to.
+        #
+        # postgresql_version is public in Rails 5, but protected in earlier
+        # versions.
+        #
+        # @return [Integer]
+        def postgresql_version
+          if undecorated_connection.respond_to?(:postgresql_version)
+            super
+          else
+            undecorated_connection.send(:postgresql_version)
+          end
+        end
+
+        private
+
+        def undecorated_connection
+          __getobj__
+        end
+      end
+    end
+  end
+end

data/lib/scenic/adapters/postgres/errors.rb

@@ -0,0 +1,26 @@
+module Scenic
+  module Adapters
+    class Postgres
+      # Raised when a materialized view operation is attempted on a database
+      # version that does not support materialized views.
+      #
+      # Materialized views are supported on Postgres 9.3 or newer.
+      class MaterializedViewsNotSupportedError < StandardError
+        def initialize
+          super("Materialized views require Postgres 9.3 or newer")
+        end
+      end
+
+      # Raised when attempting a concurrent materialized view refresh on a
+      # database version that does not support that.
+      #
+      # Concurrent materialized view refreshes are supported on Postgres 9.4 or
+      # newer.
+      class ConcurrentRefreshesNotSupportedError < StandardError
+        def initialize
+          super("Concurrent materialized view refreshes require Postgres 9.4 or newer")
+        end
+      end
+    end
+  end
+end

data/lib/scenic/adapters/postgres/index_reapplication.rb

@@ -0,0 +1,71 @@
+module Scenic
+  module Adapters
+    class Postgres
+      # Updating a materialized view causes the view to be dropped and
+      # recreated. This causes any associated indexes to be dropped as well.
+      # This object can be used to capture the existing indexes before the drop
+      # and then reapply appropriate indexes following the create.
+      #
+      # @api private
+      class IndexReapplication
+        # Creates the index reapplication object.
+        #
+        # @param connection [Connection] The connection to execute SQL against.
+        # @param speaker [#say] (ActiveRecord::Migration) The object used for
+        #   logging the results of reapplying indexes.
+        def initialize(connection:, speaker: ActiveRecord::Migration)
+          @connection = connection
+          @speaker = speaker
+        end
+
+        # Caches indexes on the provided object before executing the block and
+        # then reapplying the indexes. Each recreated or skipped index is
+        # announced to STDOUT by default. This can be overridden in the
+        # constructor.
+        #
+        # @param name The name of the object we are reapplying indexes on.
+        # @yield Operations to perform before reapplying indexes.
+        #
+        # @return [void]
+        def on(name)
+          indexes = Indexes.new(connection: connection).on(name)
+
+          yield
+
+          indexes.each(&method(:try_index_create))
+        end
+
+        private
+
+        attr_reader :connection, :speaker
+
+        def try_index_create(index)
+          success = with_savepoint(index.index_name) do
+            connection.execute(index.definition)
+          end
+
+          if success
+            say "index '#{index.index_name}' on '#{index.object_name}' has been recreated"
+          else
+            say "index '#{index.index_name}' on '#{index.object_name}' is no longer valid and has been dropped."
+          end
+        end
+
+        def with_savepoint(name)
+          connection.execute("SAVEPOINT #{name}")
+          yield
+          connection.execute("RELEASE SAVEPOINT #{name}")
+          true
+        rescue
+          connection.execute("ROLLBACK TO SAVEPOINT #{name}")
+          false
+        end
+
+        def say(message)
+          subitem = true
+          speaker.say(message, subitem)
+        end
+      end
+    end
+  end
+end

data/lib/scenic/adapters/postgres/indexes.rb

@@ -0,0 +1,53 @@
+module Scenic
+  module Adapters
+    class Postgres
+      # Fetches indexes on objects from the Postgres connection.
+      #
+      # @api private
+      class Indexes
+        def initialize(connection:)
+          @connection = connection
+        end
+
+        # Indexes on the provided object.
+        #
+        # @param name [String] The name of the object we want indexes from.
+        # @return [Array<Scenic::Index>]
+        def on(name)
+          indexes_on(name).map(&method(:index_from_database))
+        end
+
+        private
+
+        attr_reader :connection
+        delegate :quote_table_name, to: :connection
+
+        def indexes_on(name)
+          connection.execute(<<-SQL)
+            SELECT
+              t.relname as object_name,
+              i.relname as index_name,
+              pg_get_indexdef(d.indexrelid) AS definition
+            FROM pg_class t
+            INNER JOIN pg_index d ON t.oid = d.indrelid
+            INNER JOIN pg_class i ON d.indexrelid = i.oid
+            LEFT JOIN pg_namespace n ON n.oid = i.relnamespace
+            WHERE i.relkind = 'i'
+              AND d.indisprimary = 'f'
+              AND t.relname = '#{name}'
+              AND n.nspname = ANY (current_schemas(false))
+            ORDER BY i.relname
+          SQL
+        end
+
+        def index_from_database(result)
+          Scenic::Index.new(
+            object_name: result["object_name"],
+            index_name: result["index_name"],
+            definition: result["definition"],
+          )
+        end
+      end
+    end
+  end
+end