README.textile

Irmgard

PostgreSQL Change Detection and Replication Framework for Clojure.

Irmgard uses PostgreSQL Triggers to watch for changes to row data, and leverages LISTEN and NOTIFY to notify your code so you can react as quickly as possible.

Installing Irmgard in your database

Run install.sh

 bash install.sh [[database_name]] sql/plpgsql/irmgard.sql 

This will:

• Create irmgard schema
• Create irmgard.row_changes table
• Create irmgard.stats table
• Create irmgard.process_log table
• Installs PL/PGSQL procedures

To enable Irmgard to track a table, execute the following in your database:

SELECT irmgard.enable_tracking_int_pk('your_schema_name.your_table_name', 'id');

Starting the Irmgard process in your JVM

The Irmgard process is implemented as a background thread. The thread attaches to the database and executes the PostgreSQL LISTEN command. This thread will re-connect to the databse and re-execute LISTEN if any error occurrs. Irmgard also performs a poll every few seconds in case the LISTEN infrastructre does not notify it of changes.

When notified, the Irmgard process attempts to obtain a lock on irmgard.row_changes with NOWAIT. If it obtains the lock, it then processes the records in irmgard.row_changes, triggering any registered listeners for groups of those rows.

Registering Listeners

Listeners are registered via the following tuple:

 [ listener-name, database-name, schema-name, table-name, implementation-fn ]

Maintenence

Suspending Triggers/Events during ALTER TABLE or bulk UPDATE

NOT YET IMPLEMENTED

For very large tables, if you perform an ALTER or bulk UPDATE commands, you may want to suppress event generation during those operations. To suspend the trigger’s, call the following pl/pgsql function:

 irmgard.disable_all_events()
      irmgard.disable_all_events(table_name)

To re-enable, call the following pl/psql function:

 irmgard.enable_all_events()
      irmgard.enable_all_events(table_name)

Etymology of Irmgard, see: “Irmgard Replicant”.