Class: ActiveRecord::Migration

Inherits:

Object

Object
ActiveRecord::Migration

show all

Defined in:: lib/pg_trunk/operations/materialized_views/refresh_materialized_view.rb,
lib/pg_trunk/operations/materialized_views/rename_materialized_view.rb,
lib/pg_trunk/operations/materialized_views/create_materialized_view.rb,
lib/pg_trunk/operations/materialized_views/change_materialized_view.rb,
lib/pg_trunk/operations/check_constraints/validate_check_constraint.rb,
lib/pg_trunk/operations/materialized_views/drop_materialized_view.rb,
lib/pg_trunk/operations/check_constraints/rename_check_constraint.rb,
lib/pg_trunk/operations/check_constraints/drop_check_constraint.rb,
lib/pg_trunk/operations/check_constraints/add_check_constraint.rb,
lib/pg_trunk/operations/composite_types/rename_composite_type.rb,
lib/pg_trunk/operations/composite_types/create_composite_type.rb,
lib/pg_trunk/operations/composite_types/change_composite_type.rb,
lib/pg_trunk/operations/composite_types/drop_composite_type.rb,
lib/pg_trunk/operations/foreign_keys/rename_foreign_key.rb,
lib/pg_trunk/operations/foreign_keys/drop_foreign_key.rb,
lib/pg_trunk/operations/statistics/rename_statistics.rb,
lib/pg_trunk/operations/statistics/create_statistics.rb,
lib/pg_trunk/operations/foreign_keys/add_foreign_key.rb,
lib/pg_trunk/operations/procedures/rename_procedure.rb,
lib/pg_trunk/operations/procedures/create_procedure.rb,
lib/pg_trunk/operations/procedures/change_procedure.rb,
lib/pg_trunk/operations/statistics/drop_statistics.rb,
lib/pg_trunk/operations/sequences/rename_sequence.rb,
lib/pg_trunk/operations/sequences/create_sequence.rb,
lib/pg_trunk/operations/sequences/change_sequence.rb,
lib/pg_trunk/operations/procedures/drop_procedure.rb,
lib/pg_trunk/operations/functions/rename_function.rb,
lib/pg_trunk/operations/functions/create_function.rb,
lib/pg_trunk/operations/functions/change_function.rb,
lib/pg_trunk/operations/triggers/rename_trigger.rb,
lib/pg_trunk/operations/triggers/create_trigger.rb,
lib/pg_trunk/operations/triggers/change_trigger.rb,
lib/pg_trunk/operations/sequences/drop_sequence.rb,
lib/pg_trunk/operations/functions/drop_function.rb,
lib/pg_trunk/operations/triggers/drop_trigger.rb,
lib/pg_trunk/operations/domains/rename_domain.rb,
lib/pg_trunk/operations/domains/create_domain.rb,
lib/pg_trunk/operations/domains/change_domain.rb,
lib/pg_trunk/operations/domains/drop_domain.rb,
lib/pg_trunk/operations/views/rename_view.rb,
lib/pg_trunk/operations/views/create_view.rb,
lib/pg_trunk/operations/views/change_view.rb,
lib/pg_trunk/operations/rules/rename_rule.rb,
lib/pg_trunk/operations/rules/create_rule.rb,
lib/pg_trunk/operations/enums/rename_enum.rb,
lib/pg_trunk/operations/enums/create_enum.rb,
lib/pg_trunk/operations/enums/change_enum.rb,
lib/pg_trunk/operations/views/drop_view.rb,
lib/pg_trunk/operations/rules/drop_rule.rb,
lib/pg_trunk/operations/enums/drop_enum.rb

Instance Method Summary collapse

#add_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void
Add a check constraint to the table.
#add_foreign_key(table, reference, **options) {|k| ... } ⇒ void
Create a foreign key constraint.
#change_composite_type(name, **options) {|t| ... } ⇒ void
Modify a composite type.
#change_domain(name) {|d| ... } ⇒ void
Modify a domain type.
#change_enum(name) {|e| ... } ⇒ void
Modify an enumerated type.
#change_function(name, **options) {|f| ... } ⇒ void
Modify a function.
#change_materialized_view(name, **options) {|v| ... } ⇒ void
Modify a materialized view.
#change_procedure(name, **options) {|p| ... } ⇒ void
Modify a procedure.
#change_sequence(name, **options) {|s| ... } ⇒ void
Modify a sequence.
#change_view(name, **options) {|v| ... } ⇒ void
Modify a view.
#create_composite_type(name, **options) {|t| ... } ⇒ void
Create a composite type.
#create_domain(name, **options) {|d| ... } ⇒ void
Create a domain type.
#create_enum(name, **options) {|e| ... } ⇒ void
Create an enumerated type by qualified name.
#create_function(name, **options) {|f| ... } ⇒ void
Create a function.
#create_materialized_view(name, **options) {|v| ... } ⇒ void
Create a materialized view.
#create_procedure(name, **options) {|p| ... } ⇒ void
Create a procedure.
#create_rule(table, name = nil, **options) {|r| ... } ⇒ void
Create a rule.
#create_sequence(name, **options) {|s| ... } ⇒ void
Create a sequence.
#create_statistics(name, **options) {|s| ... } ⇒ void
Create a custom statistics.
#create_trigger(table, name = nil, **options) {|t| ... } ⇒ void
Create a trigger for a table.
#create_view(name, **options) {|v| ... } ⇒ void
Create a view.
#drop_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void
Remove a check constraint from the table.
#drop_composite_type(name, **options) {|t| ... } ⇒ void
Drop a composite type.
#drop_domain(name, **options) {|d| ... } ⇒ void
Drop a domain type by qualified name.
#drop_enum(name, **options) {|e| ... } ⇒ void
Drop an enumerated type by qualified name.
#drop_foreign_key(table, reference, **options) {|k| ... } ⇒ void
Drops a foreign key constraint.
#drop_function(name, **options) {|f| ... } ⇒ void
Drop a function.
#drop_materialized_view(name, **options) {|v| ... } ⇒ void
Drop a materialized view.
#drop_procedure(name, **options) {|p| ... } ⇒ void
Drop a procedure.
#drop_rule(table, name = nil, **options) {|r| ... } ⇒ void
Drop a rule.
#drop_sequence(name, **options) {|s| ... } ⇒ void
Drop a sequence.
#drop_statistics(name, **options) {|s| ... } ⇒ void
Drop a custom statistics.
#drop_trigger(table, name = nil, **options) {|t| ... } ⇒ void
Drop a trigger for a table.
#drop_view(name, **options) {|v| ... } ⇒ void
Drop a view.
#refresh_materialized_view(name, **options) ⇒ void
Refresh a materialized view.
#rename_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void
Rename a check constraint.
#rename_composite_type(name, to:) ⇒ void
Change the name and/or schema of a composite type.
#rename_domain(name, to:) ⇒ void
Change the name and/or schema of a domain type.
#rename_enum(name, to:) ⇒ void
Change the name and/or schema of an enumerated type.
#rename_foreign_key(table, reference, **options) {|k| ... } ⇒ void
Rename a foreign key.
#rename_function(name, to:) ⇒ void
Change the name and/or schema of a function.
#rename_materialized_view(name, **options) ⇒ void
Change the name and/or schema of a materialized view.
#rename_procedure(name, to:) ⇒ void
Change the name and/or schema of a procedure.
#rename_rule(table, name = nil, **options) {|c| ... } ⇒ void
Rename a rule.
#rename_sequence(name, **options, &block) ⇒ void
Rename a sequence.
#rename_statistics(name, to:) ⇒ void
Change the name and/or schema of a statistics.
#rename_trigger(table, name = nil, **options) {|t| ... } ⇒ void
Rename a trigger.
#rename_view(name, **options) ⇒ void
Change the name and/or schema of a view.
#validate_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void
Validate an invalid check constraint.

Instance Method Details

#add_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

This method returns an undefined value.

Add a check constraint to the table

The name of the new constraint can be set explicitly

add_check_constraint :users, "length(phone) > 10",
                     name: "phone_is_long_enough",
                     inherit: false,
                     comment: "Phone is 10+ chars long"

The name can also be skipped (it will be generated by default):

add_check_constraint :users, "length(phone) > 1"

The block syntax can be used for any argument as usual:

add_check_constraint do |c|
  c.table "users"
  c.expression "length(phone) > 10"
  c.name "phone_is_long_enough"
  c.inherit false
  c.comment "Phone is 10+ chars long"
end

The operation is always reversible.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
expression (#to_s) (defaults to: nil) —
(nil) The SQL expression
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The optional name of the constraint
:inherit (Boolean) — default: true —
If the constraint should be inherited by subtables
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(c) —
the block with the constraint's definition

Yield Parameters:

Object —
receiver of methods specifying the constraint

41	# File 'lib/pg_trunk/operations/check_constraints/add_check_constraint.rb', line 41 def add_check_constraint(table, expression = nil, **options, &block); end

#add_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

This method returns an undefined value.

Create a foreign key constraint

The table and reference of the new key must be set explicitly. All the rest (including the name) can be generated by default:

# same as `..., column: 'role_id', primary_key: 'id'`
add_foreign_key :users, :roles

The block syntax can be used for any argument:

add_foreign_key do |k|
  k.table "users"
  k.reference "roles"
  k.column "role_id" # (generated by default from reference and pk)
  k.primary_key "id" # (default)
  k.on_update :cascade # :restrict (default)
  k.on_delete :cascade # :restrict (default)
  k.name "user_roles_fk" # can be generated
  k.comment "Phone is 10+ chars long"
end

Composite foreign keys are supported as well:

add_foreign_key "users", "roles" do |k|
  k.columns %w[role_name role_id]
  k.primary_key %w[name id] # Requires unique index
  k.match :full # :partial, :simple (default)
end

The operation is always invertible.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
reference (#to_s) —
(nil) The qualified name of the reference table
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The current name of the foreign key
:to (#to_s) — default: nil —
The new name for the foreign key
:columns (Array<#to_s>) — default: [] —
The list of columns of the table
:column (#to_s) — default: nil —
An alias for :columns for the case of single-column keys
:primary_key (Array<#to_s>) — default: [] —
The list of columns of the reference table
:match (Symbol) — default: :full —
Define how to match rows Supported values: :full (default), :partial, :simple
:on_delete (Symbol) — default: :restrict —
Define how to handle the deletion of the referred row. Supported values: :restrict (default), :cascade, :nullify, :reset
:on_update (Symbol) — default: :restrict —
Define how to handle the update of the referred row. Supported values: :restrict (default), :cascade, :nullify, :reset

Yields:

(k) —
the block with the key's definition

Yield Parameters:

Object —
receiver of methods specifying the foreign key

57	# File 'lib/pg_trunk/operations/foreign_keys/add_foreign_key.rb', line 57 def add_foreign_key(table, reference, **options, &block); end

#change_composite_type(name, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Modify a composite type

The operation can be used to add, drop, rename or change columns. The comment can be changed as well.

Providing a type "paint.colored_point":

create_composite_type "paint.colored_point" do |t|
  t.column "color", "text", collation: "en_US"
  t.column "x", "integer"
  t.column "z", "integer"
end

After the following change:

change_composite_type "paint.colored_point" do |t|
  t.change_column "color", "text", collation: "ru_RU", from_collation: "en_US"
  t.change_column "x", "bigint", from_type: "integer"
  t.drop_column "z", "integer"
  t.add_column "Y", "bigint"
  t.rename_column "x", to: "X"
  t.comment "2D point with a color", from: "2D point"
end

The definition became:

create_composite_type "paint.colored_point" do |t|
  t.column "color", "text", collation: "ru_RU"
  t.column "X", "bigint"
  t.column "Y", "integer"
end

Notice, that all renames will be done AFTER other changes, so in change_column you should use the old names.

In several cases the operation is not invertible:

when a column was dropped
when force: :cascade option is used (to update objects that use the type)
when if_exists: true is added to the drop_column clause
when a previous state of the column type, collation or comment is not specified.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(t) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

58	# File 'lib/pg_trunk/operations/composite_types/change_composite_type.rb', line 58 def change_composite_type(name, **options, &block); end

#change_domain(name) {|d| ... } ⇒ `void`

This method returns an undefined value.

Modify a domain type

The operation can be used to add or remove constraints, modify the default_sql value, or the description of the domain type. Neither the underlying type nor the collation can be changed.

change_domain "dict.us_postal_code" do |d|
  d.null true # from: false
  # check is added for inversion
  d.drop_constraint "postal_code_length", check: <<~SQL
    length(VALUE) > 3 AND length(VALUE) < 6
  SQL
  d.add_constraint <<~SQL, name: "postal_code_valid"
    VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
  SQL
  d.default_sql "'00000'::text", from: "'0000'::text"
  d.comment <<~COMMENT, from: <<~COMMENT
    Currencies
  COMMENT
end

Use blank string (not a nil value) to reset either a default_sql, or the comment. nil-s here will be ignored.

When dropping a constraint you can use a check expression. In the same manner, use from option with comment or default_sql to make the operation invertible.

It is irreversible in case any drop_constraint clause has if_exists: true or force: :cascade option -- due to uncertainty of the previous state of the database:

change_domain "dict.us_postal_code", force: :cascade do |d|
  d.drop_constraint "postal_code_valid" # missed `:check` option
  d.drop_constraint "postal_code_length"
  d.drop_constraint "postal_code_format", if_exists: true
  d.default_sql "'0000'::text" # missed `:from` option
  d.comment "New comment" # missed `:from` option
end

Parameters:

name (#to_s) —
(nil) The qualified name of the type

Yields:

(d) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

52	# File 'lib/pg_trunk/operations/domains/change_domain.rb', line 52 def change_domain(name, &block); end

#change_enum(name) {|e| ... } ⇒ `void`

This method returns an undefined value.

Modify an enumerated type

The operation can be used to rename or add values to the enumerated type. The commend can be changed as well.

change_enum "currencies" do |e|
  e.add_value "EUR", after: "BTC"
  e.add_value "GBP", before: "usd"
  e.add_value "JPY" # to the end of the list
  e.rename_value "usd", to: "USD"
  e.comment <<~COMMENT, from: <<~COMMENT
    Currencies
  COMMENT
end

Please, keep in mind that all values will be added before the first rename. That's why you should use old values (like the usd instead of the USD in the example above) in before and after options.

Also notice that PostgreSQL doesn't support value deletion, that's why adding any value makes the migration irreversible.

It is also irreversible if you changed the comment, but not defined its previous value.

Parameters:

name (#to_s) —
(nil) The qualified name of the type

Yields:

(e) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

36	# File 'lib/pg_trunk/operations/enums/change_enum.rb', line 36 def change_enum(name, &block); end

#change_function(name, **options) {|f| ... } ⇒ `void`

This method returns an undefined value.

Modify a function

The operation changes the function without dropping it (which can be necessary when there are other objects using the function and you don't want to change them all).

You can change any property except for the name (use rename_function instead) and language.

change_function "math.mult(int, int)" do |f|
  f.volatility :immutable, from: :stable
  f.parallel :safe, from: :restricted
  f.security :invoker
  f.leakproof true
  f.strict true
  f.cost 5.0
  # f.rows 1 (supported for functions returning sets of rows)
SQL

The example above is not invertible because of uncertainty about the previous volatility, parallelism, and cost. To define them, use a from options (available in a block syntax only):

change_function "math.mult(a int, b int)" do |f|
  f.body <<~SQL, from: <<~SQL
    SELECT a * b;
  SQL
    SELECT min(a * b, 1);
  SQL
  f.volatility :immutable, from: :volatile
  f.parallel :safe, from: :unsafe
  f.leakproof true
  f.strict true
  f.cost 5.0, from: 100.0
SQL

Like in the other operations, the function can be identified by a qualified name (with types of arguments). If it has no overloaded implementations, the plain name is supported as well.

Parameters:

name (#to_s) —
(nil) The qualified name of the function
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the function is absent

Yields:

(f) —
the block with the function's definition

Yield Parameters:

Object —
receiver of methods specifying the function

51	# File 'lib/pg_trunk/operations/functions/change_function.rb', line 51 def change_function(name, **options, &block); end

#change_materialized_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Modify a materialized 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
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.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the view is absent

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

64	# File 'lib/pg_trunk/operations/materialized_views/change_materialized_view.rb', line 64 def change_materialized_view(name, **options, &block); end

#change_procedure(name, **options) {|p| ... } ⇒ `void`

This method returns an undefined value.

Modify a procedure

The operation changes the procedure without dropping it (which is useful when there are other objects using the function and you don't want to change them all).

You can change any property except for the name (use rename_function instead) and language.

change_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
SQL

Like in the other operations, the procedure can be identified by a qualified name (with types of arguments). If it has no overloaded implementations, the plain name is supported as well.

Parameters:

name (#to_s) —
(nil) The qualified name of the procedure
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the procedure is absent

Yields:

(p) —
the block with the procedure's definition

Yield Parameters:

Object —
receiver of methods specifying the procedure

51	# File 'lib/pg_trunk/operations/procedures/change_procedure.rb', line 51 def change_procedure(name, **options, &block); end

#change_sequence(name, **options) {|s| ... } ⇒ `void`

This method returns an undefined value.

Modify a sequence

The operation enables to alter a sequence without recreating it. PostgreSQL allows any setting to be modified. The comment can be changed as well.

change_sequence "my_schema.global_id" do |s|
  s.owned_by "", "", from: %w[users gid]
  s.type "smallint", from: "integer"
  s.iterate_by 1, from: 2
  s.min_value 1, from: 0
  s.max_value 2000, from: 1999
  s.start_with 2, from: 1
  s.cache 1, from: 10
  s.cycle false
  s.comment "Identifier", from: "Global identifier"
end

As in the snippet above, to make the change invertible, you have to define from option for every changed attribute, except for the boolean cycle.

With the if_exists: true option, the operation won't raise when the sequence is absent.

change_sequence "my_schema.global_id", if_exists: true do |s|
  s.type "smallint"
  s.iterate_by 1
  s.min_value 1
  s.max_value 2000
  s.start_with 2
  s.cache 1
  s.cycle false
  s.comment "Identifier"
end

This option makes a migration irreversible due to uncertainty of the previous state of the database. That's why in the last example no from: option was added (they are useless).

Parameters:

name (#to_s) —
(nil) The qualified name of the sequence.
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the sequence is absent.

Yields:

(s) —
the block with the sequence's definition.

Yield Parameters:

Object —
receiver of methods specifying the sequence.

51	# File 'lib/pg_trunk/operations/sequences/change_sequence.rb', line 51 def change_sequence(name, **options, &block); end

#change_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Modify a 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
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

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the view is absent

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

46	# File 'lib/pg_trunk/operations/views/change_view.rb', line 46 def change_view(name, **options, &block); end

#create_composite_type(name, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Create a composite type

create_composite_type "paint.colored_point" do |d|
  d.column "x", "integer"
  d.column "y", "integer"
  d.column "color", "text", collation: "en_US"
  d.comment <<~COMMENT
    2D point with color
  COMMENT
end

It is always reversible.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(t) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

22	# File 'lib/pg_trunk/operations/composite_types/create_composite_type.rb', line 22 def create_composite_type(name, **options, &block); end

#create_domain(name, **options) {|d| ... } ⇒ `void`

This method returns an undefined value.

Create a domain type

create_domain "dict.us_postal_code", as: "text" do |d|
  d.collation "en_US"
  d.default_sql "'0000'::text"
  d.null false
  d.constraint <<~SQL, name: "code_valid"
    VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
  SQL
  d.comment "US postal code"
end

It is always reversible.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:as (#to_s) — default: nil —
The base type for the domain (alias: :type)
:collation (#to_s) — default: nil —
The collation
:null (Boolean) — default: true —
If a value of this type can be NULL
:default_sql (#to_s) — default: nil —
The snippet for the default value of the domain
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(d) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

27	# File 'lib/pg_trunk/operations/domains/create_domain.rb', line 27 def create_domain(name, **options, &block); end

#create_enum(name, **options) {|e| ... } ⇒ `void`

This method returns an undefined value.

Create an enumerated type by qualified name

create_enum "finances.currency" do |e|
  e.values "BTC", "EUR", "GBP", "USD"
  e.value "JPY" # the alternative way to add a value to the tail
  e.comment <<~COMMENT
    The list of values for supported currencies.
  COMMENT
end

It is always reversible.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:values (Array<#to_s>) — default: [] —
The list of values
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(e) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

22	# File 'lib/pg_trunk/operations/enums/create_enum.rb', line 22 def create_enum(name, **options, &block); end

#create_function(name, **options) {|f| ... } ⇒ `void`

This method returns an undefined value.

Create a function

The function can be created either using inline syntax

create_function "math.mult(a int, b int) int",
                language: :sql,
                body: "SELECT a * b",
                volatility: :immutable,
                leakproof: true,
                comment: "Multiplies 2 integers"

or using a block:

create_function "math.mult(a int, b int) int" do |f|
  f.language "sql" # (default)
  f.body <<~SQL
    SELECT a * b;
  SQL
  f.volatility :immutable # :stable, :volatile (default)
  f.parallel :safe        # :restricted, :unsafe (default)
  f.security :invoker     # (default), also :definer
  f.leakproof true
  f.strict true
  f.cost 5.0
  # f.rows 1 (supported for functions returning sets of rows)
  f.comment "Multiplies 2 integers"
SQL

With a replace_existing: true option, it will be created using the CREATE OR REPLACE clause. In this case the migration is irreversible because we don't know if and how to restore its previous definition.

create_function "math.mult(a int, b int) int",
                body: "SELECT a * b",
                replace_existing: true

We presume a function without arguments should have no arguments and return void like

# the same as "do_something() void"
create_function "do_something" do |f|
  # ...
end

Parameters:

name (#to_s) —
(nil) The qualified name of the function with arguments and returned value type
options (Hash) —
a customizable set of options

Options Hash (**options):

:replace_existing (Boolean) — default: false —
If the function should overwrite an existing one
:language (#to_s) — default: "sql" —
The language (like "sql" or "plpgsql")
:body (#to_s) — default: nil —
The body of the function
:volatility (Symbol) — default: :volatile —
The volatility of the function. Supported values: :volatile (default), :stable, :immutable
:parallel (Symbol) — default: :unsafe —
The safety of parallel execution. Supported values: :unsafe (default), :restricted, :safe
:security (Symbol) — default: :invoker —
Define the role under which the function is invoked Supported values: :invoker (default), :definer
:leakproof (Boolean) — default: false —
If the function is leakproof
:strict (Boolean) — default: false —
If the function is strict
:cost (Float) — default: nil —
The cost estimation for the function
:rows (Integer) — default: nil —
The number of rows returned by a function
:comment (#to_s) —
The description of the function

Yields:

(f) —
the block with the function's definition

Yield Parameters:

Object —
receiver of methods specifying the function

74	# File 'lib/pg_trunk/operations/functions/create_function.rb', line 74 def create_function(name, **options, &block); end

#create_materialized_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Create a materialized 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
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.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_not_exists (Boolean) — default: false —
Suppress the error when a view has been already created
:sql_definition (#to_s) — default: nil —
The snippet containing the query
:version (#to_i) — default: nil —
The alternative way to set sql_definition by referencing to a file containing the snippet
:tablespace (#to_s) — default: nil —
The tablespace for the view
:with_data (Boolean) — default: true —
If the view should be populated after creation
:comment (#to_s) — default: nil —
The comment describing the view

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

81	# File 'lib/pg_trunk/operations/materialized_views/create_materialized_view.rb', line 81 def create_materialized_view(name, **options, &block); end

#create_procedure(name, **options) {|p| ... } ⇒ `void`

This method returns an undefined value.

Create a procedure

The syntax of the operation is the same as for create_function, but with only security option available. Notice, that procedures cannot return values so you're expected not to define a returned value as well.

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"

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"
SQL

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

Parameters:

name (#to_s) —
(nil) The qualified name of the procedure with arguments and returned value type
options (Hash) —
a customizable set of options

Options Hash (**options):

:replace_existing (Boolean) — default: false —
If the procedure should overwrite an existing one
:language (#to_s) — default: "sql" —
The language (like "sql" or "plpgsql")
:body (#to_s) — default: nil —
The body of the procedure
:security (Symbol) — default: :invoker —
Define the role under which the procedure is invoked Supported values: :invoker (default), :definer
:comment (#to_s) —
The description of the procedure

Yields:

(p) —
the block with the procedure's definition

Yield Parameters:

Object —
receiver of methods specifying the procedure

62	# File 'lib/pg_trunk/operations/procedures/create_procedure.rb', line 62 def create_procedure(name, **options, &block); end

#create_rule(table, name = nil, **options) {|r| ... } ⇒ `void`

This method returns an undefined value.

Create a rule

To create a rule you must define table, and event (operation) for the rule. Usually you also supposed to define a command, but in case the kind is set to :instead, missing the command would provide INSTEAD DO NOTHING rule.

create_rule "users" do |r|
  r.event :insert
  r.kind :instead
  r.comment "Forbid insertion to the table"
SQL

By default the kind is set to :also, in this case the command is needed as well:

create_rule "users", "_count_insertion" do |r|
  r.event :insert
  r.command <<~SQL
    UPDATE counters SET user_inserts = user_inserts + 1
  SQL
  r.comment "Count insertion to the table"
SQL

With a when option you can also specify a condition:

create_rule "users", "_forbid_grants" do |r|
  r.event :update
  r.kind :instead
  r.where "NOT old.admin AND new.admin"
  r.comment "Forbid granting admin rights"
SQL

With a replace_existing: true option, the rule 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 the previous definition.

create_rule "users", "_forbid_insertion", replace_existing: true do |r|
  r.event :insert
  r.kind :instead
  r.comment "Forbid insertion to the table"
SQL

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The name of the rule (unique within the table)
options (Hash) —
a customizable set of options

Options Hash (**options):

:replace_existing (Boolean) — default: false —
If the rule should overwrite an existing one
:event (Symbol) — default: nil —
The type of the query the rule is applied to. Supported values: :update, :insert, :delete
:kind (Symbol) — default: :also —
The kind of the rule (either :also or :instead). In case of instead the original query wouldn't be executed, only the command is.
:where (String) — default: nil —
The condition (SQL) for the rule to be applied.
:command (String) — default: nil —
The SQL command to be added by the rule.

Yields:

(r) —
the block with the rule's definition

Yield Parameters:

Object —
receiver of methods specifying the rule

66	# File 'lib/pg_trunk/operations/rules/create_rule.rb', line 66 def create_rule(table, name = nil, **options, &block); end

#create_sequence(name, **options) {|s| ... } ⇒ `void`

This method returns an undefined value.

Create a sequence

The sequence can be created by its qualified name only

create_sequence "my_schema.global_id"

we also support all PostgreSQL settings for the sequence:

create_sequence "my_schema.global_id", as: "integer" do |s|
  s.iterate_by 2
  s.min_value 0
  s.max_value 1999
  s.start_with 1
  s.cache 10
  s.cycle true
  s.comment "Global identifier"
end

Using a block method s.owned_by you can bind the sequence to some table's column. This means the sequence is dependent from the column and will be dropped along with it. Notice that the name of the table is NOT qualified because the table MUST belong to the same schema as the sequence itself.

create_table "users" do |t|
  t.bigint :gid
end

create_sequence "my_schema.global_id" do |s|
  s.owned_by "users", "gid"
end

With the if_not_exists: true option the operation wouldn't raise an exception in case the sequence has been already created.

create_sequence "my_schema.global_id", if_not_exists: true

This option makes the migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the sequence
options (Hash) —
a customizable set of options

Options Hash (**options):

:as (#to_s) — default: "bigint" —
The type of the sequence's value Supported values: "bigint" (or "int8", default), "integer" (or "int4"), "smallint" ("int2").
:if_not_exists (Boolean) — default: false —
Suppress the error when the sequence already existed.
:increment_by (Integer) — default: 1 —
Non-zero step of the sequence (either positive or negative).
:min_value (Integer) — default: nil —
Minimum value of the sequence.
:max_value (Integer) — default: nil —
Maximum value of the sequence.
:start_with (Integer) — default: nil —
The first value of the sequence.
:cache (Integer) — default: 1 —
The number of values to be generated and cached.
:cycle (Boolean) — default: false —
If the sequence should be reset to start after its value reaches min/max value.
:comment (#to_s) — default: nil —
The comment describing the sequence.

Yields:

(s) —
the block with the sequence's definition

Yield Parameters:

Object —
receiver of methods specifying the sequence

66	# File 'lib/pg_trunk/operations/sequences/create_sequence.rb', line 66 def create_sequence(name, **options, &block); end

#create_statistics(name, **options) {|s| ... } ⇒ `void`

This method returns an undefined value.

Create a custom statistics

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

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

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

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

Use if_not_exists: true to suppress error in case the statistics has already been created. This option, though, makes the migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the statistics
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_not_exists (Boolean) — default: false —
Suppress the error when the statistics is already exist
table (#to_s) — default: nil —
The qualified name of the table whose statistics will be collected
kinds (Array<Symbol>) — default: [:dependencies, :mcv, :ndistinct] —
The kinds of statistics to be collected (all by default). Supported values in the array: :dependencies, :mcv, :ndistinct
:comment (#to_s) —
The description of the statistics

Yields:

(s) —
the block with the statistics' definition

Yield Parameters:

Object —
receiver of methods specifying the statistics

65	# File 'lib/pg_trunk/operations/statistics/create_statistics.rb', line 65 def create_statistics(name, **options, &block); end

#create_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Create a trigger for a table

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

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The name of the trigger
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the trigger is absent

Yields:

(t) —
the block with the trigger's definition

Yield Parameters:

Object —
receiver of methods specifying the trigger

62	# File 'lib/pg_trunk/operations/triggers/create_trigger.rb', line 62 def create_trigger(table, name = nil, **options, &block); end

#create_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Create a view

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

For compatibility to the scenic gem, we also support adding a definition via its version:

create_view "admin_users", version: 1

It is expected, that a db/views/admin_users_v01.sql to contain the SQL snippet.

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

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

This option makes an operation irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:replace_existing (Boolean) — default: false —
If the view should overwrite an existing one
:sql_definition (#to_s) — default: nil —
The snippet containing the query
:version (#to_i) — default: nil —
The alternative way to set sql_definition by referencing to a file containing the snippet
:check (#to_s) — default: nil —
Controls the behavior of automatically updatable views Supported values: :local, :cascaded
:comment (#to_s) — default: nil —
The comment describing the view

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

55	# File 'lib/pg_trunk/operations/views/create_view.rb', line 55 def create_view(name, **options, &block); end

#drop_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

This method returns an undefined value.

Remove a check constraint from the table

Definition for the drop_check_constraint operation

The constraint can be identified by the table and explicit name

drop_check_constraint :users, name: "phone_is_long_enough"

Alternatively the name can be got from the expression. Be careful! the expression must have exactly the same form as stored in the database:

drop_check_constraint :users, "length((phone::text) > 10)"

To made operation reversible the expression must be provided:

drop_check_constraint "users" do |c|
  c.expression "length((phone::text) > 10)"
  c.inherit false
  c.comment "The phone is 10+ chars long"
end

The operation can be called with if_exists option.

drop_check_constraint :users,
                      name: "phone_is_long_enough",
                      if_exists: true

In this case the operation is always irreversible due to uncertainty of the previous state of the database.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
expression (#to_s) (defaults to: nil) —
(nil) The SQL expression
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the constraint is absent
:name (#to_s) — default: nil —
The optional name of the constraint
:inherit (Boolean) — default: true —
If the constraint should be inherited by subtables
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(c) —
the block with the constraint's definition

Yield Parameters:

Object —
receiver of methods specifying the constraint

50	# File 'lib/pg_trunk/operations/check_constraints/drop_check_constraint.rb', line 50 def drop_check_constraint(table, expression = nil, **options, &block); end

#drop_composite_type(name, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Drop a composite type

The operation drops a composite_type type identified by its qualified name (it can include a schema).

For inversion use the same options as in the create_composite_type operation.

drop_composite_type "paint.colored_point" do |d|
  d.column "x", "integer"
  d.column "y", "integer"
  d.column "color", "text", collation: "en_US"
  d.comment <<~COMMENT
    2D point with color
  COMMENT
end

Notice, that the composite type creation can use no attributes. That's why dropping it is always reversible; though the reversion provides a type without columns:

drop_composite_type "paint.colored_point"

With the force: :cascade option the operation removes all objects using the type.

drop_composite_type "paint.colored_point", force: :cascade

With the if_exists: true option the operation won't fail even when the view was absent.

drop_composite_type "paint.colored_point", if_exists: true

Both options make a migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the type is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(t) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

47	# File 'lib/pg_trunk/operations/composite_types/drop_composite_type.rb', line 47 def drop_composite_type(name, **options, &block); end

#drop_domain(name, **options) {|d| ... } ⇒ `void`

This method returns an undefined value.

Drop a domain type by qualified name

drop_domain "dict.us_postal_code"

To make the operation invertible, use the same options as in the create_domain operation.

drop_domain "dict.us_postal_code", as: "string" do |d|
  d.constraint <<~SQL, name: "code_valid"
    VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
  SQL
  d.comment <<~COMMENT
    US postal code
  COMMENT
end

With the force: :cascade option the operation would remove all the objects that use the type.

drop_domain "dict.us_postal_code", force: :cascade

With the if_exists: true option the operation won't fail even when the view was absent in the database.

drop_domain "dict.us_postal_code", if_exists: true

Both options make a migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the type is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:as (#to_s) — default: nil —
The base type for the domain (alias: :type)
:collation (#to_s) — default: nil —
The collation
:default_sql (#to_s) — default: nil —
The snippet for the default value of the domain
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(d) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

49	# File 'lib/pg_trunk/operations/domains/drop_domain.rb', line 49 def drop_domain(name, **options, &block); end

#drop_enum(name, **options) {|e| ... } ⇒ `void`

This method returns an undefined value.

Drop an enumerated type by qualified name

The operation drops a enumerated type identified by its qualified name (it can include a schema).

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

With the force: :cascade option the operation would remove all the objects that use the type.

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

Both options make a migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the type is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:values (Array<#to_s>) — default: [] —
The list of values
:comment (#to_s) — default: nil —
The comment describing the constraint

Yields:

(e) —
the block with the type's definition

Yield Parameters:

Object —
receiver of methods specifying the type

49	# File 'lib/pg_trunk/operations/enums/drop_enum.rb', line 49 def drop_enum(name, **options, &block); end

#drop_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

This method returns an undefined value.

Drops a foreign key constraint

The key can be identified by table/name (not invertible):

drop_foreign_key "users", name: "user_roles_fk"

To make it invertible use the same options like in the add_foreign_key operation.

drop_foreign_key do |k|
  k.table "users"
  k.reference "roles"
  k.column "role_id"
  k.primary_key "id"
  k.on_update :cascade
  k.on_delete :cascade
  k.comment "Phone is 10+ chars long"
end

Notice that the name can be skipped, in this case we would find it in the database.

The operation can be called with if_exists option.

drop_foreign_key "users", name: "user_roles_fk", if_exists: true

In this case the operation is always irreversible due to uncertainty of the previous state of the database.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
reference (#to_s) —
(nil) The qualified name of the reference table
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The current name of the foreign key
:if_exists (Boolean) — default: false —
Suppress the error when the constraint is absent
:to (#to_s) — default: nil —
The new name for the foreign key
:columns (Array<#to_s>) — default: [] —
The list of columns of the table
:column (#to_s) — default: nil —
An alias for :columns for the case of single-column keys
:primary_key (Array<#to_s>) — default: [] —
The list of columns of the reference table
:match (Symbol) — default: :full —
Define how to match rows Supported values: :full (default), :partial, :simple
:on_delete (Symbol) — default: :restrict —
Define how to handle the deletion of the referred row. Supported values: :restrict (default), :cascade, :nullify, :reset
:on_update (Symbol) — default: :restrict —
Define how to handle the update of the referred row. Supported values: :restrict (default), :cascade, :nullify, :reset

Yields:

(k) —
the block with the key's definition

Yield Parameters:

Object —
receiver of methods specifying the foreign key

56	# File 'lib/pg_trunk/operations/foreign_keys/drop_foreign_key.rb', line 56 def drop_foreign_key(table, reference, **options, &block); end

#drop_function(name, **options) {|f| ... } ⇒ `void`

This method returns an undefined value.

Drop a 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"
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.

Parameters:

name (#to_s) —
(nil) The qualified name of the function with arguments and returned value type
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the function is absent
:force (Symbol) — default: :restrict —
How to process dependent objects Supported values: :restrict (default), :cascade
:language (#to_s) — default: "sql" —
The language (like "sql" or "plpgsql")
:body (#to_s) — default: nil —
The body of the function
:volatility (Symbol) — default: :volatile —
The volatility of the function. Supported values: :volatile (default), :stable, :immutable
:parallel (Symbol) — default: :unsafe —
The safety of parallel execution. Supported values: :unsafe (default), :restricted, :safe
:security (Symbol) — default: :invoker —
Define the role under which the function is invoked Supported values: :invoker (default), :definer
:leakproof (Boolean) — default: false —
If the function is leakproof
:strict (Boolean) — default: false —
If the function is strict
:cost (Float) — default: nil —
The cost estimation for the function
:rows (Integer) — default: nil —
The number of rows returned by a function
:comment (#to_s) —
The description of the function

Yields:

(f) —
the block with the function's definition

Yield Parameters:

Object —
receiver of methods specifying the function

77	# File 'lib/pg_trunk/operations/functions/drop_function.rb', line 77 def drop_function(name, **options, &block); end

#drop_materialized_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Drop a materialized 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"
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.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the view is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:sql_definition (#to_s) — default: nil —
The snippet containing the query
:revert_to_version (#to_i) — default: nil —
The alternative way to set sql_definition by referencing to a file containing the snippet
:tablespace (#to_s) — default: nil —
The tablespace for the view
:with_data (Boolean) — default: true —
If the view should be populated after creation
:comment (#to_s) — default: nil —
The comment describing the view

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

58	# File 'lib/pg_trunk/operations/materialized_views/drop_materialized_view.rb', line 58 def drop_materialized_view(name, **options, &block); end

#drop_procedure(name, **options) {|p| ... } ⇒ `void`

This method returns an undefined value.

Drop a procedure

A procedure can be dropped by a plain name:

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)"

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"
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

Notice, that this option make the operation irreversible because of uncertainty about the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the procedure with arguments and returned value type
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the procedure is absent
:language (#to_s) — default: "sql" —
The language (like "sql" or "plpgsql")
:body (#to_s) — default: nil —
The body of the procedure
:security (Symbol) — default: :invoker —
Define the role under which the procedure is invoked Supported values: :invoker (default), :definer
:comment (#to_s) —
The description of the procedure

Yields:

(p) —
the block with the procedure's definition

Yield Parameters:

Object —
receiver of methods specifying the procedure

54	# File 'lib/pg_trunk/operations/procedures/drop_procedure.rb', line 54 def drop_procedure(name, **options, &block); end

#drop_rule(table, name = nil, **options) {|r| ... } ⇒ `void`

This method returns an undefined value.

Drop a rule

The rule can be identified by the table and explicit name

drop_rule :users, "_forbid_insertion"

Alternatively the name can be got from kind and event.

drop_rule :users do |r|
  r.event :insert
  r.kind :instead
  r.comment "Forbid insertion to the table"
end

To made operation reversible all the necessary parameters must be provided like in the create_rule operation:

drop_rule "users", "_count_insertion" do |r|
  r.event :insert
  r.command <<~SQL
    UPDATE counters SET user_inserts = user_inserts + 1
  SQL
  r.comment "Count insertion to the table"
SQL

The operation can be called with if_exists option.

drop_rule :users, if_exists: true do |r|
  # event and kind here are used to define a name
  r.event :insert
  r.kind :instead
end

With the force: :cascade option the operation would remove all the objects that use the rule.

drop_rule :users, force: :cascade do |r|
  r.event :insert
  r.kind :instead
end

In both cases the operation becomes irreversible due to uncertainty of the previous state of the database.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The name of the rule (unique within the table)
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the rule is absent.
:force (Symbol) — default: :restrict —
Define how to process dependent objects Supported values: :restrict (default), :cascade (for cascade deletion)
:event (Symbol) — default: nil —
The type of the query the rule is applied to. Supported values: :update, :insert, :delete
:kind (Symbol) — default: :also —
The kind of the rule (either :also or :instead). In case of instead the original query wouldn't be executed, only the command is.
:where (String) — default: nil —
The condition (SQL) for the rule to be applied.
:command (String) — default: nil —
The SQL command to be added by the rule.

Yields:

(r) —
the block with the rule's definition

Yield Parameters:

Object —
receiver of methods specifying the rule

70	# File 'lib/pg_trunk/operations/rules/drop_rule.rb', line 70 def drop_rule(table, name = nil, **options, &block); end

#drop_sequence(name, **options) {|s| ... } ⇒ `void`

This method returns an undefined value.

Drop a sequence

The sequence can be dropped by its qualified name only

drop_sequence "global_number"

For inversion provide options for the create_sequence operation as well:

drop_sequence "global_id", as: "int2" do |s|
  s.iterate_by 2
  s.min_value 0
  s.max_value 1999
  s.start_with 1
  s.cache 10
  s.cycle true
  s.comment "Global identifier"
end

The operation can be called with if_exists option to suppress the exception in case when the sequence is absent:

drop_sequence "global_number", if_exists: true

With the force: :cascade option the operation would remove all the objects that use the sequence.

drop_sequence "global_number", force: :cascade

In both cases the operation becomes irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the sequence
options (Hash) —
a customizable set of options

Options Hash (**options):

:as (#to_s) — default: "bigint" —
The type of the sequence's value Supported values: "bigint" (or "int8", default), "integer" (or "int4"), "smallint" ("int2").
:if_exists (Boolean) — default: false —
Suppress the error when the sequence is absent.
:force (Symbol) — default: :restrict —
Define how to process dependent objects Supported values: :restrict (default), :cascade.
:increment_by (Integer) — default: 1 —
Non-zero step of the sequence (either positive or negative).
:min_value (Integer) — default: nil —
Minimum value of the sequence.
:max_value (Integer) — default: nil —
Maximum value of the sequence.
:start_with (Integer) — default: nil —
The first value of the sequence.
:cache (Integer) — default: 1 —
The number of values to be generated and cached.
:cycle (Boolean) — default: false —
If the sequence should be reset to start after its value reaches min/max value.
:comment (#to_s) — default: nil —
The comment describing the sequence.

Yields:

(s) —
the block with the sequence's definition

Yield Parameters:

Object —
receiver of methods specifying the sequence

58	# File 'lib/pg_trunk/operations/sequences/drop_sequence.rb', line 58 def drop_sequence(name, **options, &block); end

#drop_statistics(name, **options) {|s| ... } ⇒ `void`

This method returns an undefined value.

Drop a custom 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
  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
  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_statistics "unknown_statistics", if_exists: true

Notice, that this option make the operation irreversible because of uncertainty about the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the statistics
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the statistics is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
table (#to_s) — default: nil —
The qualified name of the table whose statistics will be collected
kinds (Array<Symbol>) — default: [:dependencies, :mcv, :ndistinct] —
The kinds of statistics to be collected (all by default). Supported values in the array: :dependencies, :mcv, :ndistinct
:comment (#to_s) —
The description of the statistics

Yields:

(s) —
the block with the statistics' definition

Yield Parameters:

Object —
receiver of methods specifying the statistics

62	# File 'lib/pg_trunk/operations/statistics/drop_statistics.rb', line 62 def drop_statistics(name, **options, &block); end

#drop_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Drop a trigger for a table

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.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The name of the trigger
options (Hash) —
a customizable set of options

Options Hash (**options):

:if_exists (Boolean) — default: false —
Suppress the error when the trigger is absent
:function (#to_s) — default: nil —
The qualified name of the function to be called
:type (Symbol) — default: nil —
When the trigger should be run Supported values: :before, :after, :instead_of
:events (Array<Symbol>) —
List of events running the trigger Supported values in the array: :insert, :update, :delete, :truncate
:constraint (Boolean) — default: false —
If the trigger is a constraint
:initially (Symbol) — default: :immediate —
If the constraint check should be deferred Supported values: :immediate (default), :deferred
:when (#to_s) — default: nil —
The SQL snippet definiing a condition for the trigger
:for_each (Symbol) — default: :statement —
Define if a trigger should be run for every row Supported values: :statement (default), :row
:comment (#to_s) — default: nil —
The commend describing the trigger

Yields:

(t) —
the block with the trigger's definition

Yield Parameters:

Object —
receiver of methods specifying the trigger

54	# File 'lib/pg_trunk/operations/triggers/drop_trigger.rb', line 54 def drop_trigger(table, name = nil, **options, &block); end

#drop_view(name, **options) {|v| ... } ⇒ `void`

This method returns an undefined value.

Drop a view

The operation drops the existing view identified by its qualified name (it can include a schema).

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

You can also use a version-base SQL definition like:

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

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

Both options make an operation irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:replace_existing (Boolean) — default: false —
If the view should overwrite an existing one
:if_exists (Boolean) — default: false —
Suppress the error when the view is absent
:force (Symbol) — default: :restrict —
How to process dependent objects (:cascade or :restrict)
:sql_definition (#to_s) — default: nil —
The snippet containing the query
:revert_to_version (#to_i) — default: nil —
The alternative way to set sql_definition by referencing to a file containing the snippet
:check (#to_s) — default: nil —
Controls the behavior of automatically updatable views Supported values: :local, :cascaded
:comment (#to_s) — default: nil —
The comment describing the view

Yields:

(v) —
the block with the view's definition

Yield Parameters:

Object —
receiver of methods specifying the view

58	# File 'lib/pg_trunk/operations/views/drop_view.rb', line 58 def drop_view(name, **options, &block); end

#refresh_materialized_view(name, **options) ⇒ `void`

This method returns an undefined value.

Refresh a materialized view

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.

Parameters:

name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:with_data (Boolean) — default: true —
If the view should be populated after creation
:algorithm (Symbol) — default: nil —
Makes the operation concurrent when set to :concurrently

27	# File 'lib/pg_trunk/operations/materialized_views/refresh_materialized_view.rb', line 27 def refresh_materialized_view(name, **options); end

#rename_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

This method returns an undefined value.

Rename a check constraint

A constraint can be identified by the table and explicit name

rename_check_constraint :users,
                        name: "phone_is_long_enough",
                        to: "phones.long_enough"

Alternatively the name can be got from the expression. Be careful! the expression must have exactly the same form as stored in the database:

rename_check_constraint :users, "length((phone::text) > 10)",
                        to: "long_enough"

The name can be reset to auto-generated when the :to option is missed or blank:

rename_check_constraint :users, "phone_is_long_enough"

The operation is always reversible.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
expression (#to_s) (defaults to: nil) —
(nil) The SQL expression
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The current name of the constraint
:to (#to_s) — default: nil —
The new name for the constraint

Yields:

(c) —
the block with the constraint's definition

Yield Parameters:

Object —
receiver of methods specifying the constraint

37	# File 'lib/pg_trunk/operations/check_constraints/rename_check_constraint.rb', line 37 def rename_check_constraint(table, expression = nil, **options, &block); end

#rename_composite_type(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a composite type

rename_composite_type "point", to: "paint.colored_point"

The operation is always reversible.

Parameters:

name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

13	# File 'lib/pg_trunk/operations/composite_types/rename_composite_type.rb', line 13 def rename_composite_type(name, to:); end

#rename_domain(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a domain type

A domain type can be both renamed and moved to another schema.

rename_domain "us_code", to: "dict.us_postal_code"

The operation is always reversible.

Parameters:

:name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

15	# File 'lib/pg_trunk/operations/domains/rename_domain.rb', line 15 def rename_domain(name, to:); end

#rename_enum(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of an enumerated type

@example:

rename_enum "currencies", to: "finances.currency"

The operation is always reversible.

Parameters:

:name (#to_s) —
(nil) The qualified name of the type
options (Hash) —
a customizable set of options

15	# File 'lib/pg_trunk/operations/enums/rename_enum.rb', line 15 def rename_enum(name, to:); end

#rename_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

This method returns an undefined value.

Rename a foreign key

You can rename the foreign key constraint identified by its explicit name:

rename_foreign_key :users,
                   name: "user_roles_fk",
                   to: "constraints.users_by_roles_fk"

The key can also be found in the database by table/reference/columns/pk

rename_foreign_key :users, :roles, primary_key: "name", to: "user_roles"

If a new name is missed, then the name will be reset to the auto-generated one:

rename_foreign_key :users, "user_roles_fk"

The operation is always reversible.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
reference (#to_s) —
(nil) The qualified name of the reference table
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The current name of the foreign key
:to (#to_s) — default: nil —
The new name for the foreign key
:columns (Array<#to_s>) — default: [] —
The list of columns of the table
:column (#to_s) — default: nil —
An alias for :columns for the case of single-column keys
:primary_key (Array<#to_s>) — default: [] —
The list of columns of the reference table

Yields:

(k) —
the block with the key's definition

Yield Parameters:

Object —
receiver of methods specifying the foreign key

36	# File 'lib/pg_trunk/operations/foreign_keys/rename_foreign_key.rb', line 36 def rename_foreign_key(table, reference, **options, &block); end

#rename_function(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a 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.

Parameters:

:name (#to_s) —
(nil) The qualified name of the function
options (Hash) —
a customizable set of options

27	# File 'lib/pg_trunk/operations/functions/rename_function.rb', line 27 def rename_function(name, to:); end

#rename_materialized_view(name, **options) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a materialized view

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"

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

At the same time, the option makes a migration irreversible due to uncertainty of the previous state of the database.

Parameters:

:name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:to (#to_s) — default: nil —
The new qualified name for the view
:if_exists (Boolean) — default: false —
Suppress the error when the view is absent

27	# File 'lib/pg_trunk/operations/materialized_views/rename_materialized_view.rb', line 27 def rename_materialized_view(name, **options); end

#rename_procedure(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a procedure

A procedure can be renamed by changing both the name and the schema (namespace) it belongs to.

If there are no overloaded procedures, then you can use a plain name:

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"

Any specification of attributes in to: option is ignored because they cannot be changed anyway.

The operation is always reversible.

Parameters:

:name (#to_s) —
(nil) The qualified name of the procedure
options (Hash) —
a customizable set of options

27	# File 'lib/pg_trunk/operations/procedures/rename_procedure.rb', line 27 def rename_procedure(name, to:); end

#rename_rule(table, name = nil, **options) {|c| ... } ⇒ `void`

This method returns an undefined value.

Rename a rule

A rule can be identified by the table and explicit name

rename_rule :users, "_forbid_insertion", to: "_skip_insertion"

Alternatively the name can be got from the event and kind.

rename_rule :users, to: "_skip_insertion" do |r|
  r.event :insert
  r.kind :instead
end

The name can be reset to auto-generated when the :to option is missed or blank:

rename_rule :users, "_skip_insertion" do |r|
  r.event :insert
  r.kind :instead
end

The operation is always reversible.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The current name of the rule
options (Hash) —
a customizable set of options

Options Hash (**options):

:to (#to_s) — default: nil —
The new name for the rule

Yields:

(c) —
the block with the constraint's definition

Yield Parameters:

Object —
receiver of methods specifying the constraint

37	# File 'lib/pg_trunk/operations/rules/rename_rule.rb', line 37 def rename_rule(table, name = nil, **options, &block); end

#rename_sequence(name, **options, &block) ⇒ `void`

This method returns an undefined value.

Rename a sequence

The operation allows to change both name and schema

rename_sequence "global_num", to: "sequences.global_number"

With the if_exists: true option the operation wouldn't raise an exception in case the sequence hasn't been created yet.

create_sequence "my_schema.global_id", if_exists: true

This option makes the migration irreversible due to uncertainty of the previous state of the database.

Parameters:

name (#to_s) —
(nil) The current qualified name of the sequence
options (Hash) —
a customizable set of options

Options Hash (**options):

:to (#to_s) — default: nil —
The new qualified name for the sequence
:if_exists (Boolean) — default: false —
Suppress the error when the sequence is absent.

24	# File 'lib/pg_trunk/operations/sequences/rename_sequence.rb', line 24 def rename_sequence(name, **options, &block); end

#rename_statistics(name, to:) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a 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.

Parameters:

:name (#to_s) —
(nil) The qualified name of the statistics
options (Hash) —
a customizable set of options

16	# File 'lib/pg_trunk/operations/statistics/rename_statistics.rb', line 16 def rename_statistics(name, to:); end

#rename_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

This method returns an undefined value.

Rename a 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] 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

Parameters:

table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The name of the trigger
table (#to_s) —
(nil) The qualified name of the table
name (#to_s) (defaults to: nil) —
(nil) The current name of the trigger
options (Hash) —
a customizable set of options

Options Hash (**options):

:to (#to_s) — default: nil —
The new name of the trigger
:to (#to_s) — default: nil —
The new name for the trigger
:function (#to_s) — default: nil —
The qualified name of the function to be called
:type (Symbol) — default: nil —
When the trigger should be run Supported values: :before, :after, :instead_of
:events (Array<Symbol>) —
List of events running the trigger Supported values in the array: :insert, :update, :delete, :truncate
:for_each (Symbol) — default: :statement —
Define if a trigger should be run for every row Supported values: :statement (default), :row

Yields:

(t) —
the block with the trigger's definition

Yield Parameters:

Object —
receiver of methods specifying the trigger

50	# File 'lib/pg_trunk/operations/triggers/rename_trigger.rb', line 50 def rename_trigger(table, name = nil, **options, &block); end

#rename_view(name, **options) ⇒ `void`

This method returns an undefined value.

Change the name and/or schema of a view

A view can be renamed by changing both the name and the schema (namespace) it belongs to.

rename_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_view "views.admin_users", to: "admins", if_exists: true

At the same time, the option makes a view irreversible due to uncertainty of the previous state of the database.

Parameters:

:name (#to_s) —
(nil) The qualified name of the view
options (Hash) —
a customizable set of options

Options Hash (**options):

:to (#to_s) — default: nil —
The new qualified name for the view
:if_exists (Boolean) — default: false —
Suppress the error when the view is absent

25	# File 'lib/pg_trunk/operations/views/rename_view.rb', line 25 def rename_view(name, **options); end

#validate_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

This method returns an undefined value.

Validate an invalid check constraint

The invalid constraint can be identified by table and explicit name:

validate_check_constraint :users, name: "phone_is_long_enough"

Alternatively it can be specified by expression. In this case you must ensure the expression has the same form as it is stored in the database (after parsing the source).

validate_check_constraint :users, "length((phone::text) > 10)"

Notice that it is invertible but the inverted operation does nothing.

Parameters:

table (#to_s) —
(nil) The qualified name of the table
expression (#to_s) (defaults to: nil) —
(nil) The SQL expression
options (Hash) —
a customizable set of options

Options Hash (**options):

:name (#to_s) — default: nil —
The optional name of the constraint

Yields:

(c) —
the block with the constraint's definition

Yield Parameters:

Object —
receiver of methods specifying the constraint

26	# File 'lib/pg_trunk/operations/check_constraints/validate_check_constraint.rb', line 26 def validate_check_constraint(table, expression = nil, **options, &block); end

Class: ActiveRecord::Migration

Instance Method Summary collapse

Instance Method Details

#add_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void

#add_foreign_key(table, reference, **options) {|k| ... } ⇒ void

#change_composite_type(name, **options) {|t| ... } ⇒ void

#change_domain(name) {|d| ... } ⇒ void

#change_enum(name) {|e| ... } ⇒ void

#change_function(name, **options) {|f| ... } ⇒ void

#change_materialized_view(name, **options) {|v| ... } ⇒ void

#change_procedure(name, **options) {|p| ... } ⇒ void

#change_sequence(name, **options) {|s| ... } ⇒ void

#change_view(name, **options) {|v| ... } ⇒ void

#create_composite_type(name, **options) {|t| ... } ⇒ void

#create_domain(name, **options) {|d| ... } ⇒ void

#create_enum(name, **options) {|e| ... } ⇒ void

#create_function(name, **options) {|f| ... } ⇒ void

#create_materialized_view(name, **options) {|v| ... } ⇒ void

#create_procedure(name, **options) {|p| ... } ⇒ void

#create_rule(table, name = nil, **options) {|r| ... } ⇒ void

#create_sequence(name, **options) {|s| ... } ⇒ void

#create_statistics(name, **options) {|s| ... } ⇒ void

#create_trigger(table, name = nil, **options) {|t| ... } ⇒ void

#create_view(name, **options) {|v| ... } ⇒ void

#drop_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void

#drop_composite_type(name, **options) {|t| ... } ⇒ void

#drop_domain(name, **options) {|d| ... } ⇒ void

#drop_enum(name, **options) {|e| ... } ⇒ void

#drop_foreign_key(table, reference, **options) {|k| ... } ⇒ void

#drop_function(name, **options) {|f| ... } ⇒ void

#drop_materialized_view(name, **options) {|v| ... } ⇒ void

#drop_procedure(name, **options) {|p| ... } ⇒ void

#drop_rule(table, name = nil, **options) {|r| ... } ⇒ void

#drop_sequence(name, **options) {|s| ... } ⇒ void

#drop_statistics(name, **options) {|s| ... } ⇒ void

#drop_trigger(table, name = nil, **options) {|t| ... } ⇒ void

#drop_view(name, **options) {|v| ... } ⇒ void

#refresh_materialized_view(name, **options) ⇒ void

#rename_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void

#rename_composite_type(name, to:) ⇒ void

#rename_domain(name, to:) ⇒ void

#rename_enum(name, to:) ⇒ void

#rename_foreign_key(table, reference, **options) {|k| ... } ⇒ void

#rename_function(name, to:) ⇒ void

#rename_materialized_view(name, **options) ⇒ void

#rename_procedure(name, to:) ⇒ void

#rename_rule(table, name = nil, **options) {|c| ... } ⇒ void

#rename_sequence(name, **options, &block) ⇒ void

#rename_statistics(name, to:) ⇒ void

#rename_trigger(table, name = nil, **options) {|t| ... } ⇒ void

#rename_view(name, **options) ⇒ void

#validate_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ void

#add_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

#add_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

#change_composite_type(name, **options) {|t| ... } ⇒ `void`

#change_domain(name) {|d| ... } ⇒ `void`

#change_enum(name) {|e| ... } ⇒ `void`

#change_function(name, **options) {|f| ... } ⇒ `void`

#change_materialized_view(name, **options) {|v| ... } ⇒ `void`

#change_procedure(name, **options) {|p| ... } ⇒ `void`

#change_sequence(name, **options) {|s| ... } ⇒ `void`

#change_view(name, **options) {|v| ... } ⇒ `void`

#create_composite_type(name, **options) {|t| ... } ⇒ `void`

#create_domain(name, **options) {|d| ... } ⇒ `void`

#create_enum(name, **options) {|e| ... } ⇒ `void`

#create_function(name, **options) {|f| ... } ⇒ `void`

#create_materialized_view(name, **options) {|v| ... } ⇒ `void`

#create_procedure(name, **options) {|p| ... } ⇒ `void`

#create_rule(table, name = nil, **options) {|r| ... } ⇒ `void`

#create_sequence(name, **options) {|s| ... } ⇒ `void`

#create_statistics(name, **options) {|s| ... } ⇒ `void`

#create_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

#create_view(name, **options) {|v| ... } ⇒ `void`

#drop_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

#drop_composite_type(name, **options) {|t| ... } ⇒ `void`

#drop_domain(name, **options) {|d| ... } ⇒ `void`

#drop_enum(name, **options) {|e| ... } ⇒ `void`

#drop_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

#drop_function(name, **options) {|f| ... } ⇒ `void`

#drop_materialized_view(name, **options) {|v| ... } ⇒ `void`

#drop_procedure(name, **options) {|p| ... } ⇒ `void`

#drop_rule(table, name = nil, **options) {|r| ... } ⇒ `void`

#drop_sequence(name, **options) {|s| ... } ⇒ `void`

#drop_statistics(name, **options) {|s| ... } ⇒ `void`

#drop_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

#drop_view(name, **options) {|v| ... } ⇒ `void`

#refresh_materialized_view(name, **options) ⇒ `void`

#rename_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`

#rename_composite_type(name, to:) ⇒ `void`

#rename_domain(name, to:) ⇒ `void`

#rename_enum(name, to:) ⇒ `void`

#rename_foreign_key(table, reference, **options) {|k| ... } ⇒ `void`

#rename_function(name, to:) ⇒ `void`

#rename_materialized_view(name, **options) ⇒ `void`

#rename_procedure(name, to:) ⇒ `void`

#rename_rule(table, name = nil, **options) {|c| ... } ⇒ `void`

#rename_sequence(name, **options, &block) ⇒ `void`

#rename_statistics(name, to:) ⇒ `void`

#rename_trigger(table, name = nil, **options) {|t| ... } ⇒ `void`

#rename_view(name, **options) ⇒ `void`

#validate_check_constraint(table, expression = nil, **options) {|c| ... } ⇒ `void`