pg_trunk 0.1.1 → 0.1.2

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

@@ -12,14 +12,18 @@
 #     # A materialized view can be renamed by changing both the name
 #     # and the schema (namespace) it belongs to.
 #     #
-#     #   rename_materialized_view "views.admin_users", to: "admins"
+#     # ```ruby
+#     # rename_materialized_view "views.admin_users", to: "admins"
+#     # ```
 #     #
 #     # With the `if_exists: true` option, the operation won't fail
 #     # even when the view wasn't existed.
 #     #
-#     #   rename_materialized_view "admin_users",
-#     #                            to: "admins",
-#     #                            if_exists: true
+#     # ```ruby
+#     # rename_materialized_view "admin_users",
+#     #                          to: "admins",
+#     #                          if_exists: true
+#     # ```
 #     #
 #     # At the same time, the option makes a migration irreversible
 #     # due to uncertainty of the previous state of the database.

data/lib/pg_trunk/operations/procedures/change_procedure.rb

@@ -17,31 +17,35 @@
 #     # You can change any property except for the name
 #     # (use `rename_function` instead) and `language`.
 #     #
-#     #   change_procedure "metadata.set_foo(a int)" do |p|
-#     #     p.body <<~SQL
-#     #       SET foo = a
-#     #     SQL
-#     #     p.security :invoker
-#     #     p.comment "Multiplies 2 integers"
+#     # ```ruby
+#     # change_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.body <<~SQL
+#     #     SET foo = a
 #     #   SQL
+#     #   p.security :invoker
+#     #   p.comment "Multiplies 2 integers"
+#     # SQL
+#     # ```
 #     #
 #     # The example above is not invertible because of uncertainty
 #     # about the previous state of body and comment.
 #     # To define them, use a from options (available in a block syntax only):
 #     #
-#     #   change_procedure "metadata.set_foo(a int)" do |p|
-#     #     p.body <<~SQL, from: <<~SQL
-#     #       SET foo = a
-#     #     SQL
-#     #       SET foo = -a
-#     #     SQL
-#     #     p.comment <<~MSG, from: <<~MSG
-#     #       Multiplies 2 integers
-#     #     MSG
-#     #       Multiplies ints
-#     #     MSG
-#     #     p.security :invoker
+#     # ```ruby
+#     # change_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.body <<~SQL, from: <<~SQL
+#     #     SET foo = a
 #     #   SQL
+#     #     SET foo = -a
+#     #   SQL
+#     #   p.comment <<~MSG, from: <<~MSG
+#     #     Multiplies 2 integers
+#     #   MSG
+#     #     Multiplies ints
+#     #   MSG
+#     #   p.security :invoker
+#     # SQL
+#     # ```
 #     #
 #     # Like in the other operations, the procedure can be
 #     # identified by a qualified name (with types of arguments).

data/lib/pg_trunk/operations/procedures/create_procedure.rb

@@ -23,37 +23,45 @@
 #     #
 #     # The procedure can be created either using inline syntax
 #     #
-#     #   create_procedure "metadata.set_foo(a int)",
-#     #                    language: :sql,
-#     #                    body: "SET foo = a",
-#     #                    comment: "Sets foo value"
+#     # ```ruby
+#     # create_procedure "metadata.set_foo(a int)",
+#     #                  language: :sql,
+#     #                  body: "SET foo = a",
+#     #                  comment: "Sets foo value"
+#     # ```
 #     #
 #     # or using a block:
 #     #
-#     #   create_procedure "metadata.set_foo(a int)" do |p|
-#     #     p.language "sql" # (default)
-#     #     p.body <<~SQL
-#     #       SET foo = a
-#     #     SQL
-#     #     p.security :invoker # (default), also :definer
-#     #     p.comment "Multiplies 2 integers"
+#     # ```ruby
+#     # create_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.language "sql" # (default)
+#     #   p.body <<~SQL
+#     #     SET foo = a
 #     #   SQL
+#     #   p.security :invoker # (default), also :definer
+#     #   p.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_procedure "set_foo(a int)",
-#     #                    body: "SET foo = a",
-#     #                    replace_existing: true
+#     # ```ruby
+#     # create_procedure "set_foo(a int)",
+#     #                  body: "SET foo = a",
+#     #                  replace_existing: true
+#     # ```
 #     #
 #     # A procedure without arguments is supported as well
 #     #
-#     #   # the same as "do_something()"
-#     #   create_procedure "do_something" do |p|
-#     #     # ...
-#     #   end
+#     # ```ruby
+#     # # the same as "do_something()"
+#     # create_procedure "do_something" do |p|
+#     #   # ...
+#     # end
+#     # ```
 #     def create_procedure(name, **options, &block); end
 #   end
 module PGTrunk::Operations::Procedures

data/lib/pg_trunk/operations/procedures/drop_procedure.rb

@@ -18,31 +18,39 @@
 #     #
 #     # A procedure can be dropped by a plain name:
 #     #
-#     #   drop_procedure "set_foo"
+#     # ```ruby
+#     # drop_procedure "set_foo"
+#     # ```
 #     #
 #     # If several overloaded procedures have the name,
 #     # then you must specify the signature having
 #     # types of attributes at least:
 #     #
-#     #   drop_procedure "set_foo(int)"
+#     # ```ruby
+#     # drop_procedure "set_foo(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_procedure "metadata.set_foo(a int)" do |p|
-#     #     p.language "sql" # (default)
-#     #     p.body <<~SQL
-#     #       SET foo = a
-#     #     SQL
-#     #     p.security :invoker # (default), also :definer
-#     #     p.comment "Multiplies 2 integers"
+#     # ```ruby
+#     # drop_procedure "metadata.set_foo(a int)" do |p|
+#     #   p.language "sql" # (default)
+#     #   p.body <<~SQL
+#     #     SET foo = a
 #     #   SQL
+#     #   p.security :invoker # (default), also :definer
+#     #   p.comment "Multiplies 2 integers"
+#     # SQL
+#     # ```
 #     #
 #     # The operation can be called with `if_exists` option. In this case
 #     # it would do nothing when no procedure existed.
 #     #
-#     #   drop_procedure "metadata.set_foo(a int)", if_exists: true
+#     # ```ruby
+#     # drop_procedure "metadata.set_foo(a int)", if_exists: true
+#     # ```
 #     #
 #     # Notice, that this option make the operation irreversible because of
 #     # uncertainty about the previous state of the database.

data/lib/pg_trunk/operations/procedures/rename_procedure.rb

@@ -13,11 +13,15 @@
 #     #
 #     # If there are no overloaded procedures, then you can use a plain name:
 #     #
-#     #   rename_procedure "math.set_foo", to: "public.foo_setup"
+#     # ```ruby
+#     # rename_procedure "math.set_foo", to: "public.foo_setup"
+#     # ```
 #     #
 #     # otherwise the types of attributes must be explicitly specified.
 #     #
-#     #   rename_procedure "math.set_foo(int)", to: "public.foo_setup"
+#     # ```ruby
+#     # rename_procedure "math.set_foo(int)", to: "public.foo_setup"
+#     # ```
 #     #
 #     # Any specification of attributes in `to:` option
 #     # is ignored because they cannot be changed anyway.

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

@@ -19,40 +19,48 @@
 #     #
 #     # The statistics can be created with explicit name:
 #     #
-#     #   create_statistics "users_stats" do |s|
-#     #     s.table "users"
-#     #     s.columns "family", "name"
-#     #     s.kinds :dependencies, :mcv, :ndistinct
-#     #     s.comment "Statistics for users' names and families"
-#     #   SQL
+#     # ```ruby
+#     # create_statistics "users_stats" do |s|
+#     #   s.table "users"
+#     #   s.columns "family", "name"
+#     #   s.kinds :dependencies, :mcv, :ndistinct
+#     #   s.comment "Statistics for users' names and families"
+#     # SQL
+#     # ```
 #     #
 #     # The name can be generated as well:
 #     #
-#     #   create_statistics do |s|
-#     #     s.table "users"
-#     #     s.columns "family", "name"
-#     #     s.kinds :dependencies, :mcv, :ndistinct
-#     #     s.comment "Statistics for users' names and families"
-#     #   SQL
+#     # ```ruby
+#     # create_statistics do |s|
+#     #   s.table "users"
+#     #   s.columns "family", "name"
+#     #   s.kinds :dependencies, :mcv, :ndistinct
+#     #   s.comment "Statistics for users' names and families"
+#     # SQL
+#     # ```
 #     #
 #     # Since v14 PostgreSQL have supported expressions in addition to columns:
 #     #
-#     #   create_statistics "users_stats" do |s|
-#     #     s.table "users"
-#     #     s.columns "family"
-#     #     s.expression "length(name)"
-#     #     s.kinds :dependencies, :mcv, :ndistinct
-#     #     s.comment "Statistics for users' name lengths and families"
-#     #   SQL
+#     # ```ruby
+#     # create_statistics "users_stats" do |s|
+#     #   s.table "users"
+#     #   s.columns "family"
+#     #   s.expression "length(name)"
+#     #   s.kinds :dependencies, :mcv, :ndistinct
+#     #   s.comment "Statistics for users' name lengths and families"
+#     # SQL
+#     # ```
 #     #
 #     # as well as statistics for the sole expression (kinds must be blank)
 #     # by columns of some table.
 #     #
-#     #   create_statistics "users_stats" do |s|
-#     #     s.table "users"
-#     #     s.expression "length(name || ' ' || family)"
-#     #     s.comment "Statistics for full name lengths"
-#     #   SQL
+#     # ```ruby
+#     # create_statistics "users_stats" do |s|
+#     #   s.table "users"
+#     #   s.expression "length(name || ' ' || family)"
+#     #   s.comment "Statistics for full name lengths"
+#     # SQL
+#     # ```
 #     #
 #     # Use `if_not_exists: true` to suppress error in case the statistics
 #     # has already been created. This option, though, makes the migration

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

@@ -19,38 +19,46 @@
 #     #
 #     # A statistics can be dropped by its name only:
 #     #
-#     #   drop_statistics "my_stats"
+#     # ```ruby
+#     # 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"
+#     # ```ruby
+#     # 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
+#     #   s.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"
+#     # ```ruby
+#     # drop_statistics do |s|
+#     #   s.table "users"
+#     #   s.columns "firstname", "name"
+#     #   s.expression <<~SQL
+#     #     round(age, 10)
 #     #   SQL
+#     #   s.kinds :dependency, :mcv, :ndistinct
+#     #   s.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
+#     # ```ruby
+#     # drop_statistics "unknown_statistics", if_exists: true
+#     # ```
 #     #
 #     # Notice, that this option make the operation irreversible because of
 #     # uncertainty about the previous state of the database.

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

@@ -11,7 +11,9 @@
 #     # 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"
+#     # ```ruby
+#     # rename_statistics "math.my_stat", to: "public.my_stats"
+#     # ```
 #     #
 #     # The operation is always reversible.
 #     def rename_statistics(name, to:); end

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

@@ -13,13 +13,15 @@
 #     #
 #     # 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
+#     # ```ruby
+#     # 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

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

@@ -25,34 +25,40 @@
 #     #
 #     # 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"
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     #  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.

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

@@ -25,18 +25,22 @@
 #     #
 #     # A trigger can be dropped by a table and name:
 #     #
-#     #   drop_trigger "users", "do_something"
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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.
@@ -44,7 +48,9 @@
 #     # 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
+#     # ```ruby
+#     # 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.

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

@@ -12,20 +12,24 @@
 #     #
 #     # 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
+#     # ```ruby
+#     # 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
+#     # ```ruby
+#     # 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.
@@ -36,10 +40,12 @@
 #     # 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
+#     # ```ruby
+#     # 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
 module PGTrunk::Operations::Views

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

@@ -18,14 +18,18 @@
 #     #
 #     # The operation creates the view using its `sql_definition`:
 #     #
-#     #   create_view("views.admin_users", sql_definition: <<~SQL)
-#     #     SELECT id, name FROM users WHERE admin;
-#     #   SQL
+#     # ```ruby
+#     # create_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_view "admin_users", version: 1
+#     # ```ruby
+#     # create_view "admin_users", version: 1
+#     # ```
 #     #
 #     # It is expected, that a `db/views/admin_users_v01.sql`
 #     # to contain the SQL snippet.
@@ -33,17 +37,21 @@
 #     # You can also set a comment describing the view, and the check option
 #     # (either `:local` or `:cascaded`):
 #     #
-#     #   create_view "admin_users" do |v|
-#     #     v.sql_definition "SELECT id, name FROM users WHERE admin;"
-#     #     v.check :local
-#     #     v.comment "Admin users only"
-#     #   end
+#     # ```ruby
+#     # create_view "admin_users" do |v|
+#     #   v.sql_definition "SELECT id, name FROM users WHERE admin;"
+#     #   v.check :local
+#     #   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_view "admin_users", version: 1, replace_existing: true
+#     # ```ruby
+#     # create_view "admin_users", version: 1, replace_existing: true
+#     # ```
 #     #
 #     # This option makes an operation irreversible due to uncertainty
 #     # of the previous state of the database.

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

@@ -21,30 +21,40 @@
 #     # The operation drops the existing view identified by its
 #     # qualified name (it can include a schema).
 #     #
-#     #   drop_view "views.admin_users"
+#     # ```ruby
+#     # drop_view "views.admin_users"
+#     # ```
 #     #
 #     # To make the operation invertible, use the same options
 #     # as in the `create_view` operation.
 #     #
-#     #   drop_view "views.admin_users" do |v|
-#     #     v.sql_definition "SELECT name, email FROM users WHERE admin;"
-#     #     v.check :local
-#     #     v.comment "Admin users only"
-#     #   end
+#     # ```ruby
+#     # drop_view "views.admin_users" do |v|
+#     #   v.sql_definition "SELECT name, email FROM users WHERE admin;"
+#     #   v.check :local
+#     #   v.comment "Admin users only"
+#     # end
+#     # ```
 #     #
 #     # You can also use a version-base SQL definition like:
 #     #
-#     #    drop_view "views.admin_users", revert_to_version: 1
+#     # ```ruby
+#     # drop_view "views.admin_users", revert_to_version: 1
+#     # ```
 #     #
 #     # With the `force: :cascade` option the operation would remove
 #     # all the objects which depend on the view.
 #     #
-#     #   drop_view "views.admin_users", force: :cascade
+#     # ```ruby
+#     # drop_view "views.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_view "views.admin_users", if_exists: true
+#     # ```ruby
+#     # drop_view "views.admin_users", if_exists: true
+#     # ```
 #     #
 #     # Both options make an operation irreversible due to uncertainty
 #     # of the previous state of the database.