pg_trunk 0.1.1 → 0.1.2

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

@@ -16,28 +16,36 @@
 #     # The operation drops a enumerated type identified by its
 #     # qualified name (it can include a schema).
 #     #
-#     #   drop_enum "finances.currency"
+#     # ```ruby
+#     # 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
-#     #   end
+#     # ```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.
 #     #
-#     #   drop_enum "finances.currency", force: :cascade
+#     # ```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.
 #     #
-#     #   drop_enum "finances.currency", if_exists: true
+#     # ```ruby
+#     # drop_enum "finances.currency", if_exists: true
+#     # ```
 #     #
 #     # Both options make a migration irreversible due to uncertainty
 #     # of the previous state of the database.

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

@@ -10,7 +10,9 @@
 #     #
 #     # @example:
 #     #
-#     #   rename_enum "currencies", to: "finances.currency"
+#     # ```ruby
+#     # rename_enum "currencies", to: "finances.currency"
+#     # ```
 #     #
 #     # The operation is always reversible.
 #     def rename_enum(name, to:); end

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

@@ -26,29 +26,35 @@
 #     # 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
+#     # ```ruby
+#     # # 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
+#     # ```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:
 #     #
-#     #   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
+#     # ```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

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

@@ -26,27 +26,33 @@
 #     #
 #     # The key can be identified by table/name (not invertible):
 #     #
-#     #   drop_foreign_key "users", name: "user_roles_fk"
+#     # ```ruby
+#     # 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
+#     # ```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.
 #     #
-#     #   drop_foreign_key "users", name: "user_roles_fk", if_exists: true
+#     # ```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.

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

@@ -17,17 +17,23 @@
 #     #
 #     # 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"
+#     # ```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
 #     #
-#     #   rename_foreign_key :users, :roles, primary_key: "name", to: "user_roles"
+#     # ```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:
 #     #
-#     #   rename_foreign_key :users, "user_roles_fk"
+#     # ```ruby
+#     # rename_foreign_key :users, "user_roles_fk"
+#     # ```
 #     #
 #     # The operation is always reversible.
 #     def rename_foreign_key(table, reference, **options, &block); end

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

@@ -17,33 +17,36 @@
 #     # 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
+#     # ```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):
 #     #
-#     #   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
+#     # ```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).

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

@@ -26,46 +26,54 @@
 #     #
 #     # 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"
+#     # ```ruby
+#     # 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"
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # # 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

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

@@ -28,42 +28,52 @@
 #     #
 #     # A function can be dropped by a plain name:
 #     #
-#     #   drop_function "multiply"
+#     # ```ruby
+#     # 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)"
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # drop_function "math.multiply(integer, integer)", force: :cascade
+#     # ```
 #     #
 #     # Both options make the operation irreversible because of
 #     # uncertainty about the previous state of the database.

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

@@ -13,11 +13,15 @@
 #     #
 #     # If there are no overloaded functions, then you can use a plain name:
 #     #
-#     #   rename_function "math.multiply", to: "public.product"
+#     # ```ruby
+#     # 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"
+#     # ```ruby
+#     # 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.

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

@@ -12,15 +12,16 @@
 #     #
 #     # 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.
+#     # 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
+#     # ```ruby
+#     # 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.
@@ -32,26 +33,32 @@
 #     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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,

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

@@ -18,14 +18,18 @@
 #     #
 #     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # create_materialized_view "admin_users", version: 1
+#     # ```
 #     #
 #     # It is expected, that a `db/materialized_views/admin_users_v01.sql`
 #     # to contain the SQL snippet.
@@ -35,41 +39,45 @@
 #     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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.

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

@@ -20,31 +20,41 @@
 #     # The operation drops a materialized view identified by its
 #     # qualified name (it can include a schema).
 #     #
-#     #   drop_materialized_view "views.admin_users"
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # drop_materialized_view "admin_users", if_exists: true
+#     # ```
 #     #
 #     # Both options make a migration irreversible due to uncertainty
 #     # of the previous state of the database.

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

@@ -12,7 +12,9 @@
 #     # The operation enables refreshing a materialized view
 #     # by reloading its underlying SQL query:
 #     #
-#     #   refresh_materialized_view "admin_users"
+#     # ```ruby
+#     # refresh_materialized_view "admin_users"
+#     # ```
 #     #
 #     # The option `algorithm: :concurrently` acts exactly
 #     # like in the `create_index` definition. You should