Simple way to NOTIFY and LISTEN to channels in PostgreSQL

Inspired by https://gist.github.com/tpitale/3915671

Project Celluloid IO PG Listener
gem name celluloid-io-pg-listener
license MIT
moldiness Maintainer Status
version Gem Version
dependencies Dependency Status
code quality Code Climate
inline documenation Inline docs
continuous integration Build Status
test coverage Coverage Status
homepage https://github.com/pboling/celluloid-io-pg-listener
documentation http://rdoc.info/github/pboling/celluloid-io-pg-listener/frames
author Peter Boling
Spread ~♡ⓛⓞⓥⓔ♡~ Endorse Me


Add this line to your application's Gemfile:

gem 'celluloid-io-pg-listener'

And then execute:

$ bundle

Or install it yourself as:

$ gem install celluloid-io-pg-listener


Find a data base that exists that you want to run notifications through. Won't affect anything else in the database, so doesn't matter which one you pick. Then pick an arbitrary name for the channel. Only requirement is that the server and the client use the same database name and channel name or they won't be communicating.

In an irb session

>> require "celluloid-io-pg-listener"

=> true

>> CelluloidIOPGListener::Server.new(dbname: "test_database", channel: "test_channel" )

I, [2015-10-06T12:38:43.728686 #5880]  INFO -- : Server will send notifications to archer_test:test

=> #<Celluloid::Proxy::Cell(CelluloidIOPGListener::Server:0x3ff732194f24) @dbname="test_database" @channel="test_channel" @sleep_interval=0.1 @run_interval=1>

I, [2015-10-06T12:38:44.105265 #5880]  INFO -- : Notified test

>> CelluloidIOPGListener::Listener.new(dbname: "test_database", channel: "test_channel" )

=> #<Celluloid::Proxy::Cell(CelluloidIOPGListener::Listener:0x3fd6ace33cb8) @dbname="test_database" @listening=true @pg_connection=#<PG::Connection:0x007fad59c5f978> @actions={"test_channel"=>:do_something}>

I, [2015-10-06T12:40:38.110541 #5952]  INFO -- : Client will for notifications on test_database:test_channel
I, [2015-10-06T12:40:38.110822 #5952]  INFO -- : Starting Listening
I, [2015-10-06T12:40:50.117444 #5952]  INFO -- : Received notification: ["test", 5968, "1444160450"]
I, [2015-10-06T12:40:50.117518 #5952]  INFO -- : Doing Something with Payload: 1444160450 on test
I, [2015-10-06T12:40:50.117541 #5952]  INFO -- : 1444160450
I, [2015-10-06T12:40:51.107977 #5952]  INFO -- : Received notification: ["test", 5968, "1444160451"]
I, [2015-10-06T12:40:51.108071 #5952]  INFO -- : Doing Something with Payload: 1444160451 on test
I, [2015-10-06T12:40:51.108104 #5952]  INFO -- : 1444160451
I, [2015-10-06T12:40:52.112797 #5952]  INFO -- : Received notification: ["test", 5968, "1444160452"]
I, [2015-10-06T12:40:52.112881 #5952]  INFO -- : Doing Something with Payload: 1444160452 on test
I, [2015-10-06T12:40:52.112911 #5952]  INFO -- : 1444160452

The Listener class included is just a proof of concept. It shows you how to use the Client module to make your own listener class that does what you need done.

module CelluloidIOPGListener
  # An example Client class
  class Listener

    include CelluloidIOPGListener::Client

    def initialize(dbname:, channel:)
      info "Client will for notifications on #{dbname}:#{channel}"
      @dbname = dbname
      async.listen(channel, :do_something)

    def do_something(channel, payload)
      unlisten_wrapper(channel, payload) do
        info payload



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.


Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/celluloid-io-pg-listener. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  6. Create new Pull Request


This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency 'celluloid-io-pg-listener', '~> 0.1'


The gem is available as open source under the terms of the MIT License.