Slonik Command Summary

1. Introduction

Slonik is a command line utility designed specifically to setup and modify configurations of the Slony-I replication system.

1.1. General outline

The slonik commandline utility is supposed to be used embedded into shell scripts and reads commands from files or stdin (via here documents for example). Nearly all of the real configuration work is done by calling stored procedures after loading the Slony-I support base into a database. You may find documentation for those procedures in the Slony-I Schema Documentation, as well as in comments associated with them in the database.

Slonik was created because:

  • The stored procedures have special requirements as to on which particular node in the replication system they are called,

  • The lack of named parameters for stored procedures makes it rather difficult to do this from the psql prompt, and

  • psqllacks the ability to maintain multiple connections with open transactions.

1.1.1. Commands

The slonik command language is format free. Commands begin with keywords and are terminated with a semicolon. Most commands have a list of parameters, some of which have default values and that are therefore optional. The parameters of commands are enclosed in parentheses. Each option consists of one or more keywords, followed by an equal sign, followed by a value. Multiple options inside the parentheses are separated by commas. All keywords are case insensitive. The language should remind the reader of SQL.

Option values may be:

  • integer values

  • string literals enclosed in single quotes

  • boolean values {TRUE|ON|YES} or {FALSE|OFF|NO}

  • keywords for special cases

1.1.2. Comments

Comments begin at a hash sign (#) and extend to the end of the line.

1.1.3. Command groups

Commands can be combined into groups of commands with optional on error and on success conditionals. The syntax for this is:

       try {
       commands;
       } 
       [on error { commands; }]
       [on success { commands; }]
      

Those commands are grouped together into one transaction per participating node.

Note that this does not enforce grouping of the actions as a single transaction on all nodes. For instance, consider the following slonik code:

     try {
         execute script (set id = 1, filename = '/tmp/script1.sql', event node=1);
         execute script (set id = 1, filename = '/tmp/script2.sql', event node=1);
     }
     

This would be processed within a single BEGIN/COMMIT on node 1. However, the requests are separated into two DDL_SCRIPT events so that each will be run individually, in separate transactions, on other nodes in the cluster.