activerecord-postgres_pub_sub
This gem contains support for PostgreSQL LISTEN and NOTIFY functionality: doc.
Installation
Add this line to your application's Gemfile:
gem "activerecord-postgres_pub_sub"
And then execute:
$ bundle
Or install it yourself as:
$ gem install activerecord-postgres_pub_sub
Usage
Listener
The Listener
class is used to handle notification messages on one or more
channels.
The listener can be configured with three blocks:
- on_notify: called whenever a notification is received.
- on_start: called before receiving any notifications.
- on_timeout: called based on a configurable timeout, when no notifications have been received.
When creating a listener, the following configuration is supported:
- listen_timeout: If set, the
on_timeout
block will be called if no notifications are received within this period. (Defaultnil
). - notify_only: A payload string can be included in notifications. By default
the listener ignores the payload and coalesces multiple notifications into a
single call. When this option is
false
, theon_notify
block is called with the payload for each notification. (Defaulttrue
). - base_class: An Active Record class should you need to use a different base
class (e.g. for multiple database support). (Default
ActiveRecord::Base
). - exclusive_lock: Acquire a lock using
with_advisory_lock prior to listening.
This option ensures that a process as a singleton listener. (Default
true
).
Example:
ActiveRecord::PostgresPubSub::Listener.listen("notify_channel", listen_timeout: 30) do |listener|
listener.on_start do
# when starting assume we missed something and perform regular activity
handle_notification
end
listener.on_notify do
handle_notification
end
listener.on_timeout do
perform_regular_maintenance
end
end
Generator
This gem contains a Rails generator for a migration to add a trigger to notify on insert to a table.
The generator must be run with a model name corresponding to the table.
rails generate active_record:postgres_pub_sub:notify_on_insert --model_name NameSpace::Entity
In this example, notification events would be generated for the channel named "name_space_entity"
based
on inserts to the name_space_entities
table.
Supported dependencies
This gem will not support versions of ruby and activerecord which no longer receive security updates. It will support the latest major version of the pg gem and it will be tested against the latest minor / patch version of that gem.
Development
After checking out the repo, run bin/setup
to install dependencies. Then,
run rake spec
to run the tests. You can also run bin/console
for an
interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
To release a new version, update the version number in version.rb
, and then
run bundle exec rake release
, which will create a git tag for the version,
push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/ezcater/activerecord-postgres_pub_sub.
License
The gem is available as open source under the terms of the MIT License.