root/traduc/trunk/slony/firstdb.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- DerniÚre modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<sect1 id="firstdb"><title>Répliquer votre premiÚre base de données</title>

<indexterm><primary>Répliquer votre premiÚre base de données</primary></indexterm>

<para>Dans cet exemple, nous allons répliquer une base de donnée
  <application>pgbench</application> neuve.  Les mécanismes de réplications
  d'une base existante sont abordé ici, cependant nous vous recommandons d'apprendre 
  comment utiliser les fonctions &slony1; en utilisant une base fraîchement créée,
  placée sur un serveur qui n'est pas en production.</para>

<para> Notez que <application>pgbench</application> est une outil de <quote>tests</quote> ( "benchmark" )
  qui se trouve parmi les outils <filename>contrib</filename> de &postgres; Si vous compilez &postgres;
  depuis les sources, vous devez vous rendre dans le répertoire <filename>contrib/pgbench</filename>
  et exécuter la commande <command>make install</command> pour le compiler et l'installer;
  Vous pouvez par ailleurs le trouver inclus dans les paquets binaires de  &postgres;.
</para>

<para>Le moteur de réplication de &slony1; est basée sur les triggers, ce qui permet 
  répliquer des bases de données ( ou des parties de celles-ci ) hébergées par le 
  même postmaster.</para>

<para>Cet exemple montre comment répliquer la base <application>pgbench</application> 
  hébergées sur localhost (maître) vers la base <application>pgbench</application> esclave 
  hébergée elle aussi sur localhost (esclave). Nous nous basons sur deux suppositions
  Ã  propos de votre configuration de &postgres; :
<itemizedlist>

<listitem><para> Vous avez la ligne <option>tcpip_socket=true</option> dans votre 
<filename>postgresql.conf</filename> et </para></listitem>

<listitem><para> Vous avez activer les accÚs à votre cluster via 
<filename>pg_hba.conf</filename></para></listitem>

</itemizedlist></para>

<para> L'utilisateur <envar>REPLICATIONUSER</envar> doit être un super-utilisateur 
  &postgres;.  C'est en général, postgres ou pgsql, cependant au sein d'environnements
  complexes, il est parfois judicieux de définir un utilisateur <command>slony</command> 
  pour distinguer les différents rÎles.</para>

<para>Vous devez également définir les variables shell suivantes :

<itemizedlist>
<listitem><para> <envar>CLUSTERNAME</envar>=exemple_slony</para></listitem>
<listitem><para> <envar>MASTERDBNAME</envar>=pgbench</para></listitem>
<listitem><para> <envar>SLAVEDBNAME</envar>=pgbench_esclave</para></listitem>
<listitem><para> <envar>MASTERHOST</envar>=localhost</para></listitem>
<listitem><para> <envar>SLAVEHOST</envar>=localhost</para></listitem>
<listitem><para> <envar>REPLICATIONUSER</envar>=pgsql</para></listitem>
<listitem><para> <envar>PGBENCHUSER</envar>=pgbench</para></listitem>
</itemizedlist>
</para>
<para>Voici deux maniÚres de paramétrer ces variables avec un shell standard :

<itemizedlist>
<listitem>
  <para>bash, sh, ksh
  <command>export CLUSTERNAME=exemple_slony</command></para>
</listitem>
<listitem>
  <para>(t)csh:
  <command>setenv CLUSTERNAME exemple_slony</command></para>
</listitem>
</itemizedlist>
</para>

<para><warning><para> Si vous changez vos variables afin d'utiliser différents hÎtes 
      pour <envar>MASTERHOST</envar> et <envar>SLAVEHOST</envar>, soyez certain de 
<emphasis>ne pas</emphasis> utiliser localhost pour aucun des deux. Ceci provoquerait
une erreur similaire à celle-ci :</para>

<para><command>
ERROR  remoteListenThread_1: db_getLocalNodeId() returned 2 - wrong database?
</command></para>
</warning></para>


<sect2><title>Créer l'utilisateur <application>pgbench</application></title>

<para><command>
createuser -A -D $PGBENCHUSER
</command>
</para>
</sect2>
<sect2><title>Préparer les bases</title>

<programlisting>
createdb -O $PGBENCHUSER -h $MASTERHOST $MASTERDBNAME
createdb -O $PGBENCHUSER -h $SLAVEHOST $SLAVEDBNAME
pgbench -i -s 1 -U $PGBENCHUSER -h $MASTERHOST $MASTERDBNAME
</programlisting>

<para> Une des tables crées par <application>pgbench</application>, <envar>history</envar>,
  n'a pas de clé primaire. Dans les versions antérieurs de &slony1;, un commande
  &slonik; nommée  <xref linkend="stmttableaddkey"/> pouvait être utilisées pour
  en introduire une. Ceci provoquait de nombreux problÚmes si bien que cette 
  fonctionnalités fut supprimée dans la version 2 &slony1;. Il est désormais 
<emphasis>nécessaires</emphasis> d'avoir une ensemble éligible en tant que 
 clé primaire. </para>

<para> Les requêtes SQL suivantes établissent une clé primaire cohérente pour cette table.: </para>

<programlisting>
psql -U $PGBENCH_USER -h $HOST1 -d $DBNAME1 -c "begin; alter table
history add column id serial; update history set id =
nextval('history_id_seq'); alter table history add primary key(id);
commit"
</programlisting>

<para>Puisque &slony1; dépend de la présence du langage procédural pl/pgSQL
, nous devons l'installer maintenant. Il est possible que vous ayez installé 
pl/pgSQL dans la base template1, auquel cas vous pouvez sauter cette étape
car le langage est installé par défaut dans la base  <envar>$MASTERDBNAME</envar>.

<programlisting>
createlang -h $MASTERHOST plpgsql $MASTERDBNAME
</programlisting>
</para>

<para>&slony1; ne copie pas automatiquement les définitions de tables 
  du maître lorsqu'un esclave s'y connecte à lui, ainsi nous devons importer
  ces données. Nous réalisons cette opération avec <application>pg_dump</application>.

<programlisting>
pg_dump -s -U $REPLICATIONUSER -h $MASTERHOST $MASTERDBNAME | psql -U $REPLICATIONUSER -h $SLAVEHOST $SLAVEDBNAME
</programlisting>
</para>

<para>Pour illustrer comment &slony1; permet une réplication à la volée, 
  nous lançons l'application <application>pgbench</application>. 
  Si vous exécutez <application>pgbench</application> en tache de premier plan
  dans une fenêtre de terminal séparée, vous pouvez l'arrêter et la relancer 
  à tout moment avec des paramÚtres différents. Vous devrez exporter les 
  variables d'environnement pour qu'elles soient également disponibles dans cette session.
</para>

<para>La commande habituelle pour exécuter <application>pgbench</application> est :

<programlisting>
pgbench -s 1 -c 5 -t 1000 -U $PGBENCHUSER -h $MASTERHOST $MASTERDBNAME
</programlisting>
</para>

<para>Ceci lancera <application>pgbench</application> avec 5 clients concurrents,
  exécutant chacun 1000 transactions sur la base <application>pgbench</application>
  hébergées sur localhost, en utilisant l'utilisateur pgbench.
</para></sect2>

<sect2><title>Configurer la base de donnée pour la réplication.</title>

<para>La création des tables de configuration, des procédures stockées, des triggers,
  et la configuration sont prises en charges par l'outil <xref linkend="slonik"/>. 
  Il s'agit d'un script d'aide spécialisé, qui appelle principalement des procédures stockées
  sur les noeuds maître et esclaves.</para>

<sect3><title>Utiliser les scripts altperl</title>

<indexterm><primary> Utilisation des scripts altperl</primary></indexterm>

<para>
L'utilisation des scripts <xref linkend="altperl"/> est une façon simple de 
faire ses premiers pas.  Le script <command>slonik_build_env</command> 
génÚre une sortie fournissant les détails nécessaires à la construction 
complÚte d'un fichier <filename>rslon_tools.conf</filename>.
Un exemple de fichier <filename>slon_tools.conf</filename> est fournit dans la distribution
afin d'aider à la prise en main. Les script altperl font tous référence à ce 
fichier central de configuration afin de simplifier l'administration. 
Une fois le fichier slon_tools.conf créé, vous pouvez poursuivre comme ceci :
</para>

<programlisting>
# Initialisation du cluster:
$ slonik_init_cluster  | slonik 

# Démarrage de slon  (ici 1 et 2 sont les numéros de noeuds)
$ slon_start 1    
$ slon_start 2

# Création des ensemble (ici 1 est le numéro de l'ensemble)
$ slonik_create_set 1             

# Abonner l'ensemble dans le second noeud (1= n° d'ensemble, 2= n° de noeud)
$ slonik_subscribe_set  1 2 | slonik
</programlisting>

<para> Vous avez répliqué votre premiÚre base de données. 
  Vous pouvez sauter la section suivante de la documentation 
  si vous le souhaitez, car il s'agit d'une approche plus 
   <quote>rustre</quote>.</para>
</sect3>

<sect3><title>Utiliser directement les commandes slonik</title>

<para>L'approche traditionnelle pour administrer slony consiste à utiliser directement 
  les commandes slonik. En voici un exemple  </para>

<para> Le script de création de la configuration initiale 
  pour une simple configuration maître-esclave de la base
  <application>pgbench</application> est le suivant :</para>

<programlisting><![CDATA[
#!/bin/sh

slonik <<_EOF_
        #--
        # défintion de l'espace de nom du systÚme de réplication
        # dans notre exemple il s'agit de exemple_slony
        #--
        cluster name = $CLUSTERNAME;

        #--
        # les paramÚtres "admin conninfo" sont utilisé par slonik pour se connecter
        # aux noeuds. Une ligne par noeud. La syntaxe est celle de PQconnectdb dans la 
        # C-API
        # --
        node 1 admin conninfo = 'dbname=$MASTERDBNAME host=$MASTERHOST user=$REPLICATIONUSER';
        node 2 admin conninfo = 'dbname=$SLAVEDBNAME host=$SLAVEHOST user=$REPLICATIONUSER';

        #--
        # initialisation du premier noeud. Son identifiant DOIT être 1.  Cela provoque la création
        # du schema _$CLUSTERNAME contenant tous les objets spécifiques du systÚme
        # de réplication
        #--
        init cluster ( id=1, comment = 'Master Node');
 
        #--
        # Puisque la table history n'a pas de clé primaire, ni de contrainte unique
        # qui pourrait être utilisée pour identifier une ligne, nous devons en ajouter
        # une.
        # La commande suivante ajoute à la table une colonne bigint nommée 
        # _Slony-I_$CLUSTERNAME_rowID. Elle comme valeur par défaut 
        # nextval('_$CLUSTERNAME.s1_rowid_seq'), et dispose des contraintes
        # UNIQUE et NOT NULL. Toutes les lignes existantes seront initialisées
        # avec un dentifiant.
        #--
        table add key (node id = 1, fully qualified name = 'public.history');

        #--
        # Slony-I regroupe les tables dans des ensembles.
        # La plus petite unité qu'un noeud peut répliquer est un ensemble 
        # Les commandes suivantes créée un ensemble contenant 4 tables pgbench.
        # Le maître (ou origine) de l'ensemble est le noeud 1.
        #--
        create set (id=1, origin=1, comment='All pgbench tables');
        set add table (set id=1, origin=1, id=1, fully qualified name = 'public.accounts', comment='accounts table');
        set add table (set id=1, origin=1, id=2, fully qualified name = 'public.branches', comment='branches table');
        set add table (set id=1, origin=1, id=3, fully qualified name = 'public.tellers', comment='tellers table');
        set add table (set id=1, origin=1, id=4, fully qualified name = 'public.history', comment='history table');

        #--
        # Création du second noeud (l'esclave) 
        # décrit comment les 2 noeuds vont se connecter l'un à l'autre
        # et quelle maniÚre ils vont écouter les événements..
        #--
        store node (id=2, comment = 'Slave node');
        store path (server = 1, client = 2, conninfo='dbname=$MASTERDBNAME host=$MASTERHOST user=$REPLICATIONUSER');
        store path (server = 2, client = 1, conninfo='dbname=$SLAVEDBNAME host=$SLAVEHOST user=$REPLICATIONUSER');
_EOF_
]]></programlisting>

<para>L'application <application>pgbench</application> est-elle toujours exécutée ?
  Si ce n'est pas le cas, redémarrez-la.
</para>

<para>A ce moment, nous avons 2 bases de données qui sont complÚtement préparées.
  Une d'elle est la base maître, celle que l'application <application>pgbench</application>
  utilise pour lire et modifier des lignes. Le temps est donc venu de lancer les 
  démons de réplication.</para>

<para>Sur $MASTERHOST, la commande pour démarrer le moteur de réplication est :

<programlisting>
slon $CLUSTERNAME "dbname=$MASTERDBNAME user=$REPLICATIONUSER host=$MASTERHOST"
</programlisting>
</para>
<para>De la même façon, nous démarrons le systÚme de réplication sur le noeud 2 (l'esclave)

<programlisting>
slon $CLUSTERNAME "dbname=$SLAVEDBNAME user=$REPLICATIONUSER host=$SLAVEHOST"
</programlisting>
</para>
<para>Même si nous avons désormais le démon <xref linkend="slon"/> exécuté sur
  à la fois sur le maître et l'esclave, et qu'ils sont tous les deux en train de
  cracher des diagnostiques et d'autres messages, les données ne sommes toujours 
  pas répliquées. L'activité que vous constatez est la synchronisation de la
  configuration du cluster entre les 2 processus <xref linkend="slon"/>.
  </para>

<para>Pour démarrer la réplication des 4 tables <application>pgbench</application>
 (l'ensemble 1) depuis le maître (le noeud 1) vers l'esclave (le noeud 2),
 lancez le script suivant :

<programlisting><![CDATA[
#!/bin/sh
slonik <<_EOF_
         # ----
         # Définition de l'espace de nom du cluster
         # ----
         cluster name = $CLUSTERNAME;

         # ----
         # Les paramÚtres conninfo sont utilisés par le programme slonik
         # pour se connecter aux noeuds. Ce sont donc les arguments 
         # PQconnectdb pour se connecter depuis la station de travail
         # d'administration (où les scripts slonik sont exécutés).
         # ----
         node 1 admin conninfo = 'dbname=$MASTERDBNAME host=$MASTERHOST user=$REPLICATIONUSER';
         node 2 admin conninfo = 'dbname=$SLAVEDBNAME host=$SLAVEHOST user=$REPLICATIONUSER';

         # ----
         # Le noeud 2 s'abonne à l'ensemble 1
         # ----
         subscribe set ( id = 1, provider = 1, receiver = 2, forward = no);
_EOF_
]]></programlisting>
</para>

<para>Désormais, le démon de réplication sur<envar>$SLAVEHOST</envar>  se déclenchera à tout moment
  pour copier les changements d'états sur les 4 tables répliquées.
  Pendant ce temps, l'application <application>pgbench</application> 
  va continuer à modifier la base de données.
  Lorsque le processus de copie est terminée, le démon de réplication sur le noeud
  <envar>$SLAVEHOST</envar> commencera à se synchroniser en appliquant les journaux 
  de réplications qui auront été accumulés.
  Cela se fera par petit à petit, par tranches de 10 secondes de travail applicatifs.
  Selon les performances des 2 systÚmes impliqués, la taille des deux bases de données,
  la charge de transaction et la qualité de l'optimisation et de la maintenance effectuées
  sur les deux bases de données, ce processus de synchronisation peut durer quelques 
  minutes, quelques heures ou quelques siÚcles.</para>

<para>Vous avez maintenant configuré avec un succÚs votre premier systÚme de  réplication 
  maître-esclave basique, et les deux bases de données devraient, une fois que l'esclave
  sera synchronisé, contenir des données identiques. Ça c'est la théorie, tout du moins. 
  En pratique, il est bon de vérifier que les ensembles de données sont bien identiques. 
  </para>

<para>Le script ci-dessous crée des sauvegardes ordonnées des deux bases et les 
  compares. Assurez-vous que le test <application>pgbench</application> est terminé, 
  qu'il n'y pas d'autres mises à jour en cours sur le noeud origine, et que les sessions
  slons se sont synchronisées.</para>

<programlisting><![CDATA[
#!/bin/sh
echo -n "**** comparing sample1 ... "
psql -U $REPLICATIONUSER -h $MASTERHOST $MASTERDBNAME >dump.tmp.1.$$ <<_EOF_
         select 'accounts:'::text, aid, bid, abalance, filler
                  from accounts order by aid;
         select 'branches:'::text, bid, bbalance, filler
                  from branches order by bid;
         select 'tellers:'::text, tid, bid, tbalance, filler
                  from tellers order by tid;
         select 'history:'::text, tid, bid, aid, delta, mtime, filler,
                  "_Slony-I_${CLUSTERNAME}_rowID"
                  from history order by "_Slony-I_${CLUSTERNAME}_rowID";
_EOF_
psql -U $REPLICATIONUSER -h $SLAVEHOST $SLAVEDBNAME >dump.tmp.2.$$ <<_EOF_
         select 'accounts:'::text, aid, bid, abalance, filler
                  from accounts order by aid;
         select 'branches:'::text, bid, bbalance, filler
                  from branches order by bid;
         select 'tellers:'::text, tid, bid, tbalance, filler
                  from tellers order by tid;
         select 'history:'::text, tid, bid, aid, delta, mtime, filler,
                  "_Slony-I_${CLUSTERNAME}_rowID"
                  from history order by "_Slony-I_${CLUSTERNAME}_rowID";
_EOF_

if diff dump.tmp.1.$$ dump.tmp.2.$$ >$CLUSTERNAME.diff ; then
         echo "success - databases are equal."
         rm dump.tmp.?.$$
         rm $CLUSTERNAME.diff
else
         echo "FAILED - see $CLUSTERNAME.diff for database differences"
fi
]]></programlisting>

<para>Notez qu'il existe une documentation un peu plus sophistiquée
  concernant ce processus dans l'arborescence du code source de  
  &slony1; au sein d'un fichier nommé <filename>slony-I-basic-mstr-slv.txt</filename>.</para>

<para>Si ce script retourne <command>FAILED</command>, merci de contacter les développeurs sur 
<ulink url="http://slony.info/">http://slony.info/</ulink></para></sect3>
</sect2>
</sect1>