pg_trunk 0.1.0 → 0.2.0

data/lib/pg_trunk/operations/enums/drop_enum.rb

@@ -1,45 +1,56 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_enum(name, **options, &block)
-# Drop an enumerated type by qualified name
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [Boolean] :if_exists (false) Suppress the error when the type is absent
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @option [Array<#to_s>] :values ([]) The list of values
-# @option [#to_s] :comment (nil) The comment describing the constraint
-# @yield [Proc] the block with the type's definition
-# @yieldparam The receiver of methods specifying the type
-#
-# The operation drops a enumerated type identified by its
-# qualified name (it can include a schema).
-#
-#   drop_enum "finances.currency"
-#
-# To make the operation invertible, use the same options
-# as in the `create_enum` operation.
-#
-#   drop_enum "finances.currency" do |e|
-#     e.values "BTC", "EUR", "GBP", "USD"
-#     e.value "JPY" # the alternative way to add a value
-#     e.comment <<~COMMENT
-#       The list of values for supported currencies.
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop an enumerated type by qualified name
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the type is absent
+#     # @option options [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option options [Array<#to_s>] :values ([]) The list of values
+#     # @option options [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [e] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # The operation drops a enumerated type identified by its
+#     # qualified name (it can include a schema).
+#     #
+#     # ```ruby
+#     # drop_enum "finances.currency"
+#     # ```
+#     #
+#     # To make the operation invertible, use the same options
+#     # as in the `create_enum` operation.
+#     #
+#     # ```ruby
+#     # drop_enum "finances.currency" do |e|
+#     #   e.values "BTC", "EUR", "GBP", "USD"
+#     #   e.value "JPY" # the alternative way to add a value
+#     #   e.comment <<~COMMENT
+#     #     The list of values for supported currencies.
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # With the `force: :cascade` option the operation would remove
+#     # all the objects that use the type.
+#     #
+#     # ```ruby
+#     # drop_enum "finances.currency", force: :cascade
+#     # ```
+#     #
+#     # With the `if_exists: true` option the operation won't fail
+#     # even when the view was absent in the database.
+#     #
+#     # ```ruby
+#     # drop_enum "finances.currency", if_exists: true
+#     # ```
+#     #
+#     # Both options make a migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def drop_enum(name, **options, &block); end
 #   end
-#
-# With the `force: :cascade` option the operation would remove
-# all the objects that use the type.
-#
-#   drop_enum "finances.currency", force: :cascade
-#
-# With the `if_exists: true` option the operation won't fail
-# even when the view was absent in the database.
-#
-#   drop_enum "finances.currency", if_exists: true
-#
-# Both options make a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::Enums
   # @private
   class DropEnum < Base

data/lib/pg_trunk/operations/enums/rename_enum.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_enum(name, to:)
-# Change the name and/or schema of an enumerated type
-#
-# @param [#to_s] :name (nil) The qualified name of the type
-# @option [#to_s] :to (nil) The new qualified name for the type
-#
-# @example:
-#
-#   rename_enum "currencies", to: "finances.currency"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of an enumerated type
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the type
+#     # @option options [#to_s] :to (nil) The new qualified name for the type
+#     # @return [void]
+#     #
+#     # @example:
+#     #
+#     # ```ruby
+#     # rename_enum "currencies", to: "finances.currency"
+#     # ```
+#     #
+#     # The operation is always reversible.
+#     def rename_enum(name, to:); end
+#   end
 module PGTrunk::Operations::Enums
   # @private
   class RenameEnum < Base

data/lib/pg_trunk/operations/foreign_keys/add_foreign_key.rb

@@ -1,55 +1,64 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#add_foreign_key(table, reference, **options, &block)
-# Create a foreign key constraint
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] reference (nil) The qualified name of the reference table
-# @option [#to_s] :name (nil) The current name of the foreign key
-# @option [#to_s] :to (nil) The new name for the foreign key
-# @option [Array<#to_s>] :columns ([]) The list of columns of the table
-# @option [#to_s] :column (nil) An alias for :columns for the case of single-column keys
-# @option [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
-# @option [Symbol] :match (:full) Define how to match rows
-#   Supported values: :full (default), :partial, :simple
-# @option [Symbol] :on_delete (:restrict)
-#   Define how to handle the deletion of the referred row.
-#   Supported values: :restrict (default), :cascade, :nullify, :reset
-# @option [Symbol] :on_update (:restrict)
-#   Define how to handle the update of the referred row.
-#   Supported values: :restrict (default), :cascade, :nullify, :reset
-# @yield [Proc] the block with the key's definition
-# @yieldparam The receiver of methods specifying the foreign key
-#
-# The table and reference of the new key must be set explicitly.
-# All the rest (including the name) can be generated by default:
-#
-#   # same as `..., column: 'role_id', primary_key: 'id'`
-#   add_foreign_key :users, :roles
-#
-# The block syntax can be used for any argument:
-#
-#   add_foreign_key do |c|
-#     c.table "users"
-#     c.reference "roles"
-#     c.column "role_id" # (generated by default from reference and pk)
-#     c.primary_key "id" # (default)
-#     c.on_update :cascade # :restrict (default)
-#     c.on_delete :cascade # :restrict (default)
-#     c.name "user_roles_fk" # can be generated
-#     c.comment "Phone is 10+ chars long"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a foreign key constraint
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] reference (nil) The qualified name of the reference table
+#     # @option options [#to_s] :name (nil) The current name of the foreign key
+#     # @option options [#to_s] :to (nil) The new name for the foreign key
+#     # @option options [Array<#to_s>] :columns ([]) The list of columns of the table
+#     # @option options [#to_s] :column (nil) An alias for :columns for the case of single-column keys
+#     # @option options [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
+#     # @option options [Symbol] :match (:full) Define how to match rows
+#     #   Supported values: :full (default), :partial, :simple
+#     # @option options [Symbol] :on_delete (:restrict)
+#     #   Define how to handle the deletion of the referred row.
+#     #   Supported values: :restrict (default), :cascade, :nullify, :reset
+#     # @option options [Symbol] :on_update (:restrict)
+#     #   Define how to handle the update of the referred row.
+#     #   Supported values: :restrict (default), :cascade, :nullify, :reset
+#     # @yield [k] the block with the key's definition
+#     # @yieldparam Object receiver of methods specifying the foreign key
+#     # @return [void]
+#     #
+#     # The table and reference of the new key must be set explicitly.
+#     # All the rest (including the name) can be generated by default:
+#     #
+#     # ```ruby
+#     # # same as `..., column: 'role_id', primary_key: 'id'`
+#     # add_foreign_key :users, :roles
+#     # ```
+#     #
+#     # The block syntax can be used for any argument:
+#     #
+#     # ```ruby
+#     # add_foreign_key do |k|
+#     #   k.table "users"
+#     #   k.reference "roles"
+#     #   k.column "role_id" # (generated by default from reference and pk)
+#     #   k.primary_key "id" # (default)
+#     #   k.on_update :cascade # :restrict (default)
+#     #   k.on_delete :cascade # :restrict (default)
+#     #   k.name "user_roles_fk" # can be generated
+#     #   k.comment "Phone is 10+ chars long"
+#     # end
+#     # ```
+#     #
+#     # Composite foreign keys are supported as well:
+#     #
+#     # ```ruby
+#     # add_foreign_key "users", "roles" do |k|
+#     #   k.columns %w[role_name role_id]
+#     #   k.primary_key %w[name id] # Requires unique index
+#     #   k.match :full # :partial, :simple (default)
+#     # end
+#     # ```
+#     #
+#     # The operation is always invertible.
+#     def add_foreign_key(table, reference, **options, &block); end
 #   end
-#
-# Composite foreign keys are supported as well:
-#
-#   add_foreign_key "users", "roles" do |c|
-#     c.columns %w[role_name role_id]
-#     c.primary_key %w[name id] # Requires unique index
-#     c.match :full # :partial, :simple (default)
-#   end
-#
-# The operation is always invertible.
-
 module PGTrunk::Operations::ForeignKeys
   # @private
   class AddForeignKey < Base

data/lib/pg_trunk/operations/foreign_keys/drop_foreign_key.rb

@@ -1,54 +1,63 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_foreign_key(table, reference, **options, &block)
-# Drops a foreign key constraint
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] reference (nil) The qualified name of the reference table
-# @option [#to_s] :name (nil) The current name of the foreign key
-# @option [Boolean] :if_exists (false) Suppress the error when the constraint is absent
-# @option [#to_s] :to (nil) The new name for the foreign key
-# @option [Array<#to_s>] :columns ([]) The list of columns of the table
-# @option [#to_s] :column (nil) An alias for :columns for the case of single-column keys
-# @option [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
-# @option [Symbol] :match (:full) Define how to match rows
-#   Supported values: :full (default), :partial, :simple
-# @option [Symbol] :on_delete (:restrict)
-#   Define how to handle the deletion of the referred row.
-#   Supported values: :restrict (default), :cascade, :nullify, :reset
-# @option [Symbol] :on_update (:restrict)
-#   Define how to handle the update of the referred row.
-#   Supported values: :restrict (default), :cascade, :nullify, :reset
-# @yield [Proc] the block with the key's definition
-# @yieldparam The receiver of methods specifying the foreign key
-#
-# The key can be identified by table/name (not invertible):
-#
-#   drop_foreign_key "users", name: "user_roles_fk"
-#
-# To make it invertible use the same options like
-# in the `add_foreign_key` operation.
-#
-#   drop_foreign_key do |c|
-#     c.table "users"
-#     c.reference "roles"
-#     c.column "role_id"
-#     c.primary_key "id"
-#     c.on_update :cascade
-#     c.on_delete :cascade
-#     c.comment "Phone is 10+ chars long"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drops a foreign key constraint
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] reference (nil) The qualified name of the reference table
+#     # @option options [#to_s] :name (nil) The current name of the foreign key
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the constraint is absent
+#     # @option options [#to_s] :to (nil) The new name for the foreign key
+#     # @option options [Array<#to_s>] :columns ([]) The list of columns of the table
+#     # @option options [#to_s] :column (nil) An alias for :columns for the case of single-column keys
+#     # @option options [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
+#     # @option options [Symbol] :match (:full) Define how to match rows
+#     #   Supported values: :full (default), :partial, :simple
+#     # @option options [Symbol] :on_delete (:restrict)
+#     #   Define how to handle the deletion of the referred row.
+#     #   Supported values: :restrict (default), :cascade, :nullify, :reset
+#     # @option options [Symbol] :on_update (:restrict)
+#     #   Define how to handle the update of the referred row.
+#     #   Supported values: :restrict (default), :cascade, :nullify, :reset
+#     # @yield [k] the block with the key's definition
+#     # @yieldparam Object receiver of methods specifying the foreign key
+#     # @return [void]
+#     #
+#     # The key can be identified by table/name (not invertible):
+#     #
+#     # ```ruby
+#     # drop_foreign_key "users", name: "user_roles_fk"
+#     # ```
+#     #
+#     # To make it invertible use the same options like
+#     # in the `add_foreign_key` operation.
+#     #
+#     # ```ruby
+#     # drop_foreign_key do |k|
+#     #   k.table "users"
+#     #   k.reference "roles"
+#     #   k.column "role_id"
+#     #   k.primary_key "id"
+#     #   k.on_update :cascade
+#     #   k.on_delete :cascade
+#     #   k.comment "Phone is 10+ chars long"
+#     # end
+#     # ```
+#     #
+#     # Notice that the name can be skipped, in this case we would
+#     # find it in the database.
+#     #
+#     # The operation can be called with `if_exists` option.
+#     #
+#     # ```ruby
+#     # drop_foreign_key "users", name: "user_roles_fk", if_exists: true
+#     # ```
+#     #
+#     # In this case the operation is always irreversible due to
+#     # uncertainty of the previous state of the database.
+#     def drop_foreign_key(table, reference, **options, &block); end
 #   end
-#
-# Notice that the name can be skipped, in this case we would
-# find it in the database.
-#
-# The operation can be called with `if_exists` option.
-#
-#   drop_foreign_key "users", name: "user_roles_fk", if_exists: true
-#
-# In this case the operation is always irreversible due to
-# uncertainty of the previous state of the database.
-
 module PGTrunk::Operations::ForeignKeys
   # @private
   class DropForeignKey < Base

data/lib/pg_trunk/operations/foreign_keys/rename_foreign_key.rb

@@ -1,34 +1,43 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_foreign_key(table, reference, **options, &block)
-# Rename a foreign key
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] reference (nil) The qualified name of the reference table
-# @option [#to_s] :name (nil) The current name of the foreign key
-# @option [#to_s] :to (nil) The new name for the foreign key
-# @option [Array<#to_s>] :columns ([]) The list of columns of the table
-# @option [#to_s] :column (nil) An alias for :columns for the case of single-column keys
-# @option [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
-# @yield [Proc] the block with the key's definition
-# @yieldparam The receiver of methods specifying the foreign key
-#
-# You can rename the foreign key constraint identified by its explicit name:
-#
-#   rename_foreign_key :users,
-#                      name: "user_roles_fk",
-#                      to: "constraints.users_by_roles_fk"
-#
-# The key can also be found in the database by table/reference/columns/pk
-#
-#   rename_foreign_key :users, :roles, primary_key: "name", to: "user_roles"
-#
-# If a new name is missed, then the name will be reset to the auto-generated one:
-#
-#   rename_foreign_key :users, "user_roles_fk"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Rename a foreign key
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] reference (nil) The qualified name of the reference table
+#     # @option options [#to_s] :name (nil) The current name of the foreign key
+#     # @option options [#to_s] :to (nil) The new name for the foreign key
+#     # @option options [Array<#to_s>] :columns ([]) The list of columns of the table
+#     # @option options [#to_s] :column (nil) An alias for :columns for the case of single-column keys
+#     # @option options [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
+#     # @yield [k] the block with the key's definition
+#     # @yieldparam Object receiver of methods specifying the foreign key
+#     # @return [void]
+#     #
+#     # You can rename the foreign key constraint identified by its explicit name:
+#     #
+#     # ```ruby
+#     # rename_foreign_key :users,
+#     #                    name: "user_roles_fk",
+#     #                    to: "constraints.users_by_roles_fk"
+#     # ```
+#     #
+#     # The key can also be found in the database by table/reference/columns/pk
+#     #
+#     # ```ruby
+#     # rename_foreign_key :users, :roles, primary_key: "name", to: "user_roles"
+#     # ```
+#     #
+#     # If a new name is missed, then the name will be reset to the auto-generated one:
+#     #
+#     # ```ruby
+#     # rename_foreign_key :users, "user_roles_fk"
+#     # ```
+#     #
+#     # The operation is always reversible.
+#     def rename_foreign_key(table, reference, **options, &block); end
+#   end
 module PGTrunk::Operations::ForeignKeys
   #
   # Definition for the `rename_foreign_key` operation

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

@@ -1,52 +1,58 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_function(name, **options, &block)
-# Modify a function
-#
-# @param [#to_s] name (nil) The qualified name of the function
-# @option [Boolean] :if_exists (false) Suppress the error when the function is absent
-# @yield [Proc] the block with the function's definition
-# @yieldparam The receiver of methods specifying the function
-#
-# The operation changes the function without dropping it
-# (which can be necessary 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_function "math.mult(int, int)" do |f|
-#     f.volatility :immutable, from: :stable
-#     f.parallel :safe, from: :restricted
-#     f.security :invoker
-#     f.leakproof true
-#     f.strict true
-#     f.cost 5.0
-#     # f.rows 1 (supported for functions returning sets of rows)
-#   SQL
-#
-# The example above is not invertible because of uncertainty
-# about the previous volatility, parallelism, and cost.
-# To define them, use a from options (available in a block syntax only):
-#
-#   change_function "math.mult(a int, b int)" do |f|
-#     f.body <<~SQL, from: <<~SQL
-#       SELECT a * b;
-#     SQL
-#       SELECT min(a * b, 1);
-#     SQL
-#     f.volatility :immutable, from: :volatile
-#     f.parallel :safe, from: :unsafe
-#     f.leakproof true
-#     f.strict true
-#     f.cost 5.0, from: 100.0
-#     # f.rows 1, from: 0
-#   SQL
-#
-# Like in the other operations, the function 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 function
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the function
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the function is absent
+#     # @yield [f] the block with the function's definition
+#     # @yieldparam Object receiver of methods specifying the function
+#     # @return [void]
+#     #
+#     # The operation changes the function without dropping it
+#     # (which can be necessary 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_function "math.mult(int, int)" do |f|
+#     #   f.volatility :immutable, from: :stable
+#     #   f.parallel :safe, from: :restricted
+#     #   f.security :invoker
+#     #   f.leakproof true
+#     #   f.strict true
+#     #   f.cost 5.0
+#     #   # f.rows 1 (supported for functions returning sets of rows)
+#     # SQL
+#     # ```
+#     #
+#     # The example above is not invertible because of uncertainty
+#     # about the previous volatility, parallelism, and cost.
+#     # To define them, use a from options (available in a block syntax only):
+#     #
+#     # ```ruby
+#     # change_function "math.mult(a int, b int)" do |f|
+#     #   f.body <<~SQL, from: <<~SQL
+#     #     SELECT a * b;
+#     #   SQL
+#     #     SELECT min(a * b, 1);
+#     #   SQL
+#     #   f.volatility :immutable, from: :volatile
+#     #   f.parallel :safe, from: :unsafe
+#     #   f.leakproof true
+#     #   f.strict true
+#     #   f.cost 5.0, from: 100.0
+#     # SQL
+#     # ```
+#     #
+#     # Like in the other operations, the function 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_function(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Functions
   # @private
   class ChangeFunction < Base