Class: Scenic::Adapters::Postgres

Inherits:
Object
  • Object
show all
Defined in:
lib/scenic/adapters/postgres.rb,
lib/scenic/adapters/postgres/views.rb,
lib/scenic/adapters/postgres/errors.rb,
lib/scenic/adapters/postgres/indexes.rb,
lib/scenic/adapters/postgres/connection.rb,
lib/scenic/adapters/postgres/index_reapplication.rb,
lib/scenic/adapters/postgres/refresh_dependencies.rb

Overview

An adapter for managing Postgres views.

These methods are used interally by Scenic and are not intended for direct use. Methods that alter database schema are intended to be called via Statements, while #refresh_materialized_view is called via Scenic.database.

The methods are documented here for insight into specifics of how Scenic integrates with Postgres and the responsibilities of Scenic::Adapters.

Defined Under Namespace

Classes: ConcurrentRefreshesNotSupportedError, MaterializedViewsNotSupportedError, RefreshDependencies

Instance Method Summary collapse

Constructor Details

#initialize(connectable = ActiveRecord::Base) ⇒ Postgres

Creates an instance of the Scenic Postgres adapter.

This is the default adapter for Scenic. Configuring it via Scenic.configure is not required, but the example below shows how one would explicitly set it.

Examples:

Scenic.configure do |config|
  config.adapter = Scenic::Adapters::Postgres.new
end

Parameters:

  • connectable (#connection) (defaults to: ActiveRecord::Base)

    An object that returns the connection for Scenic to use. Defaults to ActiveRecord::Base.



38
39
40
# File 'lib/scenic/adapters/postgres.rb', line 38

def initialize(connectable = ActiveRecord::Base)
  @connectable = connectable
end

Instance Method Details

#create_materialized_view(name, sql_definition) ⇒ void

This method returns an undefined value.

Creates a materialized view in the database

This is typically called in a migration via Statements#create_view.

Parameters:

  • name

    The name of the materialized view to create

  • sql_definition

    The SQL schema that defines the materialized view.

Raises:



132
133
134
135
# File 'lib/scenic/adapters/postgres.rb', line 132

def create_materialized_view(name, sql_definition)
  raise_unless_materialized_views_supported
  execute "CREATE MATERIALIZED VIEW #{quote_table_name(name)} AS #{sql_definition};"
end

#create_view(name, sql_definition) ⇒ void

This method returns an undefined value.

Creates a view in the database.

This is typically called in a migration via Statements#create_view.

Parameters:

  • name

    The name of the view to create

  • sql_definition

    The SQL schema for the view.



60
61
62
# File 'lib/scenic/adapters/postgres.rb', line 60

def create_view(name, sql_definition)
  execute "CREATE VIEW #{quote_table_name(name)} AS #{sql_definition};"
end

#drop_materialized_view(name) ⇒ void

This method returns an undefined value.

Drops a materialized view in the database

This is typically called in a migration via Statements#update_view.

Parameters:

  • name

    The name of the materialized view to drop.

Raises:



170
171
172
173
# File 'lib/scenic/adapters/postgres.rb', line 170

def drop_materialized_view(name)
  raise_unless_materialized_views_supported
  execute "DROP MATERIALIZED VIEW #{quote_table_name(name)};"
end

#drop_view(name) ⇒ void

This method returns an undefined value.

Drops the named view from the database

This is typically called in a migration via Statements#drop_view.

Parameters:

  • name

    The name of the view to drop



117
118
119
# File 'lib/scenic/adapters/postgres.rb', line 117

def drop_view(name)
  execute "DROP VIEW #{quote_table_name(name)};"
end

#refresh_materialized_view(name, concurrently: false, cascade: false) ⇒ void

This method returns an undefined value.

Refreshes a materialized view from its SQL schema.

This is typically called from application code via Scenic.database.

Examples:

Non-concurrent refresh

Scenic.database.refresh_materialized_view(:search_results)

Concurrent refresh

Scenic.database.refresh_materialized_view(:posts, concurrently: true)

Parameters:

  • name

    The name of the materialized view to refresh.

  • concurrently (Boolean)

    Whether the refreshs hould happen concurrently or not. A concurrent refresh allows the view to be refreshed without locking the view for select but requires that the table have at least one unique index that covers all rows. Attempts to refresh concurrently without a unique index will raise a descriptive error.

Raises:



199
200
201
202
203
204
205
206
207
208
209
210
211
# File 'lib/scenic/adapters/postgres.rb', line 199

def refresh_materialized_view(name, concurrently: false, cascade: false)
  raise_unless_materialized_views_supported
  if cascade
    refresh_dependencies_for(name)
  end

  if concurrently
    raise_unless_concurrent_refresh_supported
    execute "REFRESH MATERIALIZED VIEW CONCURRENTLY #{quote_table_name(name)};"
  else
    execute "REFRESH MATERIALIZED VIEW #{quote_table_name(name)};"
  end
end

#replace_view(name, sql_definition) ⇒ void

This method returns an undefined value.

Replaces a view in the database using CREATE OR REPLACE VIEW.

This results in a CREATE OR REPLACE VIEW. Most of the time the explicitness of the two step process used in #update_view is preferred to CREATE OR REPLACE VIEW because the former ensures that the view you are trying to update did, in fact, already exist. Additionally, CREATE OR REPLACE VIEW is allowed only to add new columns to the end of an existing view schema. Existing columns cannot be re-ordered, removed, or have their types changed. Drop and create overcomes this limitation as well.

However, when there is a tangled dependency tree CREATE OR REPLACE VIEW can be preferable.

This is typically called in a migration via Statements#replace_view.

Parameters:

  • name

    The name of the view to update

  • sql_definition

    The SQL schema for the updated view.



106
107
108
# File 'lib/scenic/adapters/postgres.rb', line 106

def replace_view(name, sql_definition)
  execute "CREATE OR REPLACE VIEW #{quote_table_name(name)} AS #{sql_definition};"
end

#update_materialized_view(name, sql_definition) ⇒ void

This method returns an undefined value.

Updates a materialized view in the database.

Drops and recreates the materialized view. Attempts to maintain all previously existing and still applicable indexes on the materialized view after the view is recreated.

This is typically called in a migration via Statements#update_view.

Parameters:

  • name

    The name of the view to update

  • sql_definition

    The SQL schema for the updated view.

Raises:



152
153
154
155
156
157
158
159
# File 'lib/scenic/adapters/postgres.rb', line 152

def update_materialized_view(name, sql_definition)
  raise_unless_materialized_views_supported

  IndexReapplication.new(connection: connection).on(name) do
    drop_materialized_view(name)
    create_materialized_view(name, sql_definition)
  end
end

#update_view(name, sql_definition) ⇒ void

This method returns an undefined value.

Updates a view in the database.

This results in a #drop_view followed by a #create_view. The explicitness of that two step process is preferred to CREATE OR REPLACE VIEW because the former ensures that the view you are trying to update did, in fact, already exist. Additionally, CREATE OR REPLACE VIEW is allowed only to add new columns to the end of an existing view schema. Existing columns cannot be re-ordered, removed, or have their types changed. Drop and create overcomes this limitation as well.

This is typically called in a migration via Statements#update_view.

Parameters:

  • name

    The name of the view to update

  • sql_definition

    The SQL schema for the updated view.



80
81
82
83
# File 'lib/scenic/adapters/postgres.rb', line 80

def update_view(name, sql_definition)
  drop_view(name)
  create_view(name, sql_definition)
end

#viewsArray<Scenic::View>

Returns an array of views in the database.

This collection of views is used by the [Scenic::SchemaDumper] to populate the schema.rb file.

Returns:



48
49
50
# File 'lib/scenic/adapters/postgres.rb', line 48

def views
  Views.new(connection).all
end