pg_trunk 0.1.0 → 0.1.1

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

@@ -1,58 +1,61 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_statistics(name, **options, &block)
-# Drop a custom statistics
-#
-# @param [#to_s] name (nil) The qualified name of the statistics
-# @option [Boolean] :if_exists (false) Suppress the error when the statistics is absent
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @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
-#
-# A statistics can be dropped by its name only:
-#
-#   drop_statistics "my_stats"
-#
-# Such operation is irreversible. To make it inverted
-# you have to provide a full definition:
-#
-#   drop_statistics "users_stat" do |s|
-#     s.table "users"
-#     s.columns "firstname", "name"
-#     s.expression <<~SQL
-#       round(age, 10)
-#     SQL
-#     s.kinds :dependency, :mcv, :ndistinct
-#     p.comment "Statistics for name, firstname, and rough age"
-#   SQL
-#
-# If the statistics was anonymous (used the generated name),
-# it can be dropped without defining the name as well:
-#
-#   drop_statistics do |s|
-#     s.table "users"
-#     s.columns "firstname", "name"
-#     s.expression <<~SQL
-#       round(age, 10)
-#     SQL
-#     s.kinds :dependency, :mcv, :ndistinct
-#     p.comment "Statistics for name, firstname, and rough age"
-#   SQL
-#
-# The operation can be called with `if_exists` option. In this case
-# it would do nothing when no statistics existed.
-#
-#   drop_procedure "unknown_statistics", 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 custom statistics
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the statistics
+#     # @option [Boolean] :if_exists (false) Suppress the error when the statistics is absent
+#     # @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @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]
+#     #
+#     # A statistics can be dropped by its name only:
+#     #
+#     #   drop_statistics "my_stats"
+#     #
+#     # Such operation is irreversible. To make it inverted
+#     # you have to provide a full definition:
+#     #
+#     #   drop_statistics "users_stat" do |s|
+#     #     s.table "users"
+#     #     s.columns "firstname", "name"
+#     #     s.expression <<~SQL
+#     #       round(age, 10)
+#     #     SQL
+#     #     s.kinds :dependency, :mcv, :ndistinct
+#     #     p.comment "Statistics for name, firstname, and rough age"
+#     #   SQL
+#     #
+#     # If the statistics was anonymous (used the generated name),
+#     # it can be dropped without defining the name as well:
+#     #
+#     #   drop_statistics do |s|
+#     #     s.table "users"
+#     #     s.columns "firstname", "name"
+#     #     s.expression <<~SQL
+#     #       round(age, 10)
+#     #     SQL
+#     #     s.kinds :dependency, :mcv, :ndistinct
+#     #     p.comment "Statistics for name, firstname, and rough age"
+#     #   SQL
+#     #
+#     # The operation can be called with `if_exists` option. In this case
+#     # it would do nothing when no statistics existed.
+#     #
+#     #   drop_procedure "unknown_statistics", if_exists: true
+#     #
+#     # Notice, that this option make the operation irreversible because of
+#     # uncertainty about the previous state of the database.
+#     def drop_statistics(name, **options, &block); end
+#   end
 module PGTrunk::Operations::Statistics
   # @private
   class DropStatistics < Base

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

@@ -1,18 +1,21 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_statistics(name, to:)
-# Change the name and/or schema of a statistics
-#
-# @param [#to_s] :name (nil) The qualified name of the statistics
-# @option [#to_s] :to (nil) The new qualified name for the statistics
-#
-# A custom statistics can be renamed by changing both the name
-# and the schema (namespace) it belongs to.
-#
-#   rename_statistics "math.my_stat", to: "public.my_stats"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of a statistics
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the statistics
+#     # @option [#to_s] :to (nil) The new qualified name for the statistics
+#     # @return [void]
+#     #
+#     # A custom statistics can be renamed by changing both the name
+#     # and the schema (namespace) it belongs to.
+#     #
+#     #   rename_statistics "math.my_stat", to: "public.my_stats"
+#     #
+#     # The operation is always reversible.
+#     def rename_statistics(name, to:); end
+#   end
 module PGTrunk::Operations::Statistics
   # @private
   class RenameStatistics < Base

data/lib/pg_trunk/operations/triggers/change_trigger.rb

@@ -1,24 +1,27 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_trigger(table, name = nil, **options, &block)
-# Create a trigger for a table
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] name (nil) The name of the trigger
-# @option [Boolean] :if_exists (false) Suppress the error when the trigger is absent
-# @yield [Proc] the block with the trigger's definition
-# @yieldparam The receiver of methods specifying the trigger
-#
-# The trigger can be changed using `CREATE OR REPLACE TRIGGER` command:
-#
-#   change_trigger "users", "do_something" do |t|
-#     t.function "do_something()", from: "do_something_different()"
-#     t.for_each :row # from: :statement
-#     t.type :after, from: :before
-#     t.events %i[insert update], from: %i[insert]
-#     t.comment "Does something useful", from: ""
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a trigger for a table
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] name (nil) The name of the trigger
+#     # @option [Boolean] :if_exists (false) Suppress the error when the trigger is absent
+#     # @yield [t] the block with the trigger's definition
+#     # @yieldparam Object receiver of methods specifying the trigger
+#     # @return [void]
+#     #
+#     # The trigger can be changed using `CREATE OR REPLACE TRIGGER` command:
+#     #
+#     #   change_trigger "users", "do_something" do |t|
+#     #     t.function "do_something()", from: "do_something_different()"
+#     #     t.for_each :row # from: :statement
+#     #     t.type :after, from: :before
+#     #     t.events %i[insert update], from: %i[insert]
+#     #     t.comment "Does something useful", from: ""
+#     #   end
+#     def create_trigger(table, name = nil, **options, &block); end
 #   end
-
 module PGTrunk::Operations::Triggers
   # @private
   class ChangeTrigger < Base

data/lib/pg_trunk/operations/triggers/create_trigger.rb

@@ -1,60 +1,63 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_trigger(table, name = nil, **options, &block)
-# Create a trigger for a table
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] name (nil) The name of the trigger
-# @option [Boolean] :replace_existing (false) If the trigger should overwrite an existing one
-# @option [#to_s] :function (nil) The qualified name of the function to be called
-# @option [Symbol] :type (nil) When the trigger should be run
-#   Supported values: :before, :after, :instead_of
-# @option [Array<Symbol>] :events List of events running the trigger
-#   Supported values in the array: :insert, :update, :delete, :truncate
-# @option [Boolean] :constraint (false) If the trigger is a constraint
-# @option [Symbol] :initially (:immediate) If the constraint check should be deferred
-#   Supported values: :immediate (default), :deferred
-# @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
-# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
-#   Supported values: :statement (default), :row
-# @option [#to_s] :comment (nil) The commend describing the trigger
-# @yield [Proc] the block with the trigger's definition
-# @yieldparam The receiver of methods specifying the trigger
-#
-# The trigger can be created either using inline syntax
-#
-#   create_trigger "users", "do_something",
-#                   function: "do_something()",
-#                   for_each: :row,
-#                   type: :after,
-#                   events: %i[insert update],
-#                   comment: "Does something useful"
-#
-# or using a block:
-#
-#   create_trigger do |t|
-#     t.table "users"
-#     t.name "do_something"
-#     t.function "do_something()"
-#     t.for_each :row
-#     t.type :after
-#     t.events %i[insert update]
-#     t.comment "Does something useful"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a trigger for a table
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] name (nil) The name of the trigger
+#     # @option [Boolean] :replace_existing (false) If the trigger should overwrite an existing one
+#     # @option [#to_s] :function (nil) The qualified name of the function to be called
+#     # @option [Symbol] :type (nil) When the trigger should be run
+#     #   Supported values: :before, :after, :instead_of
+#     # @option [Array<Symbol>] :events List of events running the trigger
+#     #   Supported values in the array: :insert, :update, :delete, :truncate
+#     # @option [Boolean] :constraint (false) If the trigger is a constraint
+#     # @option [Symbol] :initially (:immediate) If the constraint check should be deferred
+#     #   Supported values: :immediate (default), :deferred
+#     # @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
+#     # @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#     #   Supported values: :statement (default), :row
+#     # @option [#to_s] :comment (nil) The commend describing the trigger
+#     # @yield [t] the block with the trigger's definition
+#     # @yieldparam Object receiver of methods specifying the trigger
+#     # @return [void]
+#     #
+#     # The trigger can be created either using inline syntax
+#     #
+#     #   create_trigger "users", "do_something",
+#     #                   function: "do_something()",
+#     #                   for_each: :row,
+#     #                   type: :after,
+#     #                   events: %i[insert update],
+#     #                   comment: "Does something useful"
+#     #
+#     # or using a block:
+#     #
+#     #   create_trigger do |t|
+#     #     t.table "users"
+#     #     t.name "do_something"
+#     #     t.function "do_something()"
+#     #     t.for_each :row
+#     #     t.type :after
+#     #     t.events %i[insert update]
+#     #     t.comment "Does something useful"
+#     #   end
+#     #
+#     # With a `replace_existing: true` option,
+#     # it will be created using the `CREATE OR REPLACE` clause.
+#     # (Available in PostgreSQL v14+).
+#     #
+#     #    create_trigger "users", "do_something",
+#     #                   function: "do_something()",
+#     #                   type: :after,
+#     #                   events: %i[insert update],
+#     #                   replace_previous: true
+#     #
+#     # In this case the migration is irreversible because we
+#     # don't know if and how to restore its previous definition.
+#     def create_trigger(table, name = nil, **options, &block); end
 #   end
-#
-# With a `replace_existing: true` option,
-# it will be created using the `CREATE OR REPLACE` clause.
-# (Available in PostgreSQL v14+).
-#
-#    create_trigger "users", "do_something",
-#                   function: "do_something()",
-#                   type: :after,
-#                   events: %i[insert update],
-#                   replace_previous: true
-#
-# In this case the migration is irreversible because we
-# don't know if and how to restore its previous definition.
-
 module PGTrunk::Operations::Triggers
   # @private
   class CreateTrigger < Base

data/lib/pg_trunk/operations/triggers/drop_trigger.rb

@@ -1,52 +1,55 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_trigger(table, name = nil, **options, &block)
-# Drop a trigger for a table
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] name (nil) The name of the trigger
-# @option [Boolean] :if_exists (false) Suppress the error when the trigger is absent
-# @option [#to_s] :function (nil) The qualified name of the function to be called
-# @option [Symbol] :type (nil) When the trigger should be run
-#   Supported values: :before, :after, :instead_of
-# @option [Array<Symbol>] :events List of events running the trigger
-#   Supported values in the array: :insert, :update, :delete, :truncate
-# @option [Boolean] :constraint (false) If the trigger is a constraint
-# @option [Symbol] :initially (:immediate) If the constraint check should be deferred
-#   Supported values: :immediate (default), :deferred
-# @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
-# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
-#   Supported values: :statement (default), :row
-# @option [#to_s] :comment (nil) The commend describing the trigger
-# @yield [Proc] the block with the trigger's definition
-# @yieldparam The receiver of methods specifying the trigger
-#
-# A trigger can be dropped by a table and name:
-#
-#   drop_trigger "users", "do_something"
-#
-# the default name can be restored from its attributes as well.
-#
-#   drop_trigger "users" do |t|
-#     t.function "send_notifications()"
-#     t.for_each :row
-#     t.type :after
-#     t.events %i[update]
-#     t.columns %w[email phone]
-#     t.comment "Does something"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a trigger for a table
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] name (nil) The name of the trigger
+#     # @option [Boolean] :if_exists (false) Suppress the error when the trigger is absent
+#     # @option [#to_s] :function (nil) The qualified name of the function to be called
+#     # @option [Symbol] :type (nil) When the trigger should be run
+#     #   Supported values: :before, :after, :instead_of
+#     # @option [Array<Symbol>] :events List of events running the trigger
+#     #   Supported values in the array: :insert, :update, :delete, :truncate
+#     # @option [Boolean] :constraint (false) If the trigger is a constraint
+#     # @option [Symbol] :initially (:immediate) If the constraint check should be deferred
+#     #   Supported values: :immediate (default), :deferred
+#     # @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
+#     # @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#     #   Supported values: :statement (default), :row
+#     # @option [#to_s] :comment (nil) The commend describing the trigger
+#     # @yield [t] the block with the trigger's definition
+#     # @yieldparam Object receiver of methods specifying the trigger
+#     # @return [void]
+#     #
+#     # A trigger can be dropped by a table and name:
+#     #
+#     #   drop_trigger "users", "do_something"
+#     #
+#     # the default name can be restored from its attributes as well.
+#     #
+#     #   drop_trigger "users" do |t|
+#     #     t.function "send_notifications()"
+#     #     t.for_each :row
+#     #     t.type :after
+#     #     t.events %i[update]
+#     #     t.columns %w[email phone]
+#     #     t.comment "Does something"
+#     #   end
+#     #
+#     # Notice, that you have to specify all attributes to make
+#     # the operation reversible.
+#     #
+#     # The operation can be called with `if_exists` option. In this case
+#     # it would do nothing when no trigger existed.
+#     #
+#     #   drop_trigger "users", "unknown_trigger", if_exists: true
+#     #
+#     # This option, though, makes the operation irreversible because of
+#     # uncertainty of the previous state of the database.
+#     def drop_trigger(table, name = nil, **options, &block); end
 #   end
-#
-# Notice, that you have to specify all attributes to make
-# the operation reversible.
-#
-# The operation can be called with `if_exists` option. In this case
-# it would do nothing when no trigger existed.
-#
-#   drop_trigger "users", "unknown_trigger", if_exists: true
-#
-# This option, though, makes the operation irreversible because of
-# uncertainty of the previous state of the database.
-
 module PGTrunk::Operations::Triggers
   # @private
   class DropTrigger < Base

data/lib/pg_trunk/operations/triggers/rename_trigger.rb

@@ -1,54 +1,57 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_trigger(table, name = nil, **options, &block)
-# Rename a trigger
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] name (nil) The name of the trigger
-# @option [#to_s] :to (nil) The new name of the trigger
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] name (nil) The current name of the trigger
-# @option [#to_s] :to (nil) The new name for the trigger
-# @option [#to_s] :function (nil) The qualified name of the function to be called
-# @option [Symbol] :type (nil) When the trigger should be run
-#   Supported values: :before, :after, :instead_of
-# @option [Array<Symbol>] :events List of events running the trigger
-#   Supported values in the array: :insert, :update, :delete, :truncate
-# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
-#   Supported values: :statement (default), :row
-# @yield [Proc] the block with the trigger's definition
-# @yieldparam The receiver of methods specifying the trigger
-#
-# A trigger can be renamed by either setting a new name explicitly
-#
-#   rename_trigger "users", "do_something", to: "do_something_different"
-#
-# or resetting it to the default (generated) value.
-#
-#   rename_trigger "users", "do_something"
-#
-# The previously generated name of the trigger can be get
-# from its parameters. In this case all the essentials
-# parameters must be specified:
-#
-#   rename_trigger "users", to: "do_something_different" do |t|
-#     t.function "do_something()"
-#     t.for_each :row
-#     t.type :after
-#     t.events %i[insert update]
+# @!parse
+#   class ActiveRecord::Migration
+#     # Rename a trigger
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] name (nil) The name of the trigger
+#     # @option [#to_s] :to (nil) The new name of the trigger
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] name (nil) The current name of the trigger
+#     # @option [#to_s] :to (nil) The new name for the trigger
+#     # @option [#to_s] :function (nil) The qualified name of the function to be called
+#     # @option [Symbol] :type (nil) When the trigger should be run
+#     #   Supported values: :before, :after, :instead_of
+#     # @option [Array<Symbol>] :events List of events running the trigger
+#     #   Supported values in the array: :insert, :update, :delete, :truncate
+#     # @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#     #   Supported values: :statement (default), :row
+#     # @yield [t] the block with the trigger's definition
+#     # @yieldparam Object receiver of methods specifying the trigger
+#     # @return [void]
+#     #
+#     # A trigger can be renamed by either setting a new name explicitly
+#     #
+#     #   rename_trigger "users", "do_something", to: "do_something_different"
+#     #
+#     # or resetting it to the default (generated) value.
+#     #
+#     #   rename_trigger "users", "do_something"
+#     #
+#     # The previously generated name of the trigger can be get
+#     # from its parameters. In this case all the essentials
+#     # parameters must be specified:
+#     #
+#     #   rename_trigger "users", to: "do_something_different" do |t|
+#     #     t.function "do_something()"
+#     #     t.for_each :row
+#     #     t.type :after
+#     #     t.events %i[insert update]
+#     #   end
+#     #
+#     # In the same way, when you reset the name to default,
+#     # all the essential parameters must be got to make the trigger
+#     # invertible.
+#     #
+#     #   rename_trigger "users", "do_something" do |t|
+#     #     t.function "do_something()"
+#     #     t.for_each :row
+#     #     t.type :after
+#     #     t.events %i[insert update]
+#     #   end
+#     def rename_trigger(table, name = nil, **options, &block); end
 #   end
-#
-# In the same way, when you reset the name to default,
-# all the essential parameters must be got to make the trigger
-# invertible.
-#
-#   rename_trigger "users", "do_something" do |t|
-#     t.function "do_something()"
-#     t.for_each :row
-#     t.type :after
-#     t.events %i[insert update]
-#   end
-
 module PGTrunk::Operations::Triggers
   # @private
   class RenameTrigger < Base

data/lib/pg_trunk/operations/views/change_view.rb

@@ -1,44 +1,47 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_view(name, **options, &block)
-# Modify a 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 replaces the view with a new definition(s):
-#
-#   change_view "admin_users" do |v|
-#     v.sql_definition: <<~SQL, from: <<~SQL
-#       SELECT id, name FROM users WHERE admin;
-#     SQL
-#       SELECT * FROM users WHERE admin;
-#     SQL
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify a 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 [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation replaces the view with a new definition(s):
+#     #
+#     #   change_view "admin_users" do |v|
+#     #     v.sql_definition: <<~SQL, from: <<~SQL
+#     #       SELECT id, name FROM users WHERE admin;
+#     #     SQL
+#     #       SELECT * FROM users WHERE admin;
+#     #     SQL
+#     #   end
+#     #
+#     # For some compatibility to the `scenic` gem, we also support
+#     # adding a definition via its version:
+#     #
+#     #    change_view "admin_users" do |v|
+#     #      v.version 2, from: 1
+#     #    end
+#     #
+#     # It is expected, that both `db/views/admin_users_v01.sql`
+#     # and `db/views/admin_users_v02.sql` to contain SQL snippets.
+#     #
+#     # Please, notice that neither deletion of columns,
+#     # nor changing their types is supported by the PostgreSQL.
+#     #
+#     # You can also (re)set a comment describing the view,
+#     # and the check option (either `:local` or `:cascaded`):
+#     #
+#     #   change_view "admin_users" do |v|
+#     #     v.check :local, from: :cascaded
+#     #     v.comment "Admin users only", from: ""
+#     #   end
+#     def change_view(name, **options, &block); end
 #   end
-#
-# For some compatibility to the `scenic` gem, we also support
-# adding a definition via its version:
-#
-#    change_view "admin_users" do |v|
-#      v.version 2, from: 1
-#    end
-#
-# It is expected, that both `db/views/admin_users_v01.sql`
-# and `db/views/admin_users_v02.sql` to contain SQL snippets.
-#
-# Please, notice that neither deletion of columns,
-# nor changing their types is supported by the PostgreSQL.
-#
-# You can also (re)set a comment describing the view,
-# and the check option (either `:local` or `:cascaded`):
-#
-#   change_view "admin_users" do |v|
-#     v.check :local, from: :cascaded
-#     v.comment "Admin users only", from: ""
-#   end
-
 module PGTrunk::Operations::Views
   # @private
   class ChangeView < Base