scenic 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aad0218a7caab0f7bb48d964a0b2fb7b45d3da68
-  data.tar.gz: 567bf836c969e9a5287a19c10a5dcd40b9a0d03d
+  metadata.gz: d42b1d2b3e1f8fd304e1f6ba852a0cc54b6727b6
+  data.tar.gz: 3a84ebfd4b1a34ad03a68f232961c6381107cd74
 SHA512:
-  metadata.gz: 57c9ba2f5803667e7f256730881e75f95ffa113b6a75d3cb94b1ef884d9e258a26c696697840a4118a88ba010fb759d339e2c89f30a903ad967e700aeb227690
-  data.tar.gz: bb6f28f0b4a24ac0e737c98fe4081e4f2a67bf9205bf89701a4deb2d1fc7ccdb1bc5d4fe5d52a002b5cc4f99154ff64d7906ea53ccd49f2e420a87c96f5bce31
+  metadata.gz: e67ff566304f93fd0c70a6c4968d2551ea9a82c3111f9f8a95f4b1dbc4e43a3f7233d9b71fc0551b8ffd806f78c5967bbd43d7b0a3783a80cc1da68b99edd041
+  data.tar.gz: 8b19e9f8e3e93142a57c15ec0f191abeab1278395bb6a09fc9face3908e8039a58cc1704d32cbecb834f966f355a6b98256ed8d2ba0727e4209efe6c83cb52e9

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+gemfiles/*.lock

data/.travis.yml

@@ -1,5 +1,5 @@
 addons:
-  postgresql: "9.3"
+  postgresql: "9.4"
 before_install:
   - "echo '--colour' > ~/.rspec"
   - "echo 'gem: --no-document' > ~/.gemrc"
@@ -15,7 +15,17 @@ language:
 notifications:
   email:
     - false
-rvm:
-  - 2.1.7
-  - 2.2.3
 sudo: false
+rvm:
+  - 2.3.0
+  - 2.2.4
+  - 2.1.8
+gemfile:
+  - gemfiles/rails40.gemfile
+  - gemfiles/rails41.gemfile
+  - gemfiles/rails42.gemfile
+  - gemfiles/rails50.gemfile
+matrix:
+  exclude:
+    - rvm: 2.1.8
+      gemfile: gemfiles/rails50.gemfile

data/.yardopts

@@ -1,5 +1,4 @@
 --hide-api private
---hide-api extension
 --exclude templates
 --markup markdown
 --markup-provider redcarpet

data/Appraisals

@@ -0,0 +1,25 @@
+appraise "rails40" do
+  gem "activerecord", "~> 4.0.0"
+  gem "railties", "~> 4.0.0"
+end
+
+appraise "rails41" do
+  gem "activerecord", "~> 4.1.0"
+  gem "railties", "~> 4.1.0"
+end
+
+appraise "rails42" do
+  gem "activerecord", "~> 4.2.0"
+  gem "railties", "~> 4.2.0"
+end
+
+appraise "rails50" do
+  gem "activerecord", "~> 5.0.0.beta1"
+  gem "railties", "~> 5.0.0.beta1"
+  gem "rspec-rails", github: "rspec/rspec-rails"
+  gem "rspec-support", github: "rspec/rspec-support"
+  gem "rspec-core", github: "rspec/rspec-core"
+  gem "rspec-mocks", github: "rspec/rspec-mocks"
+  gem "rspec-expectations", github: "rspec/rspec-expectations"
+  gem "rspec", github: "rspec/rspec"
+end

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-We love pull requests from everyone.  By participating in this project, you
+We love contributions from everyone.  By participating in this project, you
 agree to abide by the thoughtbot [code of conduct].
 
 [code of conduct]: https://thoughtbot.com/open-source-code-of-conduct
@@ -8,12 +8,13 @@ agree to abide by the thoughtbot [code of conduct].
 We expect everyone to follow the code of conduct anywhere in thoughtbot's
 project codebases, issue trackers, chatrooms, and mailing lists.
 
-## Setting Up for Development
+## Contributing Code
 
-1. For the repository.
+1. Fork the repository.
 2. Run `bin/setup`, which will install dependencies and create the dummy
    application database.
-3. Run `rake` to verify that the tests pass.
+3. Run `bin/appraisal rake` to verify that the tests pass against all
+   supported versions of Rails.
 4. Make your change with new passing tests, following the [style guide].
 5. Write a [good commit message], push your fork, and submit a pull request.
 

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Derek Prior, Caleb Thompson, and thoughtbot.
+Copyright (c) 2014-2016 Derek Prior, Caleb Thompson, and thoughtbot.
 
 MIT License
 

data/NEWS.md

@@ -5,6 +5,26 @@ changelog, see the [CHANGELOG] for each version via the version links.
 
 [CHANGELOG]: https://github.com/thoughtbot/scenic/commits/master
 
+## [1.1.0] - January 8, 2016
+
+### Added
+- Added support for updating materialized view definitions while maintaining
+  existing indexes that are still applicable after the update.
+- Added support for refreshing materialized views concurrently (requires
+  Postgres 9.4 or newer).
+
+### Fixed
+- The schema dumper will now dump views and materialized views together in the
+  order they are returned by Postgres. This fixes issues when loading views that
+  depend on other views via `rake db:schema:load`.
+- Scenic now works on [supported versions of Postgres] older than 9.3.0.
+  Attempts to use database features not supported by your specific version of
+  Postgres will raise descriptive errors.
+- Fixed inability to dump materialized views in Rails 5.0.0.beta1.
+
+[supported versions of Postgres]: http://www.postgresql.org/support/versioning/
+[1.1.0]: https://github.com/thoughtbot/scenic/compare/v1.0.0...v1.1.0
+
 ## [1.0.0] - November 23, 2015
 
 ### Added

data/README.md

@@ -1,5 +1,11 @@
 # Scenic
 
+![Scenic Landscape](https://images.thoughtbot.com/announcing-scenic--versioned-database-views-for-rails/MRUcPsxrTGCeWKyE59Zg_landscape.png)
+
+[![Build Status](https://travis-ci.org/thoughtbot/scenic.svg)](https://travis-ci.org/thoughtbot/scenic)
+[![Code Climate](https://codeclimate.com/repos/53c9736269568066a3000c35/badges/85aa9b19f3037252c55d/gpa.svg)](https://codeclimate.com/repos/53c9736269568066a3000c35/feed)
+[![Documentation Quality](http://inch-ci.org/github/thoughtbot/scenic.svg?branch=master)](http://inch-ci.org/github/thoughtbot/scenic)
+
 Scenic adds methods to `ActiveRecord::Migration` to create and manage database
 views in Rails.
 
@@ -17,18 +23,18 @@ Scenic ships with support for PostgreSQL. The adapter is configurable (see
 
 ## Great, how do I create a view?
 
-You've got this great idea for a view you'd like to call `searches`. You can
-create the migration and the corresponding view definition file with the
+You've got this great idea for a view you'd like to call `search_results`. You
+can create the migration and the corresponding view definition file with the
 following command:
 
 ```sh
-$ rails generate scenic:view searches
-      create  db/views/searches_v01.sql
-      create  db/migrate/[TIMESTAMP]_create_searches.rb
+$ rails generate scenic:view search_results
+      create  db/views/search_results_v01.sql
+      create  db/migrate/[TIMESTAMP]_create_search_results.rb
 ```
 
-Edit the `db/views/searches_v01.sql` file with the SQL statement that defines
-your view. In our example, this might look something like this:
+Edit the `db/views/search_results_v01.sql` file with the SQL statement that
+defines your view. In our example, this might look something like this:
 
 ```sql
 SELECT
@@ -62,13 +68,13 @@ $ rake db:migrate
 Here's where Scenic really shines. Run that same view generator once more:
 
 ```sh
-$ rails generate scenic:view searches
-      create  db/views/searches_v02.sql
-      create  db/migrate/[TIMESTAMP]_update_searches_to_version_2.rb
+$ rails generate scenic:view search_results
+      create  db/views/search_results_v02.sql
+      create  db/migrate/[TIMESTAMP]_update_search_results_to_version_2.rb
 ```
 
-Scenic detected that we already had an existing `searches` view at version 1,
-created a copy of that definition as version 2, and created a migration to
+Scenic detected that we already had an existing `search_results` view at version
+1, created a copy of that definition as version 2, and created a migration to
 update to the version 2 schema. All that's left for you to do is tweak the
 schema in the new definition and run the `update_view` migration.
 
@@ -76,11 +82,13 @@ schema in the new definition and run the `update_view` migration.
 
 You bet! Using view-backed models can help promote concepts hidden in your
 relational data to first-class domain objects and can clean up complex
-ActiveRecord or ARel queries. As far as ActiveRecord is concerned, you a view is
+ActiveRecord or ARel queries. As far as ActiveRecord is concerned, a view is
 no different than a table.
 
 ```ruby
-class Search < ActiveRecord::Base
+class SearchResult < ActiveRecord::Base
+  belongs_to :searchable, polymorphic: true
+
   private
 
   # this isn't strictly necessary, but it will prevent
@@ -109,18 +117,6 @@ $ rails generate scenic:model recent_status
       create  db/migrate/20151112015036_create_recent_statuses.rb
 ```
 
-### When I query that model with `find` I get an error. What gives?
-
-Your view cannot have a primary key, but ActiveRecord's `find` method expects to
-query based on one. You can use `find_by!` or you can explicitly set the primary
-key column on your model like so:
-
-```ruby
-class People < ActiveRecord::Base
-  self.primary_key = :id
-end
-```
-
 ## What about materialized views?
 
 Materialized views are essentially SQL queries whose results can be cached to a
@@ -134,20 +130,64 @@ refreshes:
 
 ```ruby
 def self.refresh
-  Scenic.database.refresh_materialized_view(table_name)
+  Scenic.database.refresh_materialized_view(table_name, concurrently: false)
 end
 ```
 
+This will perform a non-concurrent refresh, locking the view for selects until
+the refresh is complete. You can avoid locking the view by passing
+`concurrently: true` but this requires both PostgreSQL 9.4 and your view to have
+at least one unique index that covers all rows.
+
 ## I don't need this view anymore. Make it go away.
 
 Scenic gives you `drop_view` too:
 
 ```ruby
 def change
-  drop_view :searches, revert_to_version: 2
+  drop_view :search_results, revert_to_version: 2
 end
 ```
 
+## FAQs
+
+**When I query a view-backed model with `find` I get an error. What gives?**
+
+Your view cannot have a primary key, but ActiveRecord's `find` method expects to
+query based on one. You can use `find_by!` or you can explicitly set the primary
+key column on your model like so:
+
+```ruby
+class People < ActiveRecord::Base
+  self.primary_key = :id
+end
+```
+
+**Why is my view missing columns from the underlying table?**
+
+Did you create the view with `SELECT [table_name].*`? Most (possibly all)
+relational databases freeze the view definition at the time of creation. New
+columns will not be available in the view until the definition is updated once
+again. This can be accomplished by "updating" the view to its current definition
+to bake in the new meaning of `*`.
+
+```ruby
+add_column :posts, :title, :string
+update_view :posts_with_aggregate_data, version: 2, revert_to_version: 2
+```
+
+**When will you support MySQL?**
+
+We have no plans to add first-party support for MySQL at this time because we
+(the maintainers) do not currently have a use for it. It's our experience that
+maintaining a library effectively requires regular use of its features. We're
+not in a good position to support MySQL users.
+
+Scenic *does* support configuring different database adapters and should be
+extendable with adapter libraries. If you implement such an adapter, we're happy
+to review and link to it. We're also happy to make changes that would better
+accommodate adapter gems.
+
 ## About
 
 Scenic is maintained by [Derek Prior] and [Caleb Thompson], funded by

data/bin/appraisal

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'appraisal' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('appraisal', 'appraisal')

data/bin/setup

@@ -4,4 +4,9 @@ set -e
 
 gem install bundler --conservative
 bundle check || bundle install
+
+if [ -z "$CI" ]; then
+  bundle exec appraisal install
+fi
+
 bundle exec rake dummy:db:create

data/bin/yard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('yard', 'yard')

data/gemfiles/rails40.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.0.0"
+gem "railties", "~> 4.0.0"
+
+gemspec :path => "../"

data/gemfiles/rails41.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.1.0"
+gem "railties", "~> 4.1.0"
+
+gemspec :path => "../"

data/gemfiles/rails42.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.2.0"
+gem "railties", "~> 4.2.0"
+
+gemspec :path => "../"

data/gemfiles/rails50.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 5.0.0.beta1"
+gem "railties", "~> 5.0.0.beta1"
+gem "rspec-rails", :github => "rspec/rspec-rails"
+gem "rspec-support", :github => "rspec/rspec-support"
+gem "rspec-core", :github => "rspec/rspec-core"
+gem "rspec-mocks", :github => "rspec/rspec-mocks"
+gem "rspec-expectations", :github => "rspec/rspec-expectations"
+gem "rspec", :github => "rspec/rspec"
+
+gemspec :path => "../"

data/lib/generators/scenic/generators.rb

@@ -3,6 +3,7 @@ module Scenic
   # models that are backed by views.
   #
   # See:
+  #
   # * {file:lib/generators/scenic/model/USAGE Model Generator}
   # * {file:lib/generators/scenic/view/USAGE View Generator}
   # * {file:README.md README}

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

@@ -1,3 +1,3 @@
   def self.refresh
-    Scenic.database.refresh_materialized_view(table_name)
+    Scenic.database.refresh_materialized_view(table_name, concurrently: false)
   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/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 The database connection the adapter should use. This
+      #   defaults to `ActiveRecord::Base.connection`
+      #
+      # @example
+      #  Scenic.configure do |config|
+      #    config.adapter = Scenic::Adapters::Postgres.new
+      #  end
+      def initialize(connection = ActiveRecord::Base.connection)
+        @connection = Connection.new(connection)
+      end
+
       # Returns an array of views in the database.
       #
       # This collection of views is used by the [Scenic::SchemaDumper] to
@@ -22,73 +45,157 @@ 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 :connection
+      delegate :execute, :quote_table_name, to: :connection
+
+      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