pg_trunk 0.1.0 → 0.2.0

data/lib/pg_trunk/operations/materialized_views/create_materialized_view.rb

@@ -1,77 +1,88 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_materialized_view(name, **options, &block)
-# Create a materialized view
-#
-# @param [#to_s] name (nil) The qualified name of the view
-# @option [Boolean] :if_not_exists (false) Suppress the error when a view has been already created
-# @option [#to_s] :sql_definition (nil) The snippet containing the query
-# @option [#to_i] :version (nil)
-#   The alternative way to set sql_definition by referencing to a file containing the snippet
-# @option [#to_s] :tablespace (nil) The tablespace for the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [#to_s] :comment (nil) The comment describing the view
-# @yield [Proc] the block with the view's definition
-# @yieldparam The receiver of methods specifying the view
-#
-# The operation creates the view using its `sql_definition`:
-#
-#   create_materialized_view("views.admin_users", sql_definition: <<~SQL)
-#     SELECT id, name FROM users WHERE admin;
-#   SQL
-#
-# For compatibility to the `scenic` gem, we also support
-# adding a definition via its version:
-#
-#    create_materialized_view "admin_users", version: 1
-#
-# It is expected, that a `db/materialized_views/admin_users_v01.sql`
-# to contain the SQL snippet.
-#
-# The tablespace can be specified for the created view.
-# Notice that later it can't be changed (in PostgreSQL all rows
-# can be moved to another tablespace, but we don't support
-# this feature yet).
-#
-#   create_materialized_view "admin_users" do |v|
-#     v.tablespace "fast_ssd"
-#     v.sql_definition <<~SQL
-#       SELECT id, name, password, admin, on_duty
-#       FROM users
-#       WHERE admin
-#     SQL
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a materialized view
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the view
+#     # @option options [Boolean] :if_not_exists (false) Suppress the error when a view has been already created
+#     # @option options [#to_s] :sql_definition (nil) The snippet containing the query
+#     # @option options [#to_i] :version (nil)
+#     #   The alternative way to set sql_definition by referencing to a file containing the snippet
+#     # @option options [#to_s] :tablespace (nil) The tablespace for the view
+#     # @option options [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option options [#to_s] :comment (nil) The comment describing the view
+#     # @yield [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation creates the view using its `sql_definition`:
+#     #
+#     # ```ruby
+#     # create_materialized_view("views.admin_users", sql_definition: <<~SQL)
+#     #   SELECT id, name FROM users WHERE admin;
+#     # SQL
+#     # ```
+#     #
+#     # For compatibility to the `scenic` gem, we also support
+#     # adding a definition via its version:
+#     #
+#     # ```ruby
+#     # create_materialized_view "admin_users", version: 1
+#     # ```
+#     #
+#     # It is expected, that a `db/materialized_views/admin_users_v01.sql`
+#     # to contain the SQL snippet.
+#     #
+#     # The tablespace can be specified for the created view.
+#     # Notice that later it can't be changed (in PostgreSQL all rows
+#     # can be moved to another tablespace, but we don't support
+#     # this feature yet).
+#     #
+#     # ```ruby
+#     # create_materialized_view "admin_users" do |v|
+#     #   v.tablespace "fast_ssd"
+#     #   v.sql_definition <<~SQL
+#     #     SELECT id, name, password, admin, on_duty
+#     #     FROM users
+#     #     WHERE admin
+#     #   SQL
+#     # end
+#     # ```
+#     #
+#     # You can also set a comment describing the view,
+#     # and redefine the storage options for some TOAST-ed columns,
+#     # as well as their custom statistics:
+#     #
+#     # ```ruby
+#     # create_materialized_view "admin_users" do |v|
+#     #   v.sql_definition <<~SQL
+#     #     SELECT id, name, password, admin, on_duty
+#     #     FROM users
+#     #     WHERE admin
+#     #   SQL
+#     #   v.column "password", storage: "external" # to avoid compression
+#     #   v.column "password", n_distinct: -1 # linear dependency
+#     #   v.column "admin", n_distinct: 1 # exact number of values
+#     #   v.column "on_duty", statistics: 2 # the total number of values
+#     #   v.comment "Admin users only"
+#     # end
+#     # ```
+#     #
+#     # With the `replace_existing: true` option the operation
+#     # would use `CREATE OR REPLACE VIEW` command, so it
+#     # can be used to "update" (or reload) the existing view.
+#     #
+#     # ```ruby
+#     # create_materialized_view "admin_users",
+#     #                          version: 1,
+#     #                          replace_existing: true
+#     # ```
+#     #
+#     # This option makes the migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def create_materialized_view(name, **options, &block); end
 #   end
-#
-# You can also set a comment describing the view,
-# and redefine the storage options for some TOAST-ed columns,
-# as well as their custom statistics:
-#
-#   create_materialized_view "admin_users" do |v|
-#     v.sql_definition <<~SQL
-#       SELECT id, name, password, admin, on_duty
-#       FROM users
-#       WHERE admin
-#     SQL
-#
-#     v.column "password", storage: "external" # to avoid compression
-#     v.column "password", n_distinct: -1 # linear dependency
-#     v.column "admin", n_distinct: 1 # exact number of values
-#     v.column "on_duty", statistics: 2 # the total number of values
-#
-#     v.comment "Admin users only"
-#   end
-#
-# With the `replace_existing: true` option the operation
-# would use `CREATE OR REPLACE VIEW` command, so it
-# can be used to "update" (or reload) the existing view.
-#
-#   create_materialized_view "admin_users",
-#                            version: 1,
-#                            replace_existing: true
-#
-# This option makes the migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::MaterializedViews
   # @private
   class CreateMaterializedView < Base

data/lib/pg_trunk/operations/materialized_views/drop_materialized_view.rb

@@ -1,52 +1,65 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_materialized_view(name, **options, &block)
-# Drop a materialized view
-#
-# @param [#to_s] name (nil) The qualified name of the view
-# @option [Boolean] :if_exists (false) Suppress the error when the view is absent
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @option [#to_s] :sql_definition (nil) The snippet containing the query
-# @option [#to_i] :revert_to_version (nil)
-#   The alternative way to set sql_definition by referencing to a file containing the snippet
-# @option [#to_s] :tablespace (nil) The tablespace for the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [#to_s] :comment (nil) The comment describing the view
-# @yield [Proc] the block with the view's definition
-# @yieldparam The receiver of methods specifying the view
-#
-# The operation drops a materialized view identified by its
-# qualified name (it can include a schema).
-#
-#   drop_materialized_view "views.admin_users"
-#
-# To make the operation invertible, use the same options
-# as in the `create_view` operation.
-#
-#   drop_materialized_view "views.admin_users" do |v|
-#     v.sql_definition "SELECT name, password FROM users WHERE admin;"
-#     v.column "password", storage: "external" # prevent compression
-#     v.with_data false
-#     v.comment "Admin users only"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a materialized view
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the view
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the view is absent
+#     # @option options [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option options [#to_s] :sql_definition (nil) The snippet containing the query
+#     # @option options [#to_i] :revert_to_version (nil)
+#     #   The alternative way to set sql_definition by referencing to a file containing the snippet
+#     # @option options [#to_s] :tablespace (nil) The tablespace for the view
+#     # @option options [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option options [#to_s] :comment (nil) The comment describing the view
+#     # @yield [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation drops a materialized view identified by its
+#     # qualified name (it can include a schema).
+#     #
+#     # ```ruby
+#     # drop_materialized_view "views.admin_users"
+#     # ```
+#     #
+#     # To make the operation invertible, use the same options
+#     # as in the `create_view` operation.
+#     #
+#     # ```ruby
+#     # drop_materialized_view "views.admin_users" do |v|
+#     #   v.sql_definition "SELECT name, password FROM users WHERE admin;"
+#     #   v.column "password", storage: "external" # prevent compression
+#     #   v.with_data false
+#     #   v.comment "Admin users only"
+#     # end
+#     # ```
+#     #
+#     # You can also use a version-base SQL definition like:
+#     #
+#     # ```ruby
+#     # drop_materialized_view "admin_users", revert_to_version: 1
+#     # ```
+#     #
+#     # With the `force: :cascade` option the operation would remove
+#     # all the objects which depend on the view.
+#     #
+#     # ```ruby
+#     # drop_materialized_view "admin_users", force: :cascade
+#     # ```
+#     #
+#     # With the `if_exists: true` option the operation won't fail
+#     # even when the view was absent in the database.
+#     #
+#     # ```ruby
+#     # drop_materialized_view "admin_users", if_exists: true
+#     # ```
+#     #
+#     # Both options make a migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def drop_materialized_view(name, **options, &block); end
 #   end
-#
-# You can also use a version-base SQL definition like:
-#
-#    drop_materialized_view "admin_users", revert_to_version: 1
-#
-# With the `force: :cascade` option the operation would remove
-# all the objects which depend on the view.
-#
-#   drop_materialized_view "admin_users", force: :cascade
-#
-# With the `if_exists: true` option the operation won't fail
-# even when the view was absent in the database.
-#
-#   drop_materialized_view "admin_users", if_exists: true
-#
-# Both options make a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::MaterializedViews
   # @private
   class DropMaterializedView < Base

data/lib/pg_trunk/operations/materialized_views/refresh_materialized_view.rb

@@ -1,29 +1,34 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#refresh_materialized_view(name, **options)
-# Refresh a materialized view
-#
-# @param [#to_s] name (nil) The qualified name of the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [Symbol] :algorithm (nil) Makes the operation concurrent when set to :concurrently
-#
-# The operation enables refreshing a materialized view
-# by reloading its underlying SQL query:
-#
-#   refresh_materialized_view "admin_users"
-#
-# The option `algorithm: :concurrently` acts exactly
-# like in the `create_index` definition. You should
-# possibly add the `disable_ddl_transaction!` command
-# to the migration as well.
-#
-# With option `with_data: false` the command won't
-# update the data. This option can't be used along with
-# the `:algorithm`.
-#
-# The operation is always reversible, though its
-# inversion does nothing.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Refresh a materialized view
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the view
+#     # @option options [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option options [Symbol] :algorithm (nil) Makes the operation concurrent when set to :concurrently
+#     # @return [void]
+#     #
+#     # The operation enables refreshing a materialized view
+#     # by reloading its underlying SQL query:
+#     #
+#     # ```ruby
+#     # refresh_materialized_view "admin_users"
+#     # ```
+#     #
+#     # The option `algorithm: :concurrently` acts exactly
+#     # like in the `create_index` definition. You should
+#     # possibly add the `disable_ddl_transaction!` command
+#     # to the migration as well.
+#     #
+#     # With option `with_data: false` the command won't
+#     # update the data. This option can't be used along with
+#     # the `:algorithm`.
+#     #
+#     # The operation is always reversible, though its
+#     # inversion does nothing.
+#     def refresh_materialized_view(name, **options); end
+#   end
 module PGTrunk::Operations::MaterializedViews
   # @private
   class RefreshMaterializedView < Base

data/lib/pg_trunk/operations/materialized_views/rename_materialized_view.rb

@@ -1,27 +1,34 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_materialized_view(name, **options)
-# Change the name and/or schema of a materialized view
-#
-# @param [#to_s] :name (nil) The qualified name of the view
-# @option [#to_s] :to (nil) The new qualified name for the view
-# @option [Boolean] :if_exists (false) Suppress the error when the view is absent
-#
-# A materialized view can be renamed by changing both the name
-# and the schema (namespace) it belongs to.
-#
-#   rename_materialized_view "views.admin_users", to: "admins"
-#
-# With the `if_exists: true` option, the operation won't fail
-# even when the view wasn't existed.
-#
-#   rename_materialized_view "admin_users",
-#                            to: "admins",
-#                            if_exists: true
-#
-# At the same time, the option makes a migration irreversible
-# due to uncertainty of the previous state of the database.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of a materialized view
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the view
+#     # @option options [#to_s] :to (nil) The new qualified name for the view
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the view is absent
+#     # @return [void]
+#     #
+#     # A materialized view can be renamed by changing both the name
+#     # and the schema (namespace) it belongs to.
+#     #
+#     # ```ruby
+#     # rename_materialized_view "views.admin_users", to: "admins"
+#     # ```
+#     #
+#     # With the `if_exists: true` option, the operation won't fail
+#     # even when the view wasn't existed.
+#     #
+#     # ```ruby
+#     # rename_materialized_view "admin_users",
+#     #                          to: "admins",
+#     #                          if_exists: true
+#     # ```
+#     #
+#     # At the same time, the option makes a migration irreversible
+#     # due to uncertainty of the previous state of the database.
+#     def rename_materialized_view(name, **options); end
+#   end
 module PGTrunk::Operations::MaterializedViews
   # @private
   class RenameMaterializedView < Base

data/lib/pg_trunk/operations/procedures/change_procedure.rb

@@ -1,51 +1,58 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_procedure(name, **options, &block)
-# Modify a procedure
-#
-# @param [#to_s] name (nil) The qualified name of the procedure
-# @option [Boolean] :if_exists (false) Suppress the error when the procedure is absent
-# @yield [Proc] the block with the procedure's definition
-# @yieldparam The receiver of methods specifying the procedure
-#
-# The operation changes the procedure without dropping it
-# (which is useful when there are other objects
-# using the function and you don't want to change them all).
-#
-# You can change any property except for the name
-# (use `rename_function` instead) and `language`.
-#
-#   change_procedure "metadata.set_foo(a int)" do |p|
-#     p.body <<~SQL
-#       SET foo = a
-#     SQL
-#     p.security :invoker
-#     p.comment "Multiplies 2 integers"
-#   SQL
-#
-# The example above is not invertible because of uncertainty
-# about the previous state of body and comment.
-# To define them, use a from options (available in a block syntax only):
-#
-#   change_procedure "metadata.set_foo(a int)" do |p|
-#     p.body <<~SQL, from: <<~SQL
-#       SET foo = a
-#     SQL
-#       SET foo = -a
-#     SQL
-#     p.comment <<~MSG, from: <<~MSG
-#       Multiplies 2 integers
-#     MSG
-#       Multiplies ints
-#     MSG
-#     p.security :invoker
-#   SQL
-#
-# Like in the other operations, the procedure can be
-# identified by a qualified name (with types of arguments).
-# If it has no overloaded implementations,
-# the plain name is supported as well.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify a procedure
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the procedure
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the procedure is absent
+#     # @yield [p] the block with the procedure's definition
+#     # @yieldparam Object receiver of methods specifying the procedure
+#     # @return [void]
+#     #
+#     # The operation changes the procedure without dropping it
+#     # (which is useful when there are other objects
+#     # using the function and you don't want to change them all).
+#     #
+#     # You can change any property except for the name
+#     # (use `rename_function` instead) and `language`.
+#     #
+#     # ```ruby
+#     # change_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.body <<~SQL
+#     #     SET foo = a
+#     #   SQL
+#     #   p.security :invoker
+#     #   p.comment "Multiplies 2 integers"
+#     # SQL
+#     # ```
+#     #
+#     # The example above is not invertible because of uncertainty
+#     # about the previous state of body and comment.
+#     # To define them, use a from options (available in a block syntax only):
+#     #
+#     # ```ruby
+#     # change_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.body <<~SQL, from: <<~SQL
+#     #     SET foo = a
+#     #   SQL
+#     #     SET foo = -a
+#     #   SQL
+#     #   p.comment <<~MSG, from: <<~MSG
+#     #     Multiplies 2 integers
+#     #   MSG
+#     #     Multiplies ints
+#     #   MSG
+#     #   p.security :invoker
+#     # SQL
+#     # ```
+#     #
+#     # Like in the other operations, the procedure can be
+#     # identified by a qualified name (with types of arguments).
+#     # If it has no overloaded implementations,
+#     # the plain name is supported as well.
+#     def change_procedure(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Procedures
   # @private
   class ChangeProcedure < Base

data/lib/pg_trunk/operations/procedures/create_procedure.rb

@@ -1,58 +1,69 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_procedure(name, **options, &block)
-# Create a procedure
-#
-# @param [#to_s] name (nil)
-#   The qualified name of the procedure with arguments and returned value type
-# @option [Boolean] :replace_existing (false) If the procedure should overwrite an existing one
-# @option [#to_s] :language ("sql") The language (like "sql" or "plpgsql")
-# @option [#to_s] :body (nil) The body of the procedure
-# @option [Symbol] :security (:invoker) Define the role under which the procedure is invoked
-#   Supported values: :invoker (default), :definer
-# @option [#to_s] :comment The description of the procedure
-# @yield [Proc] the block with the procedure's definition
-# @yieldparam The receiver of methods specifying the procedure
-#
-# The syntax of the operation is the same as for `create_function`,
-# but with only `security` option available. Notice, that
-# procedures cannot return values so you're expected not to
-# define a returned value as well.
-#
-# The procedure can be created either using inline syntax
-#
-#   create_procedure "metadata.set_foo(a int)",
-#                    language: :sql,
-#                    body: "SET foo = a",
-#                    comment: "Sets foo value"
-#
-# or using a block:
-#
-#   create_procedure "metadata.set_foo(a int)" do |p|
-#     p.language "sql" # (default)
-#     p.body <<~SQL
-#       SET foo = a
-#     SQL
-#     p.security :invoker # (default), also :definer
-#     p.comment "Multiplies 2 integers"
-#   SQL
-#
-# With a `replace_existing: true` option,
-# it will be created using the `CREATE OR REPLACE` clause.
-# In this case the migration is irreversible because we
-# don't know if and how to restore its previous definition.
-#
-#   create_procedure "set_foo(a int)",
-#                    body: "SET foo = a",
-#                    replace_existing: true
-#
-# A procedure without arguments is supported as well
-#
-#   # the same as "do_something()"
-#   create_procedure "do_something" do |p|
-#     # ...
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a procedure
+#     #
+#     # @param [#to_s] name (nil)
+#     #   The qualified name of the procedure with arguments and returned value type
+#     # @option options [Boolean] :replace_existing (false) If the procedure should overwrite an existing one
+#     # @option options [#to_s] :language ("sql") The language (like "sql" or "plpgsql")
+#     # @option options [#to_s] :body (nil) The body of the procedure
+#     # @option options [Symbol] :security (:invoker) Define the role under which the procedure is invoked
+#     #   Supported values: :invoker (default), :definer
+#     # @option options [#to_s] :comment The description of the procedure
+#     # @yield [p] the block with the procedure's definition
+#     # @yieldparam Object receiver of methods specifying the procedure
+#     # @return [void]
+#     #
+#     # The syntax of the operation is the same as for `create_function`,
+#     # but with only `security` option available. Notice, that
+#     # procedures cannot return values so you're expected not to
+#     # define a returned value as well.
+#     #
+#     # The procedure can be created either using inline syntax
+#     #
+#     # ```ruby
+#     # create_procedure "metadata.set_foo(a int)",
+#     #                  language: :sql,
+#     #                  body: "SET foo = a",
+#     #                  comment: "Sets foo value"
+#     # ```
+#     #
+#     # or using a block:
+#     #
+#     # ```ruby
+#     # create_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.language "sql" # (default)
+#     #   p.body <<~SQL
+#     #     SET foo = a
+#     #   SQL
+#     #   p.security :invoker # (default), also :definer
+#     #   p.comment "Multiplies 2 integers"
+#     # SQL
+#     # ```
+#     #
+#     # With a `replace_existing: true` option,
+#     # it will be created using the `CREATE OR REPLACE` clause.
+#     # In this case the migration is irreversible because we
+#     # don't know if and how to restore its previous definition.
+#     #
+#     # ```ruby
+#     # create_procedure "set_foo(a int)",
+#     #                  body: "SET foo = a",
+#     #                  replace_existing: true
+#     # ```
+#     #
+#     # A procedure without arguments is supported as well
+#     #
+#     # ```ruby
+#     # # the same as "do_something()"
+#     # create_procedure "do_something" do |p|
+#     #   # ...
+#     # end
+#     # ```
+#     def create_procedure(name, **options, &block); end
 #   end
-
 module PGTrunk::Operations::Procedures
   # @private
   class CreateProcedure < Base