scenic 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aad0218a7caab0f7bb48d964a0b2fb7b45d3da68
-  data.tar.gz: 567bf836c969e9a5287a19c10a5dcd40b9a0d03d
+  metadata.gz: e1617d9008cabf9f0117f71f812735e8f89bf932
+  data.tar.gz: 31babdfa7c8fc2bc200f9457bc6f8fcab9f16a8e
 SHA512:
-  metadata.gz: 57c9ba2f5803667e7f256730881e75f95ffa113b6a75d3cb94b1ef884d9e258a26c696697840a4118a88ba010fb759d339e2c89f30a903ad967e700aeb227690
-  data.tar.gz: bb6f28f0b4a24ac0e737c98fe4081e4f2a67bf9205bf89701a4deb2d1fc7ccdb1bc5d4fe5d52a002b5cc4f99154ff64d7906ea53ccd49f2e420a87c96f5bce31
+  metadata.gz: aebbd7f6d99c20b35420a68977a4231849543393c01d2a37487cfcde775cc26b33af792d13b61a4618db12dfe4eef0fc0a581ad27a5b76842d4701c0452302db
+  data.tar.gz: 05ea1809e4c4777903a297a9ee1e8c83d59ac3550aa455a82ef2d0e52f0a5f715211ed721e1f425aa87f4d08e7f04c7e7c9b1bec284861ab667e555eefe226c0

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,26 @@
+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
+
+if RUBY_VERSION > "2.2.0"
+  appraise "rails50" do
+    gem "rails", github: "rails/rails"
+    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
+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,55 @@ changelog, see the [CHANGELOG] for each version via the version links.
 
 [CHANGELOG]: https://github.com/thoughtbot/scenic/commits/master
 
+## [1.2.0] - February 5, 2016
+
+### Added
+- The generators now accept namespaced view definitions. For example: `rails
+  generate scenic:view my_app.users`.
+
+### Fixed
+- Materialized view indexes are now properly dumped to `db/schema.rb`. This was
+  an oversight in previous releases, meaning `rake db:schema:load` was missing
+  indexes.
+- Calling `update_view` for a materialized view now properly finds associated
+  indexes for automatic reapplication. An issue in the previous index query was
+  returning no indexes.
+
+**Note**: Dumping materialized view indexes will produce an invalid
+`db/schema.rb` file  under Rails 5 beta 1 and beta 2. This is fixed on Rails
+master.
+
+[1.2.0]: https://github.com/thoughtbot/scenic/compare/v1.1.1...v1.2.0
+
+## [1.1.1] - January 29, 2016
+
+### Fixed
+- Some schema operations were failing with a `PG::ConnectionBad: connection is
+  closed` error. This has been fixed by ensuring we grab a fresh connection for
+  all operations.
+
+[1.1.1]: https://github.com/thoughtbot/scenic/compare/v1.1.0...v1.1.1
+
+## [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,67 @@ 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
+
+**Why do I get an error when querying a view-backed model with `find`, `last`, or `first`?**
+
+ActiveRecord's `find` method expects to query based on your model's primary key,
+but views do not have primary keys. Additionally, the `first` and `last` methods
+will produce queries that attempt to sort based on the primary key.
+
+You can get around these issues by setting the primary key column on your Rails
+model like so:
+
+```ruby
+class People < ActiveRecord::Base
+  self.primary_key = :my_unique_identifier_field
 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,13 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", :github => "rails/rails"
+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/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 %><%= ", materialized: true" if materialized? %>
+    create_view <%= formatted_plural_name %><%= ", materialized: true" if materialized? %>
   end
 end

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

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

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

@@ -56,7 +56,7 @@ module Scenic
 
         def migration_class_name
           if creating_new_view?
-            super
+            "Create#{class_name.gsub('.', '').pluralize}"
           else
             "Update#{class_name.pluralize}ToVersion#{version}"
           end
@@ -85,10 +85,22 @@ module Scenic
         Scenic::Definition.new(plural_file_name, previous_version)
       end
 
+      def plural_file_name
+        @plural_file_name ||= file_name.pluralize.gsub(".", "_")
+      end
+
       def destroying?
         behavior == :revoke
       end
 
+      def formatted_plural_name
+        if plural_name.include?(".")
+          "\"#{plural_name}\""
+        else
+          ":#{plural_name}"
+        end
+      end
+
       def destroying_initial_view?
         destroying? && version == 1
       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
+      # Updatine 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