pg_trunk 0.1.0 → 0.1.1

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

@@ -1,71 +1,74 @@
 # 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 [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 [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:
+#     #
+#     #   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"
+#     #   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.
+#     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,30 @@
 # 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 [#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:
+#     #
+#     #   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.
+#     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,64 @@
 # 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 [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.
+#     #
+#     #   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:
+#     #
+#     #   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.
+#     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

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

@@ -1,77 +1,80 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_materialized_view(name, **options, &block)
-# Create a materialized view
-#
-# @param [#to_s] name (nil) The qualified name of the view
-# @option [Boolean] :if_not_exists (false) Suppress the error when a view has been already created
-# @option [#to_s] :sql_definition (nil) The snippet containing the query
-# @option [#to_i] :version (nil)
-#   The alternative way to set sql_definition by referencing to a file containing the snippet
-# @option [#to_s] :tablespace (nil) The tablespace for the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [#to_s] :comment (nil) The comment describing the view
-# @yield [Proc] the block with the view's definition
-# @yieldparam The receiver of methods specifying the view
-#
-# The operation creates the view using its `sql_definition`:
-#
-#   create_materialized_view("views.admin_users", sql_definition: <<~SQL)
-#     SELECT id, name FROM users WHERE admin;
-#   SQL
-#
-# For compatibility to the `scenic` gem, we also support
-# adding a definition via its version:
-#
-#    create_materialized_view "admin_users", version: 1
-#
-# It is expected, that a `db/materialized_views/admin_users_v01.sql`
-# to contain the SQL snippet.
-#
-# The tablespace can be specified for the created view.
-# Notice that later it can't be changed (in PostgreSQL all rows
-# can be moved to another tablespace, but we don't support
-# this feature yet).
-#
-#   create_materialized_view "admin_users" do |v|
-#     v.tablespace "fast_ssd"
-#     v.sql_definition <<~SQL
-#       SELECT id, name, password, admin, on_duty
-#       FROM users
-#       WHERE admin
-#     SQL
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a materialized view
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the view
+#     # @option [Boolean] :if_not_exists (false) Suppress the error when a view has been already created
+#     # @option [#to_s] :sql_definition (nil) The snippet containing the query
+#     # @option [#to_i] :version (nil)
+#     #   The alternative way to set sql_definition by referencing to a file containing the snippet
+#     # @option [#to_s] :tablespace (nil) The tablespace for the view
+#     # @option [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option [#to_s] :comment (nil) The comment describing the view
+#     # @yield [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation creates the view using its `sql_definition`:
+#     #
+#     #   create_materialized_view("views.admin_users", sql_definition: <<~SQL)
+#     #     SELECT id, name FROM users WHERE admin;
+#     #   SQL
+#     #
+#     # For compatibility to the `scenic` gem, we also support
+#     # adding a definition via its version:
+#     #
+#     #    create_materialized_view "admin_users", version: 1
+#     #
+#     # It is expected, that a `db/materialized_views/admin_users_v01.sql`
+#     # to contain the SQL snippet.
+#     #
+#     # The tablespace can be specified for the created view.
+#     # Notice that later it can't be changed (in PostgreSQL all rows
+#     # can be moved to another tablespace, but we don't support
+#     # this feature yet).
+#     #
+#     #   create_materialized_view "admin_users" do |v|
+#     #     v.tablespace "fast_ssd"
+#     #     v.sql_definition <<~SQL
+#     #       SELECT id, name, password, admin, on_duty
+#     #       FROM users
+#     #       WHERE admin
+#     #     SQL
+#     #   end
+#     #
+#     # You can also set a comment describing the view,
+#     # and redefine the storage options for some TOAST-ed columns,
+#     # as well as their custom statistics:
+#     #
+#     #   create_materialized_view "admin_users" do |v|
+#     #     v.sql_definition <<~SQL
+#     #       SELECT id, name, password, admin, on_duty
+#     #       FROM users
+#     #       WHERE admin
+#     #     SQL
+#     #
+#     #     v.column "password", storage: "external" # to avoid compression
+#     #     v.column "password", n_distinct: -1 # linear dependency
+#     #     v.column "admin", n_distinct: 1 # exact number of values
+#     #     v.column "on_duty", statistics: 2 # the total number of values
+#     #
+#     #     v.comment "Admin users only"
+#     #   end
+#     #
+#     # With the `replace_existing: true` option the operation
+#     # would use `CREATE OR REPLACE VIEW` command, so it
+#     # can be used to "update" (or reload) the existing view.
+#     #
+#     #   create_materialized_view "admin_users",
+#     #                            version: 1,
+#     #                            replace_existing: true
+#     #
+#     # This option makes the migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def create_materialized_view(name, **options, &block); end
 #   end
-#
-# You can also set a comment describing the view,
-# and redefine the storage options for some TOAST-ed columns,
-# as well as their custom statistics:
-#
-#   create_materialized_view "admin_users" do |v|
-#     v.sql_definition <<~SQL
-#       SELECT id, name, password, admin, on_duty
-#       FROM users
-#       WHERE admin
-#     SQL
-#
-#     v.column "password", storage: "external" # to avoid compression
-#     v.column "password", n_distinct: -1 # linear dependency
-#     v.column "admin", n_distinct: 1 # exact number of values
-#     v.column "on_duty", statistics: 2 # the total number of values
-#
-#     v.comment "Admin users only"
-#   end
-#
-# With the `replace_existing: true` option the operation
-# would use `CREATE OR REPLACE VIEW` command, so it
-# can be used to "update" (or reload) the existing view.
-#
-#   create_materialized_view "admin_users",
-#                            version: 1,
-#                            replace_existing: true
-#
-# This option makes the migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::MaterializedViews
   # @private
   class CreateMaterializedView < Base

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

@@ -1,52 +1,55 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_materialized_view(name, **options, &block)
-# Drop 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
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @option [#to_s] :sql_definition (nil) The snippet containing the query
-# @option [#to_i] :revert_to_version (nil)
-#   The alternative way to set sql_definition by referencing to a file containing the snippet
-# @option [#to_s] :tablespace (nil) The tablespace for the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [#to_s] :comment (nil) The comment describing the view
-# @yield [Proc] the block with the view's definition
-# @yieldparam The receiver of methods specifying the view
-#
-# The operation drops a materialized view identified by its
-# qualified name (it can include a schema).
-#
-#   drop_materialized_view "views.admin_users"
-#
-# To make the operation invertible, use the same options
-# as in the `create_view` operation.
-#
-#   drop_materialized_view "views.admin_users" do |v|
-#     v.sql_definition "SELECT name, password FROM users WHERE admin;"
-#     v.column "password", storage: "external" # prevent compression
-#     v.with_data false
-#     v.comment "Admin users only"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop 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
+#     # @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option [#to_s] :sql_definition (nil) The snippet containing the query
+#     # @option [#to_i] :revert_to_version (nil)
+#     #   The alternative way to set sql_definition by referencing to a file containing the snippet
+#     # @option [#to_s] :tablespace (nil) The tablespace for the view
+#     # @option [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option [#to_s] :comment (nil) The comment describing the view
+#     # @yield [v] the block with the view's definition
+#     # @yieldparam Object receiver of methods specifying the view
+#     # @return [void]
+#     #
+#     # The operation drops a materialized view identified by its
+#     # qualified name (it can include a schema).
+#     #
+#     #   drop_materialized_view "views.admin_users"
+#     #
+#     # To make the operation invertible, use the same options
+#     # as in the `create_view` operation.
+#     #
+#     #   drop_materialized_view "views.admin_users" do |v|
+#     #     v.sql_definition "SELECT name, password FROM users WHERE admin;"
+#     #     v.column "password", storage: "external" # prevent compression
+#     #     v.with_data false
+#     #     v.comment "Admin users only"
+#     #   end
+#     #
+#     # You can also use a version-base SQL definition like:
+#     #
+#     #    drop_materialized_view "admin_users", revert_to_version: 1
+#     #
+#     # With the `force: :cascade` option the operation would remove
+#     # all the objects which depend on the view.
+#     #
+#     #   drop_materialized_view "admin_users", force: :cascade
+#     #
+#     # With the `if_exists: true` option the operation won't fail
+#     # even when the view was absent in the database.
+#     #
+#     #   drop_materialized_view "admin_users", if_exists: true
+#     #
+#     # Both options make a migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def drop_materialized_view(name, **options, &block); end
 #   end
-#
-# You can also use a version-base SQL definition like:
-#
-#    drop_materialized_view "admin_users", revert_to_version: 1
-#
-# With the `force: :cascade` option the operation would remove
-# all the objects which depend on the view.
-#
-#   drop_materialized_view "admin_users", force: :cascade
-#
-# With the `if_exists: true` option the operation won't fail
-# even when the view was absent in the database.
-#
-#   drop_materialized_view "admin_users", if_exists: true
-#
-# Both options make a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::MaterializedViews
   # @private
   class DropMaterializedView < Base

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

@@ -1,29 +1,32 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#refresh_materialized_view(name, **options)
-# Refresh a materialized view
-#
-# @param [#to_s] name (nil) The qualified name of the view
-# @option [Boolean] :with_data (true) If the view should be populated after creation
-# @option [Symbol] :algorithm (nil) Makes the operation concurrent when set to :concurrently
-#
-# The operation enables refreshing a materialized view
-# by reloading its underlying SQL query:
-#
-#   refresh_materialized_view "admin_users"
-#
-# The option `algorithm: :concurrently` acts exactly
-# like in the `create_index` definition. You should
-# possibly add the `disable_ddl_transaction!` command
-# to the migration as well.
-#
-# With option `with_data: false` the command won't
-# update the data. This option can't be used along with
-# the `:algorithm`.
-#
-# The operation is always reversible, though its
-# inversion does nothing.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Refresh a materialized view
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the view
+#     # @option [Boolean] :with_data (true) If the view should be populated after creation
+#     # @option [Symbol] :algorithm (nil) Makes the operation concurrent when set to :concurrently
+#     # @return [void]
+#     #
+#     # The operation enables refreshing a materialized view
+#     # by reloading its underlying SQL query:
+#     #
+#     #   refresh_materialized_view "admin_users"
+#     #
+#     # The option `algorithm: :concurrently` acts exactly
+#     # like in the `create_index` definition. You should
+#     # possibly add the `disable_ddl_transaction!` command
+#     # to the migration as well.
+#     #
+#     # With option `with_data: false` the command won't
+#     # update the data. This option can't be used along with
+#     # the `:algorithm`.
+#     #
+#     # The operation is always reversible, though its
+#     # inversion does nothing.
+#     def refresh_materialized_view(name, **options); end
+#   end
 module PGTrunk::Operations::MaterializedViews
   # @private
   class RefreshMaterializedView < Base