Module: PostgreSQLAdapterExtensions::SequenceMethods

Defined in:
lib/postgresql_adapter_extensions/sequence_methods.rb

Overview

Note:

This module is designed for PostgreSQL databases and may not be compatible with other database systems.

This module provides methods for managing PostgreSQL sequences, including creating, altering, and dropping sequences with various customization options.

Author:

Since:

  • 1.0.0

Instance Method Summary collapse

Instance Method Details

#alter_sequence(name, options = {}) ⇒ void

Note:

Uses ‘ALTER SEQUENCE` SQL statement with PostgreSQL-specific options.

This method returns an undefined value.

Alters an existing PostgreSQL sequence with the given options.

Examples:

Modify the increment value of a sequence

alter_sequence(:order_id_seq, increment_by: 10)

Restart a sequence at a specific value

alter_sequence(:order_id_seq, restart_with: 2000)

Set a minimum and maximum value for a sequence

alter_sequence(:order_id_seq, minvalue: 500, maxvalue: 10000)

Make a sequence cycle when it reaches the maximum value

alter_sequence(:order_id_seq, cycle: true)

Remove the cycle behavior from a sequence

alter_sequence(:order_id_seq, cycle: false)

Change the owner of a sequence to a specific table column

alter_sequence(:order_id_seq, owned_by: "orders.id")

Parameters:

  • name (String, Symbol) —

    The name of the sequence to alter.

  • options (Hash) (defaults to: {}) —

    A hash of options to modify the sequence behavior.

Options Hash (options):

  • :if_exists (Boolean) —

    Includes IF EXISTS to avoid errors if the sequence does not exist.

  • :data_type (String, nil) —

    Sets the sequence’s data type (e.g., BIGINT, SMALLINT).

  • :increment_by (Integer) —

    Sets the increment step for the sequence.

  • :minvalue (Integer, nil) —

    Sets the minimum value for the sequence. Uses NO MINVALUE if nil.

  • :maxvalue (Integer, nil) —

    Sets the maximum value for the sequence. Uses NO MAXVALUE if nil.

  • :start (Integer) —

    Sets the starting value of the sequence.

  • :restart (Integer, nil) —

    Restarts the sequence. Uses RESTART if nil, RESTART WITH value if provided.

  • :cache (Integer) —

    Sets the number of sequence values to cache for performance.

  • :cycle (Boolean) —

    Enables (CYCLE) or disables (+NO CYCLE+) sequence cycling.

  • :owned_by (String, nil) —

    Associates the sequence with a table column. Uses OWNED BY NONE if nil.

Author:

Since:

  • 1.0.0



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/postgresql_adapter_extensions/sequence_methods.rb', line 117

def alter_sequence(name, options = {})
  sql = +"ALTER SEQUENCE"
  sql << " IF EXISTS" if options[:if_exists]
  sql << " #{quote_table_name(name)}"

  sql << " AS #{options[:data_type]}" if options[:data_type]
  sql << " INCREMENT BY #{options[:increment_by]}" if options[:increment_by]
  sql << (options[:minvalue] ? " MINVALUE #{options[:minvalue]}" : " NO MINVALUE")
  sql << (options[:maxvalue] ? " MAXVALUE #{options[:maxvalue]}" : " NO MAXVALUE")
  sql << " START WITH #{options[:start]}" if options[:start]
  sql << " RESTART" if options[:restart].nil? && options.key?(:restart)
  sql << " RESTART WITH #{options[:restart]}" if options[:restart]
  sql << " CACHE #{options[:cache]}" if options[:cache]
  sql << " #{options[:cycle] ? 'CYCLE' : 'NO CYCLE'}"
  sql << (options[:owned_by] ? " OWNED BY #{options[:owned_by]}" : " OWNED BY NONE")

  execute(sql).tap { reload_type_map }
end

#create_sequence(name, options = {}) ⇒ void

Note:

Uses ‘CREATE SEQUENCE` SQL statement with PostgreSQL-specific options.

This method returns an undefined value.

Creates a new sequence in the PostgreSQL database with customizable options.

Examples:

Create a sequence with default options

create_sequence(:order_id_seq)

Create a sequence starting from 1000 with an increment of 5

create_sequence(:order_id_seq, start: 1000, increment_by: 5)

Create a cyclic sequence with a maximum value of 5000

create_sequence(:order_id_seq, cycle: true, maxvalue: 5000)

Create a sequence owned by a specific table column

create_sequence(:order_id_seq, owned_by: "orders.id")

Parameters:

  • name (String, Symbol) —

    The name of the sequence to create.

  • options (Hash) (defaults to: {}) —

    Additional options to configure the sequence.

Options Hash (options):

  • :if_not_exists (Boolean) — default: false —

    Includes IF NOT EXISTS to avoid errors if the sequence exists.

  • :data_type (String, nil) — default: nil —

    Sets the sequence’s data type (e.g., BIGINT, SMALLINT).

  • :start (Integer) — default: 1 —

    The starting value of the sequence.

  • :increment_by (Integer) — default: 1 —

    The increment step for each sequence value.

  • :minvalue (Integer, nil) — default: 1 —

    The minimum value the sequence can generate. Uses NO MINVALUE if nil.

  • :maxvalue (Integer, nil) — default: nil —

    The maximum value the sequence can generate. Uses NO MAXVALUE if nil.

  • :cache (Integer) — default: 1 —

    The number of sequence values to cache for performance.

  • :cycle (Boolean) — default: false —

    Whether the sequence should cycle back to the start after reaching the max value.

  • :owned_by (String, nil) — default: nil —

    The table and column name that owns this sequence.

Author:

Since:

  • 1.0.0



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/postgresql_adapter_extensions/sequence_methods.rb', line 50

def create_sequence(name, options = {})
  options = options.reverse_merge(
    start: 1,
    increment_by: 1,
    minvalue: 1,
    cache: 1,
    cycle: false,
    if_not_exists: false
  )

  sql = +"CREATE SEQUENCE"
  sql << " IF NOT EXISTS" if options[:if_not_exists]
  sql << " #{quote_table_name(name)}"

  sql << " AS #{options[:data_type]}" if options[:data_type]
  sql << " INCREMENT BY #{options[:increment_by]}" if options[:increment_by]
  sql << (options[:minvalue] ? " MINVALUE #{options[:minvalue]}" : " NO MINVALUE")
  sql << (options[:maxvalue] ? " MAXVALUE #{options[:maxvalue]}" : " NO MAXVALUE")
  sql << " START WITH #{options[:start]}" if options[:start]
  sql << " CACHE #{options[:cache]}" if options[:cache]
  sql << " #{options[:cycle] ? 'CYCLE' : 'NO CYCLE'}"
  sql << " OWNED BY #{options[:owned_by]}" if options[:owned_by]

  execute(sql).tap { reload_type_map }
end

#drop_sequence(name, options = {}) ⇒ void

Note:

Uses ‘DROP SEQUENCE` SQL statement with PostgreSQL-specific options.

This method returns an undefined value.

Drops an existing sequence from the PostgreSQL database with optional conditions.

Examples:

Drop a sequence without additional options

drop_sequence(:order_id_seq)

Drop a sequence if it exists

drop_sequence(:order_id_seq, if_exists: true)

Drop a sequence and all dependent objects

drop_sequence(:order_id_seq, drop_behavior: :cascade)

Drop a sequence but prevent deletion if dependencies exist

drop_sequence(:order_id_seq, drop_behavior: :restrict)

Parameters:

  • name (String, Symbol) —

    The name of the sequence to drop.

  • options (Hash) (defaults to: {}) —

    Additional options to modify the behavior of the drop operation.

Options Hash (options):

  • :if_exists (Boolean) — default: false —

    Adds IF EXISTS to avoid errors if the sequence does not exist.

  • :drop_behavior (Symbol) — default: nil —

    Determines whether dependent objects are also dropped.

    • Accepts :cascade to drop dependent objects.

    • Accepts :restrict to prevent dropping if dependencies exist.

Author:

Since:

  • 1.0.0



165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/postgresql_adapter_extensions/sequence_methods.rb', line 165

def drop_sequence(name, options = {})
  options = options.reverse_merge(
    if_exists: false
  )

  sql = +"DROP SEQUENCE"
  sql << " IF EXISTS" if options[:if_exists]
  sql << " #{quote_table_name(name)}"

  sql << " #{options[:drop_behavior].to_s.upcase}" if options[:drop_behavior].in?([:cascade, :restrict])

  execute(sql).tap { reload_type_map }
end

#rename_sequence(name, options = {}) ⇒ void

Note:

Uses ‘ALTER SEQUENCE … RENAME TO` SQL statement in PostgreSQL.

This method returns an undefined value.

Renames an existing PostgreSQL sequence.

Examples:

Rename a sequence

rename_sequence(:order_id_seq, to: :new_order_id_seq)

Rename a sequence only if it exists

rename_sequence(:order_id_seq, to: :new_order_id_seq, if_exists: true)

Parameters:

  • name (String, Symbol) —

    The current name of the sequence.

  • options (Hash) (defaults to: {}) —

    A hash of options for renaming the sequence.

Options Hash (options):

  • :if_exists (Boolean) — default: false —

    Includes IF EXISTS to avoid errors if the sequence does not exist.

  • :to (String, Symbol) —

    The new name for the sequence.

Raises:

  • (ArgumentError) —

    If the :to option is not provided.

Author:

Since:

  • 1.2.0



202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/postgresql_adapter_extensions/sequence_methods.rb', line 202

def rename_sequence(name, options = {})
  to = options.fetch(:to) { raise ArgumentError, ":to is required" }

  options = options.reverse_merge(
    if_exists: false
  )

  sql = +"ALTER SEQUENCE"
  sql << " IF EXISTS" if options[:if_exists]
  sql << " #{quote_table_name(name)}"
  sql << " RENAME TO #{quote_table_name(to)}"

  execute(sql).tap { reload_type_map }
end