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.

Our choices:

local_connstr = 'host=localhost port=5432' connstr = 'host=myhost.lan port=5432'

Step 3: Create the first Narugn cell

Now we can create a cell; we just need to decide at which coordinates. They must be integers and be included in the Narugn server polygon that we have chosen in the previous step.

Our choice will be (2,2); therefore the corresponding Narugn cell database name will be "narugn_cell_2_2".

Then, we connect to the "postgres" database and issue:

postgres=# CREATE DATABASE narugn_cell_2_2; CREATE DATABASE postgres=# \c narugn_cell_2_2 narugn You are now connected to database "narugn_cell_2_2" as user "narugn". narugn_cell_2_2=# CREATE EXTENSION plproxy; CREATE EXTENSION narugn_cell_2_2=# CREATE EXTENSION narugn; CREATE EXTENSION narugn_cell_2_2=# SELECT narugn.configure_cell( short_name := 'test1', full_name := 'Test Narugn server #1', polygon := polygon '1.8, 1.8, 5.4, 1.6, 3.0, 5.3', local_connstr := 'host=localhost port=5432', connstr := 'host=myhost.lan port=5432'); configure_cell


OK (1 row)

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.

In our case, the coordinates for the new cell will be (3,2), hence:

postgres=# CREATE DATABASE narugn_cell_3_2; CREATE DATABASE postgres=# \c narugn_cell_3_2 narugn You are now connected to database "narugn_cell_3_2" as user "narugn". narugn_cell_3_2=# CREATE EXTENSION plproxy; CREATE EXTENSION narugn_cell_3_2=# CREATE EXTENSION narugn; CREATE EXTENSION narugn_cell_3_2=# SELECT configure_cell( cell := '(2,2)' :: cds, local_connstr := 'host=localhost port=5432'); configure_cell


OK (1 row)

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:

narugn_cell_2_2=# SELECT * FROM execute_sync('ping'); c | z | dt | output -------+---+-----------------+-------- (2,2) | 1 | 00:00:00.026046 | OK (1 row)

Neighbouring cell (3,2) does not answer, because it is not yet visible from cell (2,2). Therefore we rescan the network from cell (2,2):

c   | z |       dt        |        output         

-------+---+-----------------+----------------------- (2,2) | 1 | 00:00:00.031397 | {.ok.,skip,skip,skip} (3,2) | 1 | 00:00:00.352463 | {skip,skip,.ok.,skip} (2 rows)

If we ping again, we now see that both cells can be reached:

narugn_cell_2_2=# SELECT * FROM execute_sync('ping'); c | z | dt | output -------+---+-----------------+-------- (2,2) | 1 | 00:00:00.012543 | OK (3,2) | 1 | 00:00:00.027754 | OK (2 rows)

Step 6: Loading Logic

Narugn code is divided in two parts, called "Extension" and "Logic".

This separation is motivated by the need to allow frequent and easy updates of one part of the code (Logic), while keeping the other part (Extension) small and stable.

The Extension code is loaded by the CREATE EXTENSION statement, which must be issued separately on each node.

The Logic code is loaded via a dedicated cell function, which propagates it to all the other cells via Narugn itself. The Logic code is passed as a base64 encoded string.

Example. If you have a SQL file named "base.sql" which contains the Logic that you want to load into an existing Narugn cluster, just issue

SELECT * FROM execute_sync('logic','$(base64 base.sql)');

on one cell, and the new Logic will be propagated to all the cells in the Narugn cluster, replacing any pre-existing code (make sure the "base64" command line utility is installed).

Step 7: Other cell functions

Note. Except for "version", all the cell functions described in this section are part of Logic.

The "version" command provides version information about the operating system, the PostgreSQL server and the installed Narugn extensions on each cell:

narugn_cell_2_2=# SELECT * FROM execute_sync('version'); c | z | t | output
-------+---+-------------------------------+--------------------------------------------------------------------------------------- (2,2) | 1 | 2012-07-02 22:11:01.16742+01 | PostgreSQL 9.1.4 on i686-pc-linux-gnu, compiled by gcc (Debian 4.7.0-9) 4.7.0, 32-bit (2,2) | 2 | 2012-07-02 22:11:01.167917+01 | Narugn 1.0.0 (3,2) | 1 | 2012-07-02 22:11:01.184062+01 | PostgreSQL 9.1.4 on i686-pc-linux-gnu, compiled by gcc (Debian 4.7.0-9) 4.7.0, 32-bit (3,2) | 2 | 2012-07-02 22:11:01.184557+01 | Narugn 1.0.0 (4 rows)

The "server" command provides information about the server to which each cell belongs:

narugn_cell_2_2=# SELECT * FROM execute_sync('server'); c | z | t | output
-------+---+-------------------------------+---------------------------------------------------------------------------------------------------------------------------- (2,2) | 1 | 2012-07-02 22:11:36.304184+01 | (test1,"Test Narugn server #1","((1.8,1.8),(5.4,1.6),(3,5.3))","host=myhost.lan port=5432","host=localhost port=5432") (3,2) | 1 | 2012-07-02 22:11:36.320489+01 | (test1,"Test Narugn server #1","((1.8,1.8),(5.4,1.6),(3,5.3))","host=myhost.lan port=5432","host=localhost port=5432") (2 rows)

The "traceroute" command is similar to "ping", but it remembers the route that was followed to reach each cell:

narugn_cell_2_2=# SELECT * FROM execute_sync('traceroute'); c | z | t | output
-------+---+-------------------------------+--------------------------------------------------------------------------------------- (2,2) | 1 | 2012-07-02 22:12:20.651231+01 | {"(2,2,\"2012-07-02 22:12:20.649637+01\")"} (3,2) | 1 | 2012-07-02 22:12:20.667166+01 | {"(2,2,\"2012-07-02 22:12:20.649637+01\")","(3,2,\"2012-07-02 22:12:20.665547+01\")"} (2 rows)

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 need to set

postgresql.conf


listen_addresses = 'localhost, 127.0.1.1, 192.168.12.34'

and

pg_hba.conf


local all narugn md5 hostnossl all narugn 127.0.0.1/8 md5 host all narugn 192.168.12.0/24 md5

since 192.168.12.34 belongs to the class C network 129.168.12.0/24.