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, Hash) (defaults to: false) —

    Set to true to create a materialized view. Set to { no_data: true } to create materialized view without loading data. Defaults to false.

Returns:

  • The database response from executing the create statement.



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

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,
      no_data: no_data(materialized),
    )
  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.



63
64
65
66
67
68
69
 
# File 'lib/scenic/statements.rb', line 63

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.



135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/scenic/statements.rb', line 135

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, Hash) (defaults to: false) —

    True if updating a materialized view. Set to { no_data: true } to update materialized view without loading data. Defaults to false.

Returns:

  • The database response from executing the create statement.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/scenic/statements.rb', line 91

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,
      no_data: no_data(materialized),
    )
  else
    Scenic.database.update_view(name, sql_definition)
  end
end