PostgreSQLAdapterExtensions

PostgreSQL Adapter Extensions for ActiveRecord.

postgresql_adapter_extensions is a Ruby gem that extends the ActiveRecord::ConnectionAdapters::PostgreSQLAdapter to add additional sequence-related methods for managing PostgreSQL sequences in a Rails application.

Harshal V. Ladhe, Master of Computer Science.

This gem provides easy-to-use methods to create, alter, and drop sequences, which can be useful for handling auto-incrementing IDs and other sequence-based logic in your database.

• Ruby 3.3+ (Download Ruby)
• Rails 8.0.0+ (RubyGems - Rails Versions)
• ActiveRecord 8.0.0+ (comes with Rails)

To use postgresql_adapter_extensions in your Rails application, add the following line to your Gemfile:

gem "postgresql_adapter_extensions"

And then execute:

$ bundle install

Or otherwise simply install it yourself as:

$ gem install postgresql_adapter_extensions

The create_sequence method allows you to create a new sequence in your PostgreSQL database with customizable options. A sequence is typically used to auto-generate unique values for primary keys or other incrementing columns.

create_sequence(name, options = {})

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 and column:

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

The alter_sequence method allows you to modify an existing sequence in your PostgreSQL database. You can change various attributes of the sequence, such as its increment, start value, maximum value, cycle behavior, and ownership.

alter_sequence(name, options = {})

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

This method provides flexibility in managing sequences dynamically in your Rails application, ensuring that sequence-related database behavior can be modified as needed.

The drop_sequence method allows you to drop an existing sequence from your PostgreSQL database, with options to control its behavior.

drop_sequence(name, options = {})

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)

If you're contributing to this gem and need to set up PostgreSQL for local development or testing, you can use the provided setup script. This script will help you create the necessary PostgreSQL user and database for testing.

1. Clone the repository and navigate to the root directory of the gem.

2. Make sure you have PostgreSQL installed and running on your machine.

3. Run the script using the following command:

   $ ./bin/setup_postgresql.sh

   By default, the script will use the following values unless environment variables are set:

   1. Database Name: rails_test
   2. Username: rails
   3. Password: password

4. If you want to override these defaults, set the environment variables before running the script:

   $ POSTGRES_DB=rails_test POSTGRES_USER=rails POSTGRES_PASSWORD=password ./bin/setup_postgresql.sh

5. The script will:

   • Check if the specified PostgreSQL user exists, creating it if necessary.
   • Check if the specified database exists, creating it if necessary.
   • Grant the required privileges to the user for the database.

Note: This script is only required if you're contributing to the development of the gem or testing locally. It is not required for end users of the gem.

The gem includes RSpec tests to verify that the sequence methods behave as expected.

To run the tests, you need to install the required dependencies first:

$ bundle install

Then, run the tests with:

$ bundle exec rspec

The tests are located in the spec/ directory and verify the behavior of create_sequence, alter_sequence, and drop_sequence methods.

Contributions to this project are welcomed! To contribute:

1. Fork this repository
2. Create a new branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am "Add some feature")
4. Push the changes to your branch (git push origin my-new-feature)
5. Create new Pull Request

Copyright 2025 Harshal V. LADHE, Released under the MIT License.