scenic 0.3.0 → 1.0.0

data/lib/generators/scenic/model/templates/model.erb

@@ -1,2 +1,3 @@
-class <%= class_name %> < ActiveRecord::Base
-end
+  def self.refresh
+    Scenic.database.refresh_materialized_view(table_name)
+  end

data/lib/generators/scenic/view/USAGE

@@ -5,6 +5,8 @@ Description:
   If a view of the given name already exists, create a new version of the view
   and a migration to replace the old version with the new.
 
+  To create a materialized view, pass the '--materialized' option.
+
 Examples:
     rails generate scenic:view searches
 

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

@@ -1,5 +1,5 @@
 class <%= migration_class_name %> < ActiveRecord::Migration
   def change
-    create_view :<%= plural_name %>
+    create_view :<%= plural_name %><%= ", materialized: true" if materialized? %>
   end
 end

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

@@ -1,5 +1,12 @@
 class <%= migration_class_name %> < ActiveRecord::Migration
   def change
+  <%- if materialized? -%>
+    update_view :<%= plural_name %>,
+      version: <%= version %>,
+      revert_to_version: <%= previous_version %>,
+      materialized: true
+  <%- else -%>
     update_view :<%= plural_name %>, version: <%= version %>, revert_to_version: <%= previous_version %>
+  <%- end -%>
   end
 end

data/lib/generators/scenic/view/view_generator.rb

@@ -1,10 +1,13 @@
 require "rails/generators"
 require "rails/generators/active_record"
+require "generators/scenic/materializable"
 
 module Scenic
   module Generators
+    # @api private
     class ViewGenerator < Rails::Generators::NamedBase
       include Rails::Generators::Migration
+      include Scenic::Generators::Materializable
       source_root File.expand_path("../templates", __FILE__)
 
       def create_views_directory
@@ -25,12 +28,12 @@ module Scenic
         if creating_new_view? || destroying_initial_view?
           migration_template(
             "db/migrate/create_view.erb",
-            "db/migrate/create_#{plural_file_name}.rb"
+            "db/migrate/create_#{plural_file_name}.rb",
           )
         else
           migration_template(
             "db/migrate/update_view.erb",
-            "db/migrate/update_#{plural_file_name}_to_version_#{version}.rb"
+            "db/migrate/update_#{plural_file_name}_to_version_#{version}.rb",
           )
         end
       end

data/lib/scenic.rb

@@ -1,3 +1,4 @@
+require "scenic/configuration"
 require "scenic/adapters/postgres"
 require "scenic/command_recorder"
 require "scenic/definition"
@@ -7,14 +8,24 @@ require "scenic/statements"
 require "scenic/version"
 require "scenic/view"
 
+# 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.include Scenic::SchemaDumper
+    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
-    Scenic::Adapters::Postgres
+    configuration.database
   end
 end

data/lib/scenic/adapters/postgres.rb

@@ -1,28 +1,95 @@
 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
-    module Postgres
-      def self.views
-        execute(<<-SQL).map { |result| Scenic::View.new(result) }
-          SELECT viewname, definition
+    # 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}.
+    #
+    # @api extension
+    class Postgres
+      # 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
+        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
       end
 
-      def self.create_view(name, sql_definition)
+      # Creates a view in the database.
+      #
+      # @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 #{name} AS #{sql_definition};"
       end
 
-      def self.drop_view(name)
+      # Drops the named view from the database
+      #
+      # @param name The name of the view to drop
+      # @return [void]
+      def drop_view(name)
         execute "DROP VIEW #{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.
+      # @return [void]
+      def create_materialized_view(name, sql_definition)
+        execute "CREATE MATERIALIZED VIEW #{name} AS #{sql_definition};"
+      end
+
+      # Drops a materialized view in the database
+      #
+      # @param name The name of the materialized view to drop.
+      # @return [void]
+      def drop_materialized_view(name)
+        execute "DROP MATERIALIZED VIEW #{name};"
+      end
+
+      # Refreshes a materialized view from its SQL schema.
+      #
+      # @param name The name of the materialized view to refresh..
+      # @return [void]
+      def refresh_materialized_view(name)
+        execute "REFRESH MATERIALIZED VIEW #{name};"
+      end
+
       private
 
-      def self.execute(sql, base = ActiveRecord::Base)
+      def execute(sql, base = ActiveRecord::Base)
         base.connection.execute sql
       end
+
+      def view_from_database(result)
+        Scenic::View.new(
+          name: result["viewname"],
+          definition: result["definition"].strip,
+          materialized: result["materialized"] == "t",
+        )
+      end
     end
   end
 end

data/lib/scenic/command_recorder.rb

@@ -1,6 +1,7 @@
 require "scenic/command_recorder/statement_arguments"
 
 module Scenic
+  # @api private
   module CommandRecorder
     def create_view(*args)
       record(:create_view, args)

data/lib/scenic/command_recorder/statement_arguments.rb

@@ -1,5 +1,6 @@
 module Scenic
   module CommandRecorder
+    # @api private
     class StatementArguments
       def initialize(args)
         @args = args.freeze

data/lib/scenic/configuration.rb

@@ -0,0 +1,37 @@
+module Scenic
+  class Configuration
+    # The Scenic database adapter instance to use when executing SQL.
+    #
+    # Defualts to an instance of [Scenic::Adapters::Postgres]
+    # @return Scenic adapter
+    attr_accessor :database
+
+    def initialize
+      @database = Scenic::Adapters::Postgres.new
+    end
+  end
+
+  # @return [Scenic::Configuration] Scenic's current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Set Scenic's configuration
+  #
+  # @param config [Scenic::Configuration]
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  # Modify Scenic's current configuration
+  #
+  # @yieldparam [Scenic::Configuration] config current Scenic config
+  # ```
+  # Scenic.configure do |config|
+  #   config.database = Scenic::Adapters::Postgres
+  # end
+  # ```
+  def self.configure
+    yield configuration
+  end
+end

data/lib/scenic/definition.rb

@@ -1,4 +1,5 @@
 module Scenic
+  # @api private
   class Definition
     def initialize(name, version)
       @name = name
@@ -8,7 +9,7 @@ module Scenic
     def to_sql
       File.read(full_path).tap do |content|
         if content.empty?
-          raise "Define view query in #{@path} before migrating."
+          raise "Define view query in #{path} before migrating."
         end
       end
     end

data/lib/scenic/railtie.rb

@@ -1,6 +1,10 @@
 require "rails/railtie"
 
 module Scenic
+  # Automatically initializes Scenic in the context of a Rails application when
+  # ActiveRecord is loaded.
+  #
+  # @see Scenic.load
   class Railtie < Rails::Railtie
     initializer "scenic.load" do
       ActiveSupport.on_load :active_record do

data/lib/scenic/schema_dumper.rb

@@ -1,13 +1,10 @@
 require "rails"
 
 module Scenic
+  # @api private
   module SchemaDumper
-    extend ActiveSupport::Concern
-
-    included { alias_method_chain :tables, :views }
-
-    def tables_with_views(stream)
-      tables_without_views(stream)
+    def tables(stream)
+      super
       views(stream)
     end
 

data/lib/scenic/statements.rb

@@ -1,27 +1,27 @@
 module Scenic
+  # Methods that are made available in migrations for managing Scenic views.
   module Statements
-    # Public: Create a new database view.
+    # Create a new database view.
     #
-    # name - A string or symbol containing the singular name of the database
-    #        view. Cannot conflict with any other view or table names.
-    # version - The version number of the view. If present, will be used to find
-    #           the definition file in db/views in the form db/views/[pluralized
-    #           name]_v[2 digit zero padded version].sql.
-    #           Example: db/views/searches_v02.sql.
-    # sql_definition - A string containing the SQL definition of the view. If
-    #                  both sql_definition and version are provided,
-    #                  sql_definition takes prescedence.
-    #
-    # Examples
+    # @param name [String, Symbol] The name of the database view.
+    # @param version [Fixnum] The version number of the view, used to find the
+    #   definition file in `db/views`. This defaults to `1` if not provided.
+    # @param sql_definition [String] The SQL query for the view schema. If both
+    #   `sql_defintiion` and `version` are provided, `sql_definition` takes
+    #   prescedence.
+    # @param materialized [Boolean] Set to true to create a materialized view.
+    #   Defaults to false.
+    # @return The database response from executing the create statement.
     #
+    # @example Create from `db/views/searches_v02.sql`
     #   create_view(:searches, version: 2)
     #
+    # @example Create from provided SQL string
     #   create_view(:active_users, sql_definition: <<-SQL)
     #     SELECT * FROM users WHERE users.active = 't'
     #   SQL
     #
-    # Returns the database response from executing the CREATE VIEW statement.
-    def create_view(name, version: 1, sql_definition: nil)
+    def create_view(name, version: 1, sql_definition: nil, materialized: false)
       if version.blank? && sql_definition.nil?
         raise(
           ArgumentError,
@@ -31,48 +31,68 @@ module Scenic
 
       sql_definition ||= definition(name, version)
 
-      Scenic.database.create_view(name, sql_definition)
+      if materialized
+        Scenic.database.create_materialized_view(name, sql_definition)
+      else
+        Scenic.database.create_view(name, sql_definition)
+      end
     end
 
-    # Public: Drop a database view by name.
-    #
-    # name - A string or symbol containing the singular name of the database
-    #        view. Must be an existing view.
-    # revert_to_version - Used to revert the drop_view command in the
-    #                     db:rollback rake task, which would pass the version
-    #                     number to create_view. Usually the most recent
-    #                     version.
+    # Drop a database view by name.
     #
-    # Example
+    # @param name [String, Symbol] The name of the database view.
+    # @param revert_to_version [Fixnum] Used to reverse the `drop_view` command
+    #   on `rake db:rollback`. The provided version will be passed as the
+    #   `version` argument to {#create_view}.
+    # @param materialized [Boolean] Set to true if dropping a meterialized view.
+    #   defaults to false.
+    # @return The database response from executing the drop statement.
     #
-    #   drop_view(:users_who_recently_logged_in, 3)
+    # @example Drop a view, rolling back to version 3 on rollback
+    #   drop_view(:users_who_recently_logged_in, revert_to_version: 3)
     #
-    # Returns the database response from executing the DROP VIEW statement.
-    def drop_view(name, revert_to_version: nil)
-      Scenic.database.drop_view(name)
+    def drop_view(name, revert_to_version: nil, materialized: false)
+      if materialized
+        Scenic.database.drop_materialized_view(name)
+      else
+        Scenic.database.drop_view(name)
+      end
     end
 
-    # Public: Update a database view to a new version by first dropping the
-    # previous version then creating the new version.
+    # Update a database view to a new version.
     #
-    # name - A string or symbol containing the singular name of the database
-    #        view. Must be an existing view.
-    # version - The version number of the view. See create_view for details.
-    # revert_to_version - The version to revert to for db:rollback. Usually the
-    #                     previous version. See drop_view for details.
+    # The existing view is dropped and recreated using the supplied `version`
+    # parameter.
     #
-    # Example
+    # @param name [String, Symbol] The name of the database view.
+    # @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.
+    # @return The database response from executing the create statement.
     #
-    #   update_view(:engagement_reports, version: 3, revert_to_version: 2)
+    # @example
+    #   update_view :engagement_reports, version: 3, revert_to_version: 2
     #
-    # Returns the database response from executing the CREATE VIEW statement.
-    def update_view(name, version: nil, revert_to_version: nil)
+    def update_view(name, version: nil, revert_to_version: nil, materialized: false)
       if version.blank?
         raise ArgumentError, "version is required"
       end
 
-      drop_view(name, revert_to_version: revert_to_version)
-      create_view(name, version: 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."
+      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 = "0.3.0"
+  VERSION = "1.0.0"
 end

data/lib/scenic/view.rb

@@ -1,24 +1,56 @@
 module Scenic
+  # The in-memory representation of a view definition.
+  #
+  # **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 View
-    attr_reader :name, :definition
+    # The name of the view
+    # @return [String]
+    attr_reader :name
+
+    # The SQL schema for the query that defines the view
+    # @return [String]
+    #
+    # @example
+    #   "SELECT name, email FROM users UNION SELECT name, email FROM contacts"
+    attr_reader :definition
+
+    # True if the view is materialized
+    # @return [Boolean]
+    attr_reader :materialized
+
+    # @api private
     delegate :<=>, to: :name
 
-    def initialize(view_row)
-      @name = view_row["viewname"]
-      @definition = view_row["definition"].strip
+    # Returns a new instance of View.
+    #
+    # @param name [String] The name of the view.
+    # @param definition [String] The SQL for the query that defines the view.
+    # @param materialized [String] `true` if the view is materialized.
+    def initialize(name:, definition:, materialized:)
+      @name = name
+      @definition = definition
+      @materialized = materialized
     end
 
+    # @api private
     def ==(other)
       name == other.name &&
-        definition == other.definition
+        definition == other.definition &&
+        materialized == other.materialized
     end
 
+    # @api private
     def to_schema
-      <<-DEFINITION.strip_heredoc
-        create_view :#{name}, sql_definition:<<-\SQL
-          #{definition}
-        SQL
+      materialized_option = materialized ? "materialized: true, " : ""
+      <<-DEFINITION
 
+  create_view :#{name}, #{materialized_option} sql_definition: <<-\SQL
+    #{definition.indent(2)}
+  SQL
       DEFINITION
     end
   end