Scenic Documentation

By default, updating a view drops and recreates it. To update a view in place (using CREATE OR REPLACE VIEW) to preserve dependencies, use the --replace option with the generator. This produces a migration using the replace_view method.

$ rails generate scenic:view search_results --replace

To change a view, run the scenic:view generator again with the same name. Scenic will detect the existing version, create a new versioned SQL file (e.g., _v02.sql), and generate a migration to update the view.

$ rails generate scenic:view search_results

Use the scenic:view generator to create a new view. This generates a versioned SQL definition file in db/views/ and a migration file in db/migrate/.

1. Run the generator: rails generate scenic:view <view_name>
2. Edit the generated .sql file in db/views/ to define your SQL query.
3. Run the migration: rake db:migrate.

$ rails generate scenic:view search_results

Scenic supports materialized views via the --materialized flag in the scenic:view or scenic:model generators.

Refreshing Materialized Views

If you use scenic:model, a .refresh method is added to the model class:

# Non-concurrent refresh (locks the view)
Model.refresh

# Concurrent refresh (requires Postgres 9.4+ and a unique index)
Model.refresh(concurrently: true)

# Cascading refresh (refreshes dependent views)
Model.refresh(cascade: true)

Updating Materialized Views with side_by_side strategy

Because materialized views cannot be updated in-place with REPLACE VIEW, use the --side-by-side option during generation. This creates a migration using the side_by_side strategy, which prepares the new version under a temporary name to minimize lock time.

$ rails generate scenic:view search_results --materialized --side-by-side

To use Scenic with a PostgreSQL database, add the scenic gem to your Gemfile and run bundle install.

gem "scenic"

You can back an ActiveRecord model with a view. Use the scenic:model generator, which is a superset of scenic:view. It creates the model file and the versioned view definition/migration.

Important Requirements:

• Primary Key: Since views do not have primary keys, you must explicitly declare the primary key in your model to enable methods like find, first, or last.
• Read-only: It is recommended to define readonly? as true to prevent Rails from attempting to save changes to the view.

$ rails generate scenic:model recent_status

To remove a view, use the drop_view method in a migration. You can specify the version to revert to and whether the view is materialized.

class DropViews < ActiveRecord::Migration
  def change
    drop_view :search_results, revert_to_version: 2
    drop_view :materialized_admin_reports, revert_to_version: 3, materialized: true
  end
end

The Scenic::Index class is an in-memory representation of a database index.

Note: This class is intended for use by adapter gems and the schema dumper. It is not intended for use by general application code.

It provides access to the object name, the index name, and the SQL definition used to create the index.

Scenic provides a Rails generator to create view definitions (SQL files) and the corresponding database migrations. This generator handles both the creation of new views and the generation of update migrations for existing views.

To create a new view, use the scenic:view generator followed by the name of the view. This will create a file in db/views/ and a migration file in db/migrate/.