pg_trunk 0.1.0 → 0.2.0

data/lib/pg_trunk/operations/functions/create_function.rb

@@ -1,70 +1,81 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_function(name, **options, &block)
-# Create a function
-#
-# @param [#to_s] name (nil)
-#   The qualified name of the function with arguments and returned value type
-# @option [Boolean] :replace_existing (false) If the function 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 function
-# @option [Symbol] :volatility (:volatile) The volatility of the function.
-#   Supported values: :volatile (default), :stable, :immutable
-# @option [Symbol] :parallel (:unsafe) The safety of parallel execution.
-#   Supported values: :unsafe (default), :restricted, :safe
-# @option [Symbol] :security (:invoker) Define the role under which the function is invoked
-#   Supported values: :invoker (default), :definer
-# @option [Boolean] :leakproof (false) If the function is leakproof
-# @option [Boolean] :strict (false) If the function is strict
-# @option [Float] :cost (nil) The cost estimation for the function
-# @option [Integer] :rows (nil) The number of rows returned by a function
-# @option [#to_s] :comment The description of the function
-# @yield [Proc] the block with the function's definition
-# @yieldparam The receiver of methods specifying the function
-#
-# The function can be created either using inline syntax
-#
-#   create_function "math.mult(a int, b int) int",
-#                   language: :sql,
-#                   body: "SELECT a * b",
-#                   volatility: :immutable,
-#                   leakproof: true,
-#                   comment: "Multiplies 2 integers"
-#
-# or using a block:
-#
-#   create_function "math.mult(a int, b int) int" do |f|
-#     f.language "sql" # (default)
-#     f.body <<~SQL
-#       SELECT a * b;
-#     SQL
-#     f.volatility :immutable # :stable, :volatile (default)
-#     f.parallel :safe        # :restricted, :unsafe (default)
-#     f.security :invoker     # (default), also :definer
-#     f.leakproof true
-#     f.strict true
-#     f.cost 5.0
-#     # f.rows 1 (supported for functions returning sets of rows)
-#     f.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_function "math.mult(a int, b int) int",
-#                   body: "SELECT a * b",
-#                   replace_existing: true
-#
-# We presume a function without arguments should have
-# no arguments and return `void` like
-#
-#   # the same as "do_something() void"
-#   create_function "do_something" do |f|
-#     # ...
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a function
+#     #
+#     # @param [#to_s] name (nil)
+#     #   The qualified name of the function with arguments and returned value type
+#     # @option options [Boolean] :replace_existing (false) If the function 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 function
+#     # @option options [Symbol] :volatility (:volatile) The volatility of the function.
+#     #   Supported values: :volatile (default), :stable, :immutable
+#     # @option options [Symbol] :parallel (:unsafe) The safety of parallel execution.
+#     #   Supported values: :unsafe (default), :restricted, :safe
+#     # @option options [Symbol] :security (:invoker) Define the role under which the function is invoked
+#     #   Supported values: :invoker (default), :definer
+#     # @option options [Boolean] :leakproof (false) If the function is leakproof
+#     # @option options [Boolean] :strict (false) If the function is strict
+#     # @option options [Float] :cost (nil) The cost estimation for the function
+#     # @option options [Integer] :rows (nil) The number of rows returned by a function
+#     # @option options [#to_s] :comment The description of the function
+#     # @yield [f] the block with the function's definition
+#     # @yieldparam Object receiver of methods specifying the function
+#     # @return [void]
+#     #
+#     # The function can be created either using inline syntax
+#     #
+#     # ```ruby
+#     # create_function "math.mult(a int, b int) int",
+#     #                 language: :sql,
+#     #                 body: "SELECT a * b",
+#     #                 volatility: :immutable,
+#     #                 leakproof: true,
+#     #                 comment: "Multiplies 2 integers"
+#     # ```
+#     #
+#     # or using a block:
+#     #
+#     # ```ruby
+#     # create_function "math.mult(a int, b int) int" do |f|
+#     #   f.language "sql" # (default)
+#     #   f.body <<~SQL
+#     #     SELECT a * b;
+#     #   SQL
+#     #   f.volatility :immutable # :stable, :volatile (default)
+#     #   f.parallel :safe        # :restricted, :unsafe (default)
+#     #   f.security :invoker     # (default), also :definer
+#     #   f.leakproof true
+#     #   f.strict true
+#     #   f.cost 5.0
+#     #   # f.rows 1 (supported for functions returning sets of rows)
+#     #   f.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_function "math.mult(a int, b int) int",
+#     #                 body: "SELECT a * b",
+#     #                 replace_existing: true
+#     # ```
+#     #
+#     # We presume a function without arguments should have
+#     # no arguments and return `void` like
+#     #
+#     # ```ruby
+#     # # the same as "do_something() void"
+#     # create_function "do_something" do |f|
+#     #   # ...
+#     # end
+#     # ```
+#     def create_function(name, **options, &block); end
 #   end
-
 module PGTrunk::Operations::Functions
   # @private
   class CreateFunction < Base

data/lib/pg_trunk/operations/functions/drop_function.rb

@@ -1,71 +1,84 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_function(name, **options, &block)
-# Drop a function
-#
-# @param [#to_s] name (nil)
-#   The qualified name of the function with arguments and returned value type
-# @option [Boolean] :if_exists (false) Suppress the error when the function is absent
-# @option [Symbol] :force (:restrict) How to process dependent objects
-#   Supported values: :restrict (default), :cascade
-# @option [#to_s] :language ("sql") The language (like "sql" or "plpgsql")
-# @option [#to_s] :body (nil) The body of the function
-# @option [Symbol] :volatility (:volatile) The volatility of the function.
-#   Supported values: :volatile (default), :stable, :immutable
-# @option [Symbol] :parallel (:unsafe) The safety of parallel execution.
-#   Supported values: :unsafe (default), :restricted, :safe
-# @option [Symbol] :security (:invoker) Define the role under which the function is invoked
-#   Supported values: :invoker (default), :definer
-# @option [Boolean] :leakproof (false) If the function is leakproof
-# @option [Boolean] :strict (false) If the function is strict
-# @option [Float] :cost (nil) The cost estimation for the function
-# @option [Integer] :rows (nil) The number of rows returned by a function
-# @option [#to_s] :comment The description of the function
-# @yield [Proc] the block with the function's definition
-# @yieldparam The receiver of methods specifying the function
-#
-# A function can be dropped by a plain name:
-#
-#   drop_function "multiply"
-#
-# If several overloaded functions have the name,
-# then you must specify the signature having
-# types of attributes at least:
-#
-#   drop_function "multiply(int, int)"
-#
-# In both cases above the operation is irreversible. To make it
-# inverted you have to provide a full signature along with
-# the body definition. The other options are supported as well:
-#
-#   drop_function "math.mult(a int, b int) int" do |f|
-#     f.language "sql" # (default)
-#     f.body <<~SQL
-#       SELECT a * b;
-#     SQL
-#     f.volatility :immutable # :stable, :volatile (default)
-#     f.parallel :safe        # :restricted, :unsafe (default)
-#     f.security :invoker     # (default), also :definer
-#     f.leakproof true
-#     f.strict true
-#     f.cost 5.0
-#     # f.rows 1 (supported for functions returning sets of rows)
-#     f.comment "Multiplies 2 integers"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a function
+#     #
+#     # @param [#to_s] name (nil)
+#     #   The qualified name of the function with arguments and returned value type
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the function is absent
+#     # @option options [Symbol] :force (:restrict) How to process dependent objects
+#     #   Supported values: :restrict (default), :cascade
+#     # @option options [#to_s] :language ("sql") The language (like "sql" or "plpgsql")
+#     # @option options [#to_s] :body (nil) The body of the function
+#     # @option options [Symbol] :volatility (:volatile) The volatility of the function.
+#     #   Supported values: :volatile (default), :stable, :immutable
+#     # @option options [Symbol] :parallel (:unsafe) The safety of parallel execution.
+#     #   Supported values: :unsafe (default), :restricted, :safe
+#     # @option options [Symbol] :security (:invoker) Define the role under which the function is invoked
+#     #   Supported values: :invoker (default), :definer
+#     # @option options [Boolean] :leakproof (false) If the function is leakproof
+#     # @option options [Boolean] :strict (false) If the function is strict
+#     # @option options [Float] :cost (nil) The cost estimation for the function
+#     # @option options [Integer] :rows (nil) The number of rows returned by a function
+#     # @option options [#to_s] :comment The description of the function
+#     # @yield [f] the block with the function's definition
+#     # @yieldparam Object receiver of methods specifying the function
+#     # @return [void]
+#     #
+#     # A function can be dropped by a plain name:
+#     #
+#     # ```ruby
+#     # drop_function "multiply"
+#     # ```
+#     #
+#     # If several overloaded functions have the name,
+#     # then you must specify the signature having
+#     # types of attributes at least:
+#     #
+#     # ```ruby
+#     # drop_function "multiply(int, int)"
+#     # ```
+#     #
+#     # In both cases above the operation is irreversible. To make it
+#     # inverted you have to provide a full signature along with
+#     # the body definition. The other options are supported as well:
+#     #
+#     # ```ruby
+#     # drop_function "math.mult(a int, b int) int" do |f|
+#     #   f.language "sql" # (default)
+#     #   f.body <<~SQL
+#     #     SELECT a * b;
+#     #   SQL
+#     #   f.volatility :immutable # :stable, :volatile (default)
+#     #   f.parallel :safe        # :restricted, :unsafe (default)
+#     #   f.security :invoker     # (default), also :definer
+#     #   f.leakproof true
+#     #   f.strict true
+#     #   f.cost 5.0
+#     #   # f.rows 1 (supported for functions returning sets of rows)
+#     #   f.comment "Multiplies 2 integers"
+#     # end
+#     # ```
+#     #
+#     # The operation can be called with `if_exists` option. In this case
+#     # it would do nothing when no function existed.
+#     #
+#     # ```ruby
+#     # drop_function "math.multiply(integer, integer)", if_exists: true
+#     # ```
+#     #
+#     # Another operation-specific option `force: :cascade` enables
+#     # to drop silently any object depending on the function.
+#     #
+#     # ```ruby
+#     # drop_function "math.multiply(integer, integer)", force: :cascade
+#     # ```
+#     #
+#     # Both options make the operation irreversible because of
+#     # uncertainty about the previous state of the database.
+#     def drop_function(name, **options, &block); end
 #   end
-#
-# The operation can be called with `if_exists` option. In this case
-# it would do nothing when no function existed.
-#
-#   drop_function "math.multiply(integer, integer)", if_exists: true
-#
-# Another operation-specific option `force: :cascade` enables
-# to drop silently any object depending on the function.
-#
-#   drop_function "math.multiply(integer, integer)", force: :cascade
-#
-# Both options make the operation irreversible because of
-# uncertainty about the previous state of the database.
-
 module PGTrunk::Operations::Functions
   # @private
   class DropFunction < Base

data/lib/pg_trunk/operations/functions/rename_function.rb

@@ -1,27 +1,34 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_function(name, to:)
-# Change the name and/or schema of a function
-#
-# @param [#to_s] :name (nil) The qualified name of the function
-# @option [#to_s] :to (nil) The new qualified name for the function
-#
-# A function can be renamed by changing both the name
-# and the schema (namespace) it belongs to.
-#
-# If there are no overloaded functions, then you can use a plain name:
-#
-#   rename_function "math.multiply", to: "public.product"
-#
-# otherwise the types of attributes must be explicitly specified.
-#
-#   rename_function "math.multiply(int, int)", to: "public.product"
-#
-# Any specification of attributes or returned values in `to:` option
-# is ignored because they cannot be changed anyway.
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of a function
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the function
+#     # @option options [#to_s] :to (nil) The new qualified name for the function
+#     # @return [void]
+#     #
+#     # A function can be renamed by changing both the name
+#     # and the schema (namespace) it belongs to.
+#     #
+#     # If there are no overloaded functions, then you can use a plain name:
+#     #
+#     # ```ruby
+#     # rename_function "math.multiply", to: "public.product"
+#     # ```
+#     #
+#     # otherwise the types of attributes must be explicitly specified.
+#     #
+#     # ```ruby
+#     # rename_function "math.multiply(int, int)", to: "public.product"
+#     # ```
+#     #
+#     # Any specification of attributes or returned values in `to:` option
+#     # is ignored because they cannot be changed anyway.
+#     #
+#     # The operation is always reversible.
+#     def rename_function(name, to:); end
+#   end
 module PGTrunk::Operations::Functions
   # @private
   class RenameFunction < Base

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

@@ -1,61 +1,71 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_materialized_view(name, **options, &block)
-# Modify 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
-# @yield [Proc] the block with the view's definition
-# @yieldparam The receiver of methods specifying the view
-#
-# The operation enables to alter a view without recreating
-# its from scratch. You can rename columns, change their
-# storage settings (how the column is TOAST-ed), or
-# customize their statistics.
-#
-#   change_materialized_view "admin_users" do |v|
-#     v.rename_column "name", to: "full_name"
-#     v.column "name", storage: "extended", from_storage: "expanded"
-#     v.column "admin", n_distinct: 2
-#     v.column "role", statistics: 100
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify 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
+#     # @yield [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation enables to alter a view without recreating
+#     # its from scratch. You can rename columns, change their
+#     # storage settings (how the column is TOAST-ed), or customize their statistics.
+#     #
+#     # ```ruby
+#     # change_materialized_view "admin_users" do |v|
+#     #   v.rename_column "name", to: "full_name"
+#     #   v.column "name", storage: "extended", from_storage: "expanded"
+#     #   v.column "admin", n_distinct: 2
+#     #   v.column "role", statistics: 100
+#     # end
+#     # ```
+#     #
+#     # Notice that renaming will be done AFTER all changes even
+#     # though the order of declarations can be different.
+#     #
+#     # As in the snippet above, to make the change invertible,
+#     # you have to define a previous storage via `from_storage` option.
+#     # The inversion would always reset statistics (set it to 0).
+#     #
+#     # In addition to changing columns, the operation enables
+#     # to set a default clustering by given index:
+#     #
+#     # ```ruby
+#     # change_materialized_view "admin_users" do |v|
+#     #   v.cluster_on "admin_users_by_names_idx"
+#     # end
+#     # ```
+#     #
+#     # The clustering is invertible, but its inversion does nothing,
+#     # keeping the clustering unchanged.
+#     #
+#     # The comment can also be changed:
+#     #
+#     # ```ruby
+#     # change_materialized_view "admin_users" do |v|
+#     #   v.comment "Admin users", from: "Admin users only"
+#     # end
+#     # ```
+#     #
+#     # Notice, that without `from` option the operation is still
+#     # invertible, but its inversion would delete the comment.
+#     # It can also be reset to the blank string explicitly:
+#     #
+#     # ```ruby
+#     # change_materialized_view "admin_users" do |v|
+#     #   v.comment "", from: "Admin users only"
+#     # end
+#     # ```
+#     #
+#     # With the `if_exists: true` option, the operation won't fail
+#     # even when the view wasn't existed. At the same time,
+#     # this option makes a migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def change_materialized_view(name, **options, &block); end
 #   end
-#
-# Notice that renaming will be done AFTER all changes even
-# though the order of declarations can be different.
-#
-# As in the snippet above, to make the change invertible,
-# you have to define a previous storage via `from_storage` option.
-# The inversion would always reset statistics (set it to 0).
-#
-# In addition to changing columns, the operation enables
-# to set a default clustering by given index:
-#
-#   change_materialized_view "admin_users" do |v|
-#     v.cluster_on "admin_users_by_names_idx"
-#   end
-#
-# The clustering is invertible, but its inversion does nothing,
-# keeping the clustering unchanged.
-#
-# The comment can also be changed:
-#
-#   change_materialized_view "admin_users" do |v|
-#     v.comment "Admin users", from: "Admin users only"
-#   end
-#
-# Notice, that without `from` option the operation is still
-# invertible, but its inversion would delete the comment.
-# It can also be reset to the blank string explicitly:
-#
-#   change_materialized_view "admin_users" do |v|
-#     v.comment "", from: "Admin users only"
-#   end
-#
-# With the `if_exists: true` option, the operation won't fail
-# even when the view wasn't existed. At the same time,
-# this option makes a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::MaterializedViews
   # @private
   class ChangeMaterializedView < Base