Module: Scenic::Statements

Defined in:
lib/scenic/statements.rb

Overview

Methods that are made available in migrations for managing Scenic views.

Instance Method Summary collapse

Instance Method Details

#create_view(name, version: nil, sql_definition: nil, materialized: false) ⇒ Object

Create a new database view.

Examples:

Create from db/views/searches_v02.sql

create_view(:searches, version: 2)

Create from provided SQL string

create_view(:active_users, sql_definition: <<-SQL)
  SELECT * FROM users WHERE users.active = 't'
SQL

Parameters:

  • name (String, Symbol) —

    The name of the database view.

  • version (Fixnum) (defaults to: nil) —

    The version number of the view, used to find the definition file in db/views. This defaults to 1 if not provided.

  • sql_definition (String) (defaults to: nil) —

    The SQL query for the view schema. An error will be raised if sql_definition and version are both set, as they are mutually exclusive.

  • materialized (Boolean) (defaults to: false) —

    Set to true to create a materialized view. Defaults to false.

Returns:

  • The database response from executing the create statement.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/scenic/statements.rb', line 24

def create_view(name, version: nil, sql_definition: nil, materialized: false)
  if version.present? && sql_definition.present?
    raise(
      ArgumentError,
      "sql_definition and version cannot both be set",
    )
  end

  if version.blank? && sql_definition.blank?
    version = 1
  end

  sql_definition ||= definition(name, version)

  if materialized
    Scenic.database.create_materialized_view(name, sql_definition)
  else
    Scenic.database.create_view(name, sql_definition)
  end
end

#drop_view(name, revert_to_version: nil, materialized: false) ⇒ Object

Drop a database view by name.

Examples:

Drop a view, rolling back to version 3 on rollback

drop_view(:users_who_recently_logged_in, revert_to_version: 3)

Parameters:

  • name (String, Symbol) —

    The name of the database view.

  • revert_to_version (Fixnum) (defaults to: nil) —

    Used to reverse the drop_view command on rake db:rollback. The provided version will be passed as the version argument to #create_view.

  • materialized (Boolean) (defaults to: false) —

    Set to true if dropping a meterialized view. defaults to false.

Returns:

  • The database response from executing the drop statement.



58
59
60
61
62
63
64
 
# File 'lib/scenic/statements.rb', line 58

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

#replace_view(name, version: nil, revert_to_version: nil, materialized: false) ⇒ Object

Update a database view to a new version using CREATE OR REPLACE VIEW.

The existing view is replaced using the supplied version parameter.

Does not work with materialized views due to lack of database support.

Examples:

replace_view :engagement_reports, version: 3, revert_to_version: 2

Parameters:

  • name (String, Symbol) —

    The name of the database view.

  • version (Fixnum) (defaults to: nil) —

    The version number of the view.

  • revert_to_version (Fixnum) (defaults to: nil) —

    The version number to rollback to on rake db rollback

Returns:

  • The database response from executing the create statement.



125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/scenic/statements.rb', line 125

def replace_view(name, version: nil, revert_to_version: nil, materialized: false)
  if version.blank?
    raise ArgumentError, "version is required"
  end

  if materialized
    raise ArgumentError, "Cannot replace materialized views"
  end

  sql_definition = definition(name, version)

  Scenic.database.replace_view(name, sql_definition)
end

#update_view(name, version: nil, sql_definition: nil, revert_to_version: nil, materialized: false) ⇒ Object

Update a database view to a new version.

The existing view is dropped and recreated using the supplied version parameter.

Examples:

update_view :engagement_reports, version: 3, revert_to_version: 2

Parameters:

  • name (String, Symbol) —

    The name of the database view.

  • version (Fixnum) (defaults to: nil) —

    The version number of the view.

  • sql_definition (String) (defaults to: nil) —

    The SQL query for the view schema. An error will be raised if sql_definition and version are both set, as they are mutually exclusive.

  • revert_to_version (Fixnum) (defaults to: nil) —

    The version number to rollback to on rake db rollback

  • materialized (Boolean) (defaults to: false) —

    True if updating a materialized view. Defaults to false.

Returns:

  • The database response from executing the create statement.



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/scenic/statements.rb', line 85

def update_view(name, version: nil, sql_definition: nil, revert_to_version: nil, materialized: false)
  if version.blank? && sql_definition.blank?
    raise(
      ArgumentError,
      "sql_definition or version must be specified",
    )
  end

  if version.present? && sql_definition.present?
    raise(
      ArgumentError,
      "sql_definition and version cannot both be set",
    )
  end

  sql_definition ||= definition(name, version)

  if materialized
    Scenic.database.update_materialized_view(name, sql_definition)
  else
    Scenic.database.update_view(name, sql_definition)
  end
end