Home

Awesome

pglistend

npm version npm downloads Code Climate

A lightweight Postgres LISTEN Daemon built on top of node, node-postgres and systemd.

It's a very simple yet generic daemon application that could be used in any project that makes use of Postgres' LISTEN/NOTIFY feature.

It runs as a background process that does LISTEN on the configured channels on a database and allows to perform custom actions on receiving NOTIFY signals on those channels.

Check this simple tutorial to get started with it.

Installation

Firstly, install the npm package globally. This will make pglisten CLI tool available on your system.

$ npm install -g pglistend

Now setup the daemon using this command.

$ sudo pglisten setup-daemon

Or, alternatively you can curl the script and run it on the fly.

$ curl https://raw.githubusercontent.com/kabirbaidhya/pglistend/master/setup/setup.py | sudo python

When it's done, edit your configuration. And finally start the service using

$ sudo systemctl start pglistend

Usage

Managing the daemon

You can use systemd commands to manage pglistend.

# Start the service
$ systemctl start pglistend

# Stop the service
$ systemctl stop pglistend

# Check service status
$ systemctl status pglistend

# Enable the service (This will start the service on bootup)
$ systemctl enable pglistend

# Disable the service (Disable the service to not start on bootup)
$ systemctl disable pglistend

For more information about systemd check this

Logs

All logs are written to syslog. So, you can make use of journalctl here

$ journalctl -u pglistend
$ journalctl -f -u pglistend

Or, you can simply tail the logs like this:

$ tail /var/log/syslog | grep pglistend
$ tail -f /var/log/syslog | grep pglistend

Check this to read more about journalctl.

Tutorials

  1. Getting Started
  2. Performing custom actions

Testing

  1. Clone repository: git clone git@github.com:kabirbaidhya/pglistend.git
  2. Install dependencies: npm install
  3. Install other required packages:
    • pycodestyle: pip install pycodestyle or pip install --upgrade pycodestyle [Reference]
    • pylint: sudo apt-get install pylint [Reference]
  4. Copy configuration file config.yml.sample and rename to .pglistend.yml in root directory. Update database credentials, channels and location of scripts.
  5. To prepare a script, copy listener.js.sample and save it as listener.js, or anything you wish, to any location(recommended to save outside project directory). Update the preferred channels and instructions in the script. Also, update the location of script in .pglistend.yml.
  6. From terminal in root directory, run: npm start. You can see the logs in terminal as the channels hit the queries when the notify operation is called on.

TODOs