NAME

Net::Clacks::PostgreSQL2Clacks - write-only support client for PostgreSQL messaging

SYNOPSIS

  use Net::Clacks::PostgreSQL2Clacks;

  # Create new instance.
  my $pgclacks = Net::Clacks::PostgreSQL2Clacks->new(
      clacks => {
          server => '127.0.0.1',
          port => '4988',
          username => 'exampleuser',
          password => 'unsafepassword',
          clientname => 'PostgreSQL 2 Clacks Bridge',
          caching => 0,
      },
      postgres => {
          url => 'dbi:Pg:dbname=TropicoDB;host=/var/run/postgresql;sslmode=disable',
          username => 'ElPresidente',
          password => 'WorldDomination',
      },
  );
  # If you want to use Clacks with Unix domain sockets (can be a lot faster!), replace "server" and "port" with "socket" and point it to server socket
  # e.g. socket => '/my/path/to/server.socket"

  # run the PostgreSQL "CREATE OR REPLACE FUNCTION" calls. This needs the proper PostgreSQL permissions.
  # Only needs to be run once per database and after that only if the UpgradeGuide calls for it.
  $pgclacks->initFunctions();


  # Use the in-build event loop (never returns)
  $pgclacks->run();

  # ... or use your own event loop
  while($keeprunning) {
      # do your stuff

      $pgclacks->runOnce();
  }

DESCRIPTION

This implements a simple "write-only" support client to allow sending clacks messages from PostgreSQL. This makes it easy (or at least "easier") to implement database triggers that send clacks messages.

And example would be a price list for articles. Whenever articles get updated in the database, it can now trigger a clacks message that requests all clients to reload the price data from the database. In some cases this can reduce server load, because the clients now only have to listen for small network messages instead of constantly polling the database.

Another example would be a live counter. Say you implement a mail server that knows how to stuff mails into the database but doesn't know how to "speak clacks". With the help of PostgreSQL2Clacks, you can now add a PostgreSQL trigger that calls clacks_increment(), and every time new mail arrives, the live counter gets incremented.

Technically, this works by using the PostgreSQL inbuild LISTEN/NOTIFY functionality. This module provides a few extra PostgreSQL server side functions. The database trigger calls these, the functions concatenate the message parts with some delimeters and send a PostgreSQL "NOTIFY" message. This client LISTENs for them, un-concatenate the message parts and call the corresponding Net::Clacks::Client function.

Perl functions

new

Create a new instance, see SYNOPSIS.

initFunctions

initFunctions() installs (and upgrades) the required PostgreSQL server side functions. Only needs to be run once per database instances. But make sure to check the Net::Clacks::UpgradeGuide when upgrading. It may require you to run initFunctions again.

This is designed this way so you can use the client without having to give it the "CREATE" privilege during normal running. This is only required for installing and upgrading.

runOnce

Run the event loop once. Use this if you implement your own event loops in your application. Make sure to call it at least once every 10 seconds or so, shorter intervals are better.

run

Just hand over everything to Net::Clacks::PostgreSQL2Clacks. Unless something goes horribly wrong, it will never return. Perfect for creating a small standalone PostgreSQL to Clacks bridge.

getStatements

Technically an internal function which returns all the "CREATE" statements used in initFunctions(). If you don't want to give the client "CREATE" permissions, you can use something like this to just list all the statements to run them by hand in your psql console:

  my @stmts = $pgclacks->getStatements();

  foreach my $stmt (@stmts) {
      print $stmt, "\n\n";
  }

You would still need a valid connection to clacks and the database, though, for the client.

DESTROY

This tries to close the connection cleanly but there is a good chance it wont succeed cleanly under certain circumstances, especially on program exit. Blame the random order Perl calls DESTROY.

PostgreSQL functions

clacks_notify(clacksname TEXT)

NOTIFY via clacks that event "clacksname" has happened

clacks_set(clacksname TEXT, clacksvalue TEXT)

SET clacks real-time value "clacksname" to "clacksvalue"

clacks_store(clacksname TEXT, clacksvalue TEXT)

STORE clacks cache value "clacksname" with "clacksvalue"

clacks_setandstore(clacksname TEXT, clacksvalue TEXT)

Combines SET and STORE in one go

clacks_increment(clacksname TEXT, clacksvalue TEXT)

INCREMENT clacks cache value "clacksname" by "clacksvalue"

(yes, you send a TEXT, not a BIGINT or something similar.)

clacks_decrement(clacksname TEXT, clacksvalue TEXT)

DECREMENT clacks cache value "clacksname" by "clacksvalue"

(yes, you send a TEXT, not a BIGINT or something similar.)

clacks_remove(clacksname TEXT)

REMOVE clacks cache value "clacksname"

IMPORTANT NOTE

Please make sure and read the documentations for Net::Clacks as it contains important information pertaining to upgrades and general changes!

AUTHOR

Rene Schickbauer, <cavac@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008-2023 Rene Schickbauer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

cpanm Net::Clacks

perl -MCPAN -e shell
install Net::Clacks