scenic 1.0.0 → 1.2.0

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

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

@@ -0,0 +1,51 @@
+module Scenic
+  module Adapters
+    class Postgres
+      # Fetches defined views from the postgres connection.
+      # @api private
+      class Views
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # All of the views that this connection has defined.
+        #
+        # This will include materialized views if those are supported by the
+        # connection.
+        #
+        # @return [Array<Scenic::View>]
+        def all
+          views_from_postgres.map(&method(:to_scenic_view))
+        end
+
+        private
+
+        attr_reader :connection
+
+        def views_from_postgres
+          connection.execute(<<-SQL)
+            SELECT
+              c.relname as viewname,
+              pg_get_viewdef(c.oid) AS definition,
+              c.relkind AS kind
+            FROM pg_class c
+              LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
+            WHERE
+              c.relkind IN ('m', 'v')
+              AND c.relname NOT IN (SELECT extname FROM pg_extension)
+              AND n.nspname = ANY (current_schemas(false))
+            ORDER BY c.oid
+          SQL
+        end
+
+        def to_scenic_view(result)
+          Scenic::View.new(
+            name: result["viewname"],
+            definition: result["definition"].strip,
+            materialized: result["kind"] == "m",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/scenic/adapters/postgres.rb

@@ -1,3 +1,9 @@
+require_relative "postgres/connection"
+require_relative "postgres/errors"
+require_relative "postgres/index_reapplication"
+require_relative "postgres/indexes"
+require_relative "postgres/views"
+
 module Scenic
   # Scenic database adapters.
   #
@@ -7,14 +13,31 @@ module Scenic
   module Adapters
     # An adapter for managing Postgres views.
     #
-    # **This object is used internally by adapters and the schema dumper and is
-    # not intended to be used by application code. It is documented here for
-    # use by adapter gems.**
-    #
-    # For methods usable in migrations see {Statements}.
+    # 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}.
     #
-    # @api extension
+    # 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.adapter = 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
@@ -22,73 +45,161 @@ module Scenic
       #
       # @return [Array<Scenic::View>]
       def views
-        execute(<<-SQL).map { |result| view_from_database(result) }
-          SELECT viewname, definition, FALSE AS materialized
-          FROM pg_views
-          WHERE schemaname = ANY (current_schemas(false))
-          AND viewname NOT IN (SELECT extname FROM pg_extension)
-          UNION
-          SELECT matviewname AS viewname, definition, TRUE AS materialized
-          FROM pg_matviews
-          WHERE schemaname = ANY (current_schemas(false))
-          ORDER BY viewname
-        SQL
+        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.
+      # @param sql_definition The SQL schema for the view.
+      #
       # @return [void]
       def create_view(name, sql_definition)
-        execute "CREATE VIEW #{name} AS #{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
 
       # 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 #{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.
+      #
+      # 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)
-        execute "CREATE MATERIALIZED VIEW #{name} AS #{sql_definition};"
+        raise_unless_materialized_views_supported
+        execute "CREATE MATERIALIZED VIEW #{quote_table_name(name)} AS #{sql_definition};"
+      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.
+      #
+      # @raise [MaterializedViewsNotSupportedError] if the version of Postgres
+      #   in use does not support materialized views.
+      #
+      # @return [void]
+      def update_materialized_view(name, sql_definition)
+        raise_unless_materialized_views_supported
+
+        IndexReapplication.new(connection: connection).on(name) do
+          drop_materialized_view(name)
+          create_materialized_view(name, sql_definition)
+        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)
-        execute "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.
       #
-      # @param name The name of the materialized view to refresh..
+      # 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, concurrent: true)
+      #
       # @return [void]
-      def refresh_materialized_view(name)
-        execute "REFRESH MATERIALIZED VIEW #{name};"
+      def refresh_materialized_view(name, concurrently: false)
+        raise_unless_materialized_views_supported
+
+        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
 
-      def execute(sql, base = ActiveRecord::Base)
-        base.connection.execute sql
+      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 view_from_database(result)
-        Scenic::View.new(
-          name: result["viewname"],
-          definition: result["definition"].strip,
-          materialized: result["materialized"] == "t",
-        )
+      def raise_unless_concurrent_refresh_supported
+        unless connection.supports_concurrent_refreshes?
+          raise ConcurrentRefreshesNotSupportedError
+        end
       end
     end
   end

data/lib/scenic/configuration.rb

@@ -2,7 +2,7 @@ module Scenic
   class Configuration
     # The Scenic database adapter instance to use when executing SQL.
     #
-    # Defualts to an instance of [Scenic::Adapters::Postgres]
+    # Defualts to an instance of {Adapters::Postgres}
     # @return Scenic adapter
     attr_accessor :database
 
@@ -28,7 +28,7 @@ module Scenic
   # @yieldparam [Scenic::Configuration] config current Scenic config
   # ```
   # Scenic.configure do |config|
-  #   config.database = Scenic::Adapters::Postgres
+  #   config.database = Scenic::Adapters::Postgres.new
   # end
   # ```
   def self.configure

data/lib/scenic/index.rb

@@ -0,0 +1,36 @@
+module Scenic
+  # The in-memory representation of a database index.
+  #
+  # **This object is used internally by adapters and the schema dumper and is
+  # not intended to be used by application code. It is documented here for
+  # use by adapter gems.**
+  #
+  # @api extension
+  class Index
+    # The name of the object that has the index
+    # @return [String]
+    attr_reader :object_name
+
+    # The name of the index
+    # @return [String]
+    attr_reader :index_name
+
+    # The SQL statement that defines the index
+    # @return [String]
+    #
+    # @example
+    #   "CREATE INDEX index_users_on_email ON users USING btree (email)"
+    attr_reader :definition
+
+    # Returns a new instance of Index
+    #
+    # @param object_name [String] The name of the object that has the index
+    # @param index_name [String] The name of the index
+    # @param definition [String] The SQL statements that defined the index
+    def initialize(object_name:, index_name:, definition:)
+      @object_name = object_name
+      @index_name = index_name
+      @definition = definition
+    end
+  end
+end

data/lib/scenic/schema_dumper.rb

@@ -9,17 +9,24 @@ module Scenic
     end
 
     def views(stream)
-      views_in_database.select { |view| !ignored?(view.name) }.each do |view|
-        stream.puts(view.to_schema)
+      if dumpable_views_in_database.any?
+        stream.puts
       end
-    end
 
-    def views_in_database
-      @views_in_database ||= Scenic.database.views.sort
+      dumpable_views_in_database.each do |view|
+        stream.puts(view.to_schema)
+        indexes(view.name, stream)
+      end
     end
 
     private
 
+    def dumpable_views_in_database
+      @dumpable_views_in_database ||= Scenic.database.views.reject do |view|
+        ignored?(view.name)
+      end
+    end
+
     unless ActiveRecord::SchemaDumper.instance_methods(false).include?(:ignored?)
       # This method will be present in Rails 4.2.0 and can be removed then.
       def ignored?(table_name)

data/lib/scenic/statements.rb

@@ -68,10 +68,8 @@ module Scenic
     # @param version [Fixnum] The version number of the view.
     # @param revert_to_version [Fixnum] The version number to rollback to on
     #   `rake db rollback`
-    # @param materialized [Boolean] Must be false. Updating a meterialized view
-    #   causes indexes on it to be dropped. For this reason you should
-    #   explicitly use {#drop_view} followed by {#create_view} and recreate
-    #   applicable indexes. Setting this to `true` will raise an error.
+    # @param materialized [Boolean] True if updating a materialized view.
+    #   Defaults to false.
     # @return The database response from executing the create statement.
     #
     # @example
@@ -82,17 +80,13 @@ module Scenic
         raise ArgumentError, "version is required"
       end
 
+      sql_definition = definition(name, version)
+
       if materialized
-        raise ArgumentError, "Updating materialized views is not supported "\
-          "because it would cause any indexes to be dropped. Please use "\
-          "'drop_view' followed by 'create_view', being sure to also recreate "\
-          "any previously-existing indexes."
+        Scenic.database.update_materialized_view(name, sql_definition)
+      else
+        Scenic.database.update_view(name, sql_definition)
       end
-
-      drop_view name,
-        revert_to_version: revert_to_version,
-        materialized: materialized
-      create_view(name, version: version, materialized: materialized)
     end
 
     private

data/lib/scenic/version.rb

@@ -1,3 +1,3 @@
 module Scenic
-  VERSION = "1.0.0"
+  VERSION = "1.2.0".freeze
 end

data/lib/scenic/view.rb

@@ -22,9 +22,6 @@ module Scenic
     # @return [Boolean]
     attr_reader :materialized
 
-    # @api private
-    delegate :<=>, to: :name
-
     # Returns a new instance of View.
     #
     # @param name [String] The name of the view.
@@ -47,10 +44,10 @@ module Scenic
     def to_schema
       materialized_option = materialized ? "materialized: true, " : ""
       <<-DEFINITION
-
   create_view :#{name}, #{materialized_option} sql_definition: <<-\SQL
     #{definition.indent(2)}
   SQL
+
       DEFINITION
     end
   end

data/lib/scenic.rb

@@ -7,6 +7,7 @@ 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.

data/scenic.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^spec/})
   spec.require_paths = ['lib']
 
+  spec.add_development_dependency 'appraisal'
   spec.add_development_dependency 'bundler', '>= 1.5'
   spec.add_development_dependency 'database_cleaner'
   spec.add_development_dependency 'rake'
@@ -27,9 +28,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pg'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'ammeter', '>= 1.1.3'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'redcarpet'
 
   spec.add_dependency 'activerecord', '>= 4.0.0'
   spec.add_dependency 'railties', '>= 4.0.0'
 
-  spec.required_ruby_version = '~> 2.0'
+  spec.required_ruby_version = '~> 2.1'
 end

data/spec/dummy/config/application.rb

@@ -8,5 +8,8 @@ require "scenic"
 
 module Dummy
   class Application < Rails::Application
+    config.cache_classes = true
+    config.eager_load = false
+    config.active_support.deprecation = :stderr
   end
 end

data/spec/generators/scenic/view/view_generator_spec.rb

@@ -36,4 +36,16 @@ describe Scenic::Generators::ViewGenerator, :generator do
       expect(migration).to contain "materialized: true"
     end
   end
+
+  context "for views created in a schema other than 'public'" do
+    it "creates view definition and migration files" do
+      migration = file("db/migrate/create_non_public_searches.rb")
+      view_definition = file("db/views/non_public_searches_v01.sql")
+
+      run_generator ["non_public.search"]
+
+      expect(migration).to be_a_migration
+      expect(view_definition).to exist
+    end
+  end
 end

data/spec/scenic/adapters/postgres/connection_spec.rb

@@ -0,0 +1,79 @@
+require "spec_helper"
+
+module Scenic
+  module Adapters
+    describe Postgres::Connection do
+      describe "supports_materialized_views?" do
+        context "supports_materialized_views? was defined on connection" do
+          it "uses the previously defined version" do
+            base_response = double("response from base connection")
+            base_connection = double(
+              "Connection",
+              supports_materialized_views?: base_response,
+            )
+
+            connection = Postgres::Connection.new(base_connection)
+
+            expect(connection.supports_materialized_views?).to be base_response
+          end
+        end
+
+        context "supports_materialized_views? is not already defined" do
+          it "is true if postgres version is at least than 9.3.0" do
+            base_connection = double("Connection", postgresql_version: 90300)
+
+            connection = Postgres::Connection.new(base_connection)
+
+            expect(connection.supports_materialized_views?).to be true
+          end
+
+          it "is false if postgres version is less than 9.3.0" do
+            base_connection = double("Connection", postgresql_version: 90299)
+
+            connection = Postgres::Connection.new(base_connection)
+
+            expect(connection.supports_materialized_views?).to be false
+          end
+        end
+      end
+
+      describe "#postgresql_version" do
+        it "uses the public method on the provided connection if defined" do
+          base_connection = Class.new do
+            def postgresql_version
+              123
+            end
+          end
+
+          connection = Postgres::Connection.new(base_connection.new)
+
+          expect(connection.postgresql_version).to eq 123
+        end
+
+        it "uses the protected method if the underlying method is not public" do
+          base_connection = Class.new do
+            protected
+
+            def postgresql_version
+              123
+            end
+          end
+
+          connection = Postgres::Connection.new(base_connection.new)
+
+          expect(connection.postgresql_version).to eq 123
+        end
+      end
+
+      describe "#supports_concurrent_refresh" do
+        it "is true if postgres version is at least 9.4.0" do
+          base_connection = double("Connection", postgresql_version: 90400)
+
+          connection = Postgres::Connection.new(base_connection)
+
+          expect(connection.supports_concurrent_refreshes?).to be true
+        end
+      end
+    end
+  end
+end

data/spec/scenic/adapters/postgres/views_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+module Scenic
+  module Adapters
+    describe Postgres::Views, :db do
+      it "returns scenic view objects for plain old views" do
+        connection = ActiveRecord::Base.connection
+        connection.execute <<-SQL
+          CREATE VIEW children AS SELECT text 'Elliot' AS name
+        SQL
+
+        views = Postgres::Views.new(connection).all
+        first = views.first
+
+        expect(views.size).to eq 1
+        expect(first.name).to eq "children"
+        expect(first.materialized).to be false
+        expect(first.definition).to eq "SELECT 'Elliot'::text AS name;"
+      end
+
+      it "returns scenic view objects for materialized views" do
+        connection = ActiveRecord::Base.connection
+        connection.execute <<-SQL
+          CREATE MATERIALIZED VIEW children AS SELECT text 'Owen' AS name
+        SQL
+
+        views = Postgres::Views.new(connection).all
+        first = views.first
+
+        expect(views.size).to eq 1
+        expect(first.name).to eq "children"
+        expect(first.materialized).to be true
+        expect(first.definition).to eq "SELECT 'Owen'::text AS name;"
+      end
+    end
+  end
+end