Quickstart

You can follow steps 0-9 for a brief Narugn tour.

See also "PostgreSQL database server configuration" below.

Step 0: Prerequisites

A PostgreSQL 9.1 database server, on which there is an "narugn"
superuser which can connect seamlessly from the postgres system user
and from any other user you wish to use (for instance you might want
to set both ~postgres/.pgpass and your ~/.pgpass accordingly). You
also need to set

search_path = narugn_logic, narugn, public

for the narugn PostgreSQL user.

The "plproxy" extension must be installed.

Step 1: Install Narugn

Narugn is a PostgreSQL 9.1 extension; hence it can be installed just
like any PostgreSQL extension.

Note. A "Narugn server" is just a PostgreSQL database server where the
Narugn extension has been installed.

Step 2: Design your Narugn server

Before we create the first Narugn cell, we need to choose sensible
values for the following settings of our Narugn server:

polygon

short_name

full_name

local_connstr

connstr (i.e. the remote connection string)

"polygon" is a value of type "polygon", and must contain at least one
point with integer coordinates. For instance, we choose the following:

polygon '1.8, 1.8, 5.4, 1.6, 3.0, 5.3'

which contains points (2,2) and (3,2).

"short_name" is a text value, and must be a valid PostgreSQL
identifier. We choose "test1".

"full_name" is any text value. We choose "Test Narugn server #1".

"local_connstr" and "connstr" are text values, and must be valid
PostgreSQL connection strings. "local_connstr" will be used to connect
from cells in the same Narugn server, while "connstr" will be used to
connect to this server from cells in neighbouring Narugn servers.

Step 4: create subsequent Narugn cells

Once you have created a Narugn cell, you can clone it to create
additional Narugn cells on the same Narugn server. The procedure is
almost the same, except that when running narugn.configure_cell you
only need to provide local_connstr and the coordinates for the
existing cell that you are cloning from.

Note. Creating new Narugn cells by cloning existing ones ensures that
the Narugn server configuration is consistent across all the Narugn
cells in that server.

Step 5: Rescan

There are several ways to operate a Narugn cluster. Here we will only
see the "execute_sync" function, which runs a given "cell function" on
all the accessible cells, waits for all the functions to finish, and
returns the combined output.

First, we connect to one of the Narugn cell databases that have been
created (for instance "narugn_cell_2_2"), and run the "ping" cell
function:

"rpfp" is an acronym of "request permission for propagation", and is
used to implement partial propagation of cell functions, such as in
the new_server cell function. This cell function just returns 'true'
because it always agrees to be propagated to its neighbours (if any).

Step 8: Empty the Narugn cluster

Cells in an Narugn server can be dropped just by dropping the related
database, because there is no Narugn master database.

Step 9: Uninstall Narugn software

Since Narugn is packaged as a PostgreSQL 9.1 extension, the Narugn
software can be uninstalled just like any other extension.

PostgreSQL database server configuration

In order to connect two or more Narugn clusters, the underlying
PostgreSQL database servers need to be allowed to talk to each other.

In Debian GNU/Linux systems, localhost is bound to the address
127.0.0.1 while the hostname is bound to 127.0.1.1 .

Incoming connections will be either directed to localhost or to the
hostname, therefore the PostgreSQL server needs to listen on both
addresses. It is also necessary to listen on the network interface
that receives connections from neighbouring hosts. For instance, if
your system is reachable by its neighbours at server.my.lan, whose IP
is 192.168.12.34, you can set