'\" -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH "SLONIK SET ADD TABLE" 7 "24 July 2014" "" "Slony-I 2.2.3 Documentation"
.SH NAME
SET ADD TABLE \- Add a table to a Slony-I replication set 
.SH SYNOPSIS
'nh
.fi
.ad l
\fBSET ADD TABLE (options);\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
Add an existing user table to a replication set. The set
cannot currently be subscribed by any other node - that
functionality is supported by the \fBSLONIK MERGE
SET\fR(7)
command.
.TP 
\*(T<SET ID = ival \*(T>
ID of the set to which the table is to be added. 
.TP 
\*(T<ORIGIN = ival \*(T>
Origin node for the set. (Optional) 
.TP 
\*(T<ID = ival \*(T>
Unique ID of the table. These ID's are not
only used to uniquely identify the individual table within the
replication system. The numeric value of this ID also
determines the order in which the tables are locked in a \fBSLONIK LOCK SET\fR(7) command for example. So
these numbers might represent any applicable table hierarchy
to make sure the slonik command
scripts do not deadlock at any critical
moment. If this parameter is omitted then slonik will
check every node that it can connect to and find the 
highest table id being used across all nodes.

This ID must be unique across all sets; you cannot
have two tables in the same cluster with the same
ID. 

Note that Slony-I generates an in-memory array
indicating all of the fully qualified table names; if you use
large table ID numbers, the sparsely-utilized array can lead
to substantial wastage of memory. Each potential table ID
consumes a pointer to a char, commonly costing 4 bytes per
table ID on 32 bit architectures, and 8 bytes per table ID on
64 bit architectures. 
.TP 
\*(T<FULLY QUALIFIED NAME = 'string' \*(T>
The full table name including the name of the schema. 
This can be omitted if \*(T<TABLES\*(T> is specified instead
.TP 
\*(T<KEY = { 'string' | SERIAL } \*(T>
\fI(Optional)\fR The index name that covers the
unique and not null set of columns to be used as the row identifier
for replication purposes. Default
is to use the table's primary key. The index name is \fInot \fRfully qualified; you must omit the
namespace.
.TP 
\*(T<TABLES = 'string' \*(T>
A POSIX regular expression that specifies the
list of tables that should be added. This regular expression
is evaluated by PostgreSQL against the list of fully qualified table
names on the set origin to find the tables that should be added.
If \*(T<TABLES\*(T> is omitted then \*(T<FULLY QUALIFIED NAME\*(T> must be specified.
.RS 
\fBWarning\fR

The \*(T<TABLES\*(T> option requires
that all the tables are in \(oqgood form\(cq to be replicated
en masse. The request will fail, not configuring any tables
for replication, if it encounters any of the following
problems:
.RS 
.TP 0.2i
\(bu
Each table must have a \*(T<PRIMARY
KEY\*(T> defined, and a candidate primary key will not
suffice.
.TP 0.2i
\(bu
If a table is found that is already
replicated, the request will fail.
.TP 0.2i
\(bu
The \*(T<TABLES\*(T> option needs
to automatically assign table ID values, and looks through
the configuration on every node specified by \fBSLONIK ADMIN CONNINFO\fR(7), finding the largest ID in use, and
starting after that for the table IDs that it
assigns.

It considers it a \(oqbenign\(cq failure to
find a node that does not yet have a Slony-I schema
assigned, as that may be expected to occur if tables are
configured before all the nodes have been configured using
\fBSLONIK STORE NODE\fR(7). If there is no Slony-I
schema, then that node certainly hasn't contributed
anything to an increase in the table IDs in use.

On the other hand, if a node specified by \fBSLONIK ADMIN CONNINFO\fR(7) is not available to be queried,
the request \fIwill
fail.\fR
.RE
.RE
.TP 
\*(T<COMMENT = 'string' \*(T>
A descriptive text added to the table entry. 
.TP 
\*(T<ADD SEQUENCES= boolean\*(T>
A boolean value that indicates if any sequences attached
to columns in this table should also be automatically
added to the replication set. This defaults to false
.PP
This uses \(lqschemadocsetaddtable(p_tab_comment integer, p_tab_idxname integer, p_fqname text, p_tab_id name, p_set_id text)\(rq [not available as a man page]. 
.SH EXAMPLE
.nf
\*(T<SET ADD TABLE (
    SET ID = 1,
    ORIGIN = 1,
    ID = 20,
    FULLY QUALIFIED NAME = 'public.tracker_ticket',
    COMMENT = 'Support ticket',
    ADD SEQUENCES=false
);

or 

SET ADD TABLE (
    SET ID=1,
    TABLES='public\e\e.tracker*'
);

    \*(T>
.fi
.SH "ERROR MESSAGES "
Here are some of the error messages you may encounter if
adding tables incorrectly: 
.TP 
\*(T<Slony\-I: setAddTable_int: table public.my_table PK column id nullable \*(T>
Primary keys (or candidates thereof) are
required to have all column defined as \fBNOT
NULL\fR. If you have a PK candidate that has columns
that are not thus restricted, Slony-I will reject the table
with this message. 
.TP 
\*(T<Slony\-I: setAddTable_int: table id 14 has already been assigned! \*(T>
The table id, stored in
\fBsl_table.tab_id\fR, is required to be unique
across all tables/nodes/sets. Apparently you have tried to
reused a table ID. 
.TP 
\*(T<Slony\-I: setAddTable_int(): table public.my_table has no index mt_idx_14\*(T>
This will normally occur with candidate
primary keys; apparently the index specified is not available
on this node. 
.TP 
\*(T<Slony\-I: setAddTable_int(): table public.my_table not found \*(T>
Worse than an index missing, the whole table
is missing. Apparently whatever process you were using to get
the schema into place everywhere didn't work properly. 
.TP 
\*(T<Slony\-I: setAddTable_int(): public.my_view is not a regular table \*(T>
You can only replicate (at least, using
\fBSET ADD TABLE\fR) objects that are ordinary
tables. That doesn't include views or indexes. (Indexes can
come along for the ride, but you don't ask to replicate an
index...) 
.TP 
\*(T<Slony\-I: setAddTable_int(): set 4 not found \*(T>
You need to define a replication set before
assigning tables to it. 
.TP 
\*(T<Slony\-I: setAddTable(): set 4 has remote origin \*(T>
This will occur if set 4 is configured with,
as origin, node 1, and then you submit a \fBSET ADD
TABLE\fR request involving that set to some other node
than node 1. This would be expected to occur if there was
some confusion in the \fBadmin conninfo\fR
configuration in the slonik script preamble...
.TP 
\*(T<Slony\-I: cannot add table to currently subscribed set 1 \*(T>
Slony-I does not support adding tables to
sets that are already participating in subscriptions.
Instead, you need to define a new replication set, and add any
new tables to \fIthat\fR set. You might then
use \fBSLONIK MERGE
SET\fR(7) to merge the new set into an
existing one, if that seems appropriate. 
.SH "LOCKING BEHAVIOUR "
On the origin node, this operation requires a brief
exclusive lock on the table in order to alter it to add 
replication triggers. On subscriber nodes, corresponding locking
takes place at the time of the \fBSUBSCRIBE_SET\fR
event. 
.SH "SLONIK EVENT CONFIRMATION BEHAVIOUR "
Slonik waits for the command submitted to the previous
event node to be confirmed on the specified event node before
submitting this command.
.SH "VERSION INFORMATION "
This command was introduced in Slony-I 1.0