pg_trunk 0.1.0 → 0.1.1

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

@@ -1,55 +1,58 @@
 # 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 [#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 [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:
+#     #
+#     #   # 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 |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:
+#     #
+#     #   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,57 @@
 # 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 [#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 [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):
+#     #
+#     #   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 |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.
+#     #
+#     #   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,37 @@
 # 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 [#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 [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:
+#     #
+#     #   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.
+#     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,55 @@
 # 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 [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`.
+#     #
+#     #   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.
+#     def change_function(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Functions
   # @private
   class ChangeFunction < Base

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

@@ -1,70 +1,73 @@
 # 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 [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 [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
+#     #
+#     #   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|
+#     #     # ...
+#     #   end
+#     def create_function(name, **options, &block); end
 #   end
-
 module PGTrunk::Operations::Functions
   # @private
   class CreateFunction < Base