pg_trunk 0.1.0 → 0.1.1

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

@@ -1,27 +1,30 @@
 # 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 [#to_s] :to (nil) The new qualified name for the view
+#     # @option [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.
+#     #
+#     #   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.
+#     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,54 @@
 # 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 [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`.
+#     #
+#     #   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.
+#     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,61 @@
 # 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 [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 [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
+#     #
+#     #   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|
+#     #     # ...
+#     #   end
+#     def create_procedure(name, **options, &block); end
 #   end
-
 module PGTrunk::Operations::Procedures
   # @private
   class CreateProcedure < Base

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

@@ -1,50 +1,53 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_procedure(name, **options, &block)
-# Drop a procedure
-#
-# @param [#to_s] name (nil)
-#   The qualified name of the procedure with arguments and returned value type
-# @option [Boolean] :if_exists (false) Suppress the error when the procedure is absent
-# @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
-#
-# A procedure can be dropped by a plain name:
-#
-#   drop_procedure "set_foo"
-#
-# If several overloaded procedures have the name,
-# then you must specify the signature having
-# types of attributes at least:
-#
-#   drop_procedure "set_foo(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_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
-#
-# The operation can be called with `if_exists` option. In this case
-# it would do nothing when no procedure existed.
-#
-#   drop_procedure "metadata.set_foo(a int)", if_exists: true
-#
-# Notice, that this option make the operation irreversible because of
-# uncertainty about the previous state of the database.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a procedure
+#     #
+#     # @param [#to_s] name (nil)
+#     #   The qualified name of the procedure with arguments and returned value type
+#     # @option [Boolean] :if_exists (false) Suppress the error when the procedure is absent
+#     # @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 [p] the block with the procedure's definition
+#     # @yieldparam Object receiver of methods specifying the procedure
+#     # @return [void]
+#     #
+#     # A procedure can be dropped by a plain name:
+#     #
+#     #   drop_procedure "set_foo"
+#     #
+#     # If several overloaded procedures have the name,
+#     # then you must specify the signature having
+#     # types of attributes at least:
+#     #
+#     #   drop_procedure "set_foo(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_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
+#     #
+#     # The operation can be called with `if_exists` option. In this case
+#     # it would do nothing when no procedure existed.
+#     #
+#     #   drop_procedure "metadata.set_foo(a int)", if_exists: true
+#     #
+#     # Notice, that this option make the operation irreversible because of
+#     # uncertainty about the previous state of the database.
+#     def drop_procedure(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Procedures
   # @private
   class DropProcedure < Base

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

@@ -1,27 +1,30 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_procedure(name, to:)
-# Change the name and/or schema of a procedure
-#
-# @param [#to_s] :name (nil) The qualified name of the procedure
-# @option [#to_s] :to (nil) The new qualified name for the procedure
-#
-# A procedure can be renamed by changing both the name
-# and the schema (namespace) it belongs to.
-#
-# If there are no overloaded procedures, then you can use a plain name:
-#
-#   rename_procedure "math.set_foo", to: "public.foo_setup"
-#
-# otherwise the types of attributes must be explicitly specified.
-#
-#   rename_procedure "math.set_foo(int)", to: "public.foo_setup"
-#
-# Any specification of attributes 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 procedure
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the procedure
+#     # @option [#to_s] :to (nil) The new qualified name for the procedure
+#     # @return [void]
+#     #
+#     # A procedure can be renamed by changing both the name
+#     # and the schema (namespace) it belongs to.
+#     #
+#     # If there are no overloaded procedures, then you can use a plain name:
+#     #
+#     #   rename_procedure "math.set_foo", to: "public.foo_setup"
+#     #
+#     # otherwise the types of attributes must be explicitly specified.
+#     #
+#     #   rename_procedure "math.set_foo(int)", to: "public.foo_setup"
+#     #
+#     # Any specification of attributes in `to:` option
+#     # is ignored because they cannot be changed anyway.
+#     #
+#     # The operation is always reversible.
+#     def rename_procedure(name, to:); end
+#   end
 module PGTrunk::Operations::Procedures
   # @private
   class RenameProcedure < Base

data/lib/pg_trunk/operations/statistics/create_statistics.rb

@@ -1,61 +1,64 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_statistics(name, **options, &block)
-# Create a custom statistics
-#
-# @param [#to_s] name (nil) The qualified name of the statistics
-# @option [Boolean] :if_not_exists (false)
-#   Suppress the error when the statistics is already exist
-# @option [#to_s] table (nil)
-#   The qualified name of the table whose statistics will be collected
-# @option [Array<Symbol>] kinds ([:dependencies, :mcv, :ndistinct])
-#   The kinds of statistics to be collected (all by default).
-#   Supported values in the array: :dependencies, :mcv, :ndistinct
-# @option [#to_s] :comment The description of the statistics
-# @yield [Proc] the block with the statistics' definition
-# @yieldparam The receiver of methods specifying the statistics
-#
-# The statistics can be created with explicit name:
-#
-#   create_statistics "users_stats" do |s|
-#     s.table "users"
-#     s.columns "family", "name"
-#     s.kinds :dependencies, :mcv, :ndistinct
-#     s.comment "Statistics for users' names and families"
-#   SQL
-#
-# The name can be generated as well:
-#
-#   create_statistics do |s|
-#     s.table "users"
-#     s.columns "family", "name"
-#     s.kinds :dependencies, :mcv, :ndistinct
-#     s.comment "Statistics for users' names and families"
-#   SQL
-#
-# Since v14 PostgreSQL have supported expressions in addition to columns:
-#
-#   create_statistics "users_stats" do |s|
-#     s.table "users"
-#     s.columns "family"
-#     s.expression "length(name)"
-#     s.kinds :dependencies, :mcv, :ndistinct
-#     s.comment "Statistics for users' name lengths and families"
-#   SQL
-#
-# as well as statistics for the sole expression (kinds must be blank)
-# by columns of some table.
-#
-#   create_statistics "users_stats" do |s|
-#     s.table "users"
-#     s.expression "length(name || ' ' || family)"
-#     s.comment "Statistics for full name lengths"
-#   SQL
-#
-# Use `if_not_exists: true` to suppress error in case the statistics
-# has already been created. This option, though, makes the migration
-# irreversible due to uncertainty of the previous state of the database.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a custom statistics
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the statistics
+#     # @option [Boolean] :if_not_exists (false)
+#     #   Suppress the error when the statistics is already exist
+#     # @option [#to_s] table (nil)
+#     #   The qualified name of the table whose statistics will be collected
+#     # @option [Array<Symbol>] kinds ([:dependencies, :mcv, :ndistinct])
+#     #   The kinds of statistics to be collected (all by default).
+#     #   Supported values in the array: :dependencies, :mcv, :ndistinct
+#     # @option [#to_s] :comment The description of the statistics
+#     # @yield [s] the block with the statistics' definition
+#     # @yieldparam Object receiver of methods specifying the statistics
+#     # @return [void]
+#     #
+#     # The statistics can be created with explicit name:
+#     #
+#     #   create_statistics "users_stats" do |s|
+#     #     s.table "users"
+#     #     s.columns "family", "name"
+#     #     s.kinds :dependencies, :mcv, :ndistinct
+#     #     s.comment "Statistics for users' names and families"
+#     #   SQL
+#     #
+#     # The name can be generated as well:
+#     #
+#     #   create_statistics do |s|
+#     #     s.table "users"
+#     #     s.columns "family", "name"
+#     #     s.kinds :dependencies, :mcv, :ndistinct
+#     #     s.comment "Statistics for users' names and families"
+#     #   SQL
+#     #
+#     # Since v14 PostgreSQL have supported expressions in addition to columns:
+#     #
+#     #   create_statistics "users_stats" do |s|
+#     #     s.table "users"
+#     #     s.columns "family"
+#     #     s.expression "length(name)"
+#     #     s.kinds :dependencies, :mcv, :ndistinct
+#     #     s.comment "Statistics for users' name lengths and families"
+#     #   SQL
+#     #
+#     # as well as statistics for the sole expression (kinds must be blank)
+#     # by columns of some table.
+#     #
+#     #   create_statistics "users_stats" do |s|
+#     #     s.table "users"
+#     #     s.expression "length(name || ' ' || family)"
+#     #     s.comment "Statistics for full name lengths"
+#     #   SQL
+#     #
+#     # Use `if_not_exists: true` to suppress error in case the statistics
+#     # has already been created. This option, though, makes the migration
+#     # irreversible due to uncertainty of the previous state of the database.
+#     def create_statistics(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Statistics
   # SQL snippet to fetch statistics in v10-13
   SQL_V10 = <<~SQL.freeze