scenic 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e917734f36443e8d261a50f8bcef5c5e65eeebda
-  data.tar.gz: d013d537a689625087039b4d6cb2e54a584c73ca
+  metadata.gz: aad0218a7caab0f7bb48d964a0b2fb7b45d3da68
+  data.tar.gz: 567bf836c969e9a5287a19c10a5dcd40b9a0d03d
 SHA512:
-  metadata.gz: be0c588362c95ab41cf71670954569c6c06e8ff7e7ef5b2a27b23b32eb61dc86ea8e13e3a969c7596ca9d55a86d2f8c9999486ecfdcac025dc70cbca81cddbb7
-  data.tar.gz: d1b4171587355aef488df5ebc9d998da4eaa690baf3e8aad2a6ca9ab6db1b11a4bbe1ac07c43c2c9305b5761b43d24298c983cdf1129e795488d1b035cb0daf8
+  metadata.gz: 57c9ba2f5803667e7f256730881e75f95ffa113b6a75d3cb94b1ef884d9e258a26c696697840a4118a88ba010fb759d339e2c89f30a903ad967e700aeb227690
+  data.tar.gz: bb6f28f0b4a24ac0e737c98fe4081e4f2a67bf9205bf89701a4deb2d1fc7ccdb1bc5d4fe5d52a002b5cc4f99154ff64d7906ea53ccd49f2e420a87c96f5bce31

data/.travis.yml

@@ -1,19 +1,21 @@
+addons:
+  postgresql: "9.3"
 before_install:
   - "echo '--colour' > ~/.rspec"
   - "echo 'gem: --no-document' > ~/.gemrc"
   - git config --global user.name 'Travis CI'
   - git config --global user.email 'travis-ci@example.com'
-before_script:
-  - pushd spec/dummy && bundle exec rake db:create && mkdir db/views && popd
 branches:
   only:
     - master
+install:
+  - travis_retry bin/setup
 language:
   - ruby
 notifications:
   email:
     - false
 rvm:
-  - 2.1.5
-  - 2.2.0
+  - 2.1.7
+  - 2.2.3
 sudo: false

data/.yardopts

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

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+We love pull requests 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
+
+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
+
+1. For 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.
+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.
+
+[style guide]: https://github.com/thoughtbot/guides/tree/master/style
+[good commit message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+Others will give constructive feedback.  This is a time for discussion and
+improvements, and making the necessary changes will be required before we can
+merge the contribution.

data/LICENSE.txt

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

data/NEWS.md

@@ -1,12 +1,64 @@
-New in 0.3.0 (January 23, 2015)
-* Previous view definition is copied into new view definition file when updating
+# News
+
+The noteworthy changes for each Scenic version are included here. For a complete
+changelog, see the [CHANGELOG] for each version via the version links.
+
+[CHANGELOG]: https://github.com/thoughtbot/scenic/commits/master
+
+## [1.0.0] - November 23, 2015
+
+### Added
+- Added support for [materialized views].
+- Allow changing the database adapter via `Scenic::Configuration`.
+
+### Fixed
+- Improved formatting of the view when dumped to `schema.rb`.
+- Fixed generation of namespaced models by using ActiveRecord's own model
+  generator.
+- Eliminated `alias_method_chain` deprecation when running with Rails master
+  (5.0).
+
+[materialized views]:https://github.com/thoughtbot/scenic/blob/v1.0.0/README.md
+[1.0.0]: https://github.com/thoughtbot/scenic/compare/v0.3.0...v1.0.0
+
+## [0.3.0] - January 23, 2015
+
+### Added
+- Previous view definition is copied into new view definition file when updating
   an existing view.
-* We avoid dumping views that belong to Postgres extensions
-* `db/schema.rb` is prettier thanks to a blank line after each view definition.
 
-New in 0.2.1
-* View generator will now create `db/views` directory if necessary
+### Fixed
+- We avoid dumping views that belong to Postgres extensions.
+- `db/schema.rb` is prettier thanks to a blank line after each view definition.
+
+[0.3.0]: https://github.com/thoughtbot/scenic/compare/v0.2.1...v0.3.0
+
+## [0.2.1] - January 5, 2015
+
+### Fixed
+- View generator will now create `db/views` directory if necessary.
+
+[0.2.1]: https://github.com/thoughtbot/scenic/compare/v0.2.0...v0.2.1
+
+## [0.2.0] - August 11, 2014
+
+### Added
+- Teach view generator to update existing views.
+
+### Fixed
+- Raise an error if view definition is empty.
+
+[0.2.0]: https://github.com/thoughtbot/scenic/compare/v0.1.0...v0.2.0
+
+## [0.1.0] - August 4, 2014
+
+Scenic makes it easier to work with Postgres views in Rails.
+
+It introduces view methods to ActiveRecord::Migration and allows views to be
+dumped to db/schema.rb.  It provides generators for models, view definitions,
+and migrations.  It is built around a basic versioning system for view
+definition files.
+
+In short, go add a view to your app.
 
-New in 0.2.0
-* Teach view generator to update existing views [683361d](https://github.com/thoughtbot/scenic/commit/683361d59410f46aba508a3ceb850161dd0be027)
-* Raise an error if view definition is empty. [PR #38](https://github.com/thoughtbot/scenic/issues/38)
+[0.1.0]: https://github.com/thoughtbot/scenic/compare/8599daa132880cd6c07efb0395c0fb023b171f47...v0.1.0

data/README.md

@@ -1,27 +1,34 @@
 # Scenic
 
-![Boston cityscape - it's scenic](http://www.california-tour.com/blog/wp-content/uploads/2011/11/skyline-boats-shutterstock-superreduced.jpg)
+Scenic adds methods to `ActiveRecord::Migration` to create and manage database
+views in Rails.
 
-**Scenic (v0.2.0) is in an early stage of development. While it hasn't been
-tested in an actual application, we are relatively confident in its readiness
-and value, and stand ready to help resolve any issues it may have**
+Using Scenic, you can bring the power of SQL views to your Rails application
+without having to switch your schema format to SQL. Scenic provides a convention
+for versioning views that keeps your migration history consistent and reversible
+and avoids having to duplicate SQL strings across migrations. As an added bonus,
+you define the structure of your view in a SQL file, meaning you get full SQL
+syntax highlighting in the editor of your choice and can easily test your SQL in
+the database console during development.
 
-## Description
+Scenic ships with support for PostgreSQL. The adapter is configurable (see
+`Scenic::Configuration`) and has a minimal interface (see
+`Scenic::Adapters::Postgres`) that other gems can provide.
 
-Scenic adds methods to ActiveRecord::Migration to create and manage database
-views in Rails.
+## Great, how do I create a view?
 
-Using Scenic, you can use the power of SQL views in your Rails application
-without having to switch your schema format to SQL. Scenic also handles
-versioning your views in a way that eliminates duplication across migrations. As
-an added bonus, you define the structure of your view in a SQL file, meaning you
-get full SQL syntax highlighting support in the editor of your choice.
+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
+following command:
 
-## Great, how do I create a view?
+```sh
+$ rails generate scenic:view searches
+      create  db/views/searches_v01.sql
+      create  db/migrate/[TIMESTAMP]_create_searches.rb
+```
 
-You've got this great idea for a view you'd like to call `searches`. Create a
-definition file at `db/views/searches_v01.sql` which contains the query you'd
-like to build your view with. Perhaps that looks something like this:
+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:
 
 ```sql
 SELECT
@@ -40,34 +47,37 @@ SELECT
 FROM statuses
 ```
 
-Generate a new migration with the following `change` method:
+The generated migration will contain a `create_view` statement. Run the
+migration, and [baby, you got a view going][carl]. The migration is reversible
+and the schema will be dumped into your `schema.rb` file.
 
-```ruby
-def change
-  create_view :searches
-end
-```
+[carl]: https://www.youtube.com/watch?v=Sr2PlqXw03Y
 
-Run that migration and congrats, you've got yourself a view. The migration is
-reversible and it will be dumped into your `schema.rb` file.
+```sh
+$ rake db:migrate
+```
 
 ## Cool, but what if I need to change that view?
 
-Add the new query to `db/views/searches_v02.sql` and generate a new migration with
-the following `change` method:
+Here's where Scenic really shines. Run that same view generator once more:
 
-```ruby
-def change
-  update_view :searches, version: 2, revert_to_version: 1
-end
+```sh
+$ rails generate scenic:view searches
+      create  db/views/searches_v02.sql
+      create  db/migrate/[TIMESTAMP]_update_searches_to_version_2.rb
 ```
 
-When you run that migration, your view will be updated. The `revert_to_version`
-option makes that migration reversible.
+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
+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.
 
 ## Can I use this view to back a model?
 
-You bet!
+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
+no different than a table.
 
 ```ruby
 class Search < ActiveRecord::Base
@@ -81,50 +91,76 @@ class Search < ActiveRecord::Base
 end
 ```
 
-## Can you make this easier?
-
-Sure thing. How about some generators?
-
-### Model generator
+Scenic even provides a `scenic:model` generator that is a superset of
+`scenic:view`.  It will act identically to the Rails `model` generator except
+that it will create a Scenic view migration rather than a table migration.
+
+There is no special base class or mixin needed. If desired, any code the model
+generator adds can be removed without worry.
+
+```sh
+$ rails generate scenic:model recent_status
+      invoke  active_record
+      create    app/models/recent_status.rb
+      invoke    test_unit
+      create      test/models/recent_status_test.rb
+      create      test/fixtures/recent_statuses.yml
+      create  db/views/recent_statuses_v01.sql
+      create  db/migrate/20151112015036_create_recent_statuses.rb
+```
 
-The `scenic:model` generator builds you a model, view, and migration from
-scratch. `db/views/[model]_v01.sql` wil be an empty file that you fill in only
-the [query] portion of the view with.
+### When I query that model with `find` I get an error. What gives?
 
-[query]: http://www.postgresql.org/docs/current/static/sql-createview.html
+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
 ```
-$ rails generate scenic:model search
-      create  app/models/search.rb
-      create  db/views/searches_v01.sql
-      create  db/migrate/[TIMESTAMP]_create_searches.rb
-```
-
-### View generator
 
-The `scenic:view` generator is functionally equivalent to `scenic:model` except
-that it doesn't create the model. Convenient.
+## What about materialized views?
 
-```
-$ rails generate scenic:view search
-      create  db/views/searches_v01.sql
-      create  db/migrate/[TIMESTAMP]_create_searches.rb
-```
+Materialized views are essentially SQL queries whose results can be cached to a
+table, indexed, and periodically refreshed when desired. Does Scenic support
+those? Of course!
 
-Subsequent invocations will create updated view versions and update migrations:
+The `scenic:view` and `scenic:model` generators accept a `--materialized`
+option for this purpose. When used with the model generator, your model will
+have the following method defined as a convenience to aid in scheduling
+refreshes:
 
-```
-rails generate scenic:view search
-      create  db/views/searches_v02.sql
-      create  db/migrate/[TIMESTAMP]_update_searches_to_version_2.rb
+```ruby
+def self.refresh
+  Scenic.database.refresh_materialized_view(table_name)
+end
 ```
 
 ## I don't need this view anymore. Make it go away.
 
-We give you `drop_view` too:
+Scenic gives you `drop_view` too:
 
 ```ruby
 def change
   drop_view :searches, revert_to_version: 2
 end
 ```
+
+## About
+
+Scenic is maintained by [Derek Prior] and [Caleb Thompson], funded by
+thoughtbot, inc. The names and logos for thoughtbot are trademarks of
+thoughtbot, inc.
+
+[Derek Prior]: http://prioritized.net
+[Caleb Thompson]: http://calebthompson.io
+
+![thoughtbot](https://thoughtbot.com/logo.png)
+
+We love open source software!  See [our other projects][community] or [hire
+us][hire] to help build your product.
+
+[community]: https://thoughtbot.com/community?utm_source=github
+[hire]: https://thoughtbot.com/hire-us?utm_source=github

data/Rakefile

@@ -7,4 +7,9 @@ task :smoke do
   exec "spec/smoke"
 end
 
+namespace :dummy do
+  require_relative "spec/dummy/config/application"
+  Dummy::Application.load_tasks
+end
+
 task default: [:spec, :smoke]

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+gem install bundler --conservative
+bundle check || bundle install
+bundle exec rake dummy:db:create

data/lib/generators/scenic/generators.rb

@@ -0,0 +1,11 @@
+module Scenic
+  # Scenic provides generators for creating and updating views and ActiveRecord
+  # 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}
+  module Generators
+  end
+end

data/lib/generators/scenic/materializable.rb

@@ -0,0 +1,22 @@
+module Scenic
+  module Generators
+    # @api private
+    module Materializable
+      extend ActiveSupport::Concern
+
+      included do
+        class_option :materialized,
+          type: :boolean,
+          required: false,
+          desc: "Makes the view materialized",
+          default: false
+      end
+
+      private
+
+      def materialized?
+        options[:materialized]
+      end
+    end
+  end
+end

data/lib/generators/scenic/model/USAGE

@@ -2,6 +2,8 @@ Description:
   Create a new database view and ActiveRecord::Base subclass for your
   application.
 
+  To create a materialized view, pass the '--materialized' option.
+
 Examples:
     rails generate scenic:model search
 

data/lib/generators/scenic/model/model_generator.rb

@@ -1,19 +1,46 @@
 require "rails/generators"
+require "rails/generators/rails/model/model_generator"
 require "generators/scenic/view/view_generator"
+require "generators/scenic/materializable"
 
 module Scenic
   module Generators
+    # @api private
     class ModelGenerator < Rails::Generators::NamedBase
+      include Scenic::Generators::Materializable
       source_root File.expand_path("../templates", __FILE__)
 
-      check_class_collision
+      def invoke_rails_model_generator
+        invoke "model", [name], options.merge(migration: false)
+      end
 
-      def create_model_file
-        template("model.erb", "app/models/#{file_name}.rb")
+      def inject_model_methods
+        if materialized? && generating?
+          inject_into_class "app/models/#{file_path}.rb", class_name do
+            evaluate_template("model.erb")
+          end
+        end
       end
 
       def invoke_view_generator
-        invoke "scenic:view", [singular_name]
+        invoke "scenic:view", [table_name], options
+      end
+
+      private
+
+      def evaluate_template(source)
+        source  = File.expand_path(find_in_source_paths(source.to_s))
+        context = instance_eval("binding")
+        ERB.new(
+          ::File.binread(source),
+          nil,
+          "-",
+          "@output_buffer",
+        ).result(context)
+      end
+
+      def generating?
+        behavior != :revoke
       end
     end
   end