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ées
  <application>pgbench</application> neuve. Les mécanismes de réplications
  d'une base existante sont abordés 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 un outil de
  <quote>tests</quote> («&nbsp;benchmark&nbsp;») 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&nbsp;; vous pouvez par
  ailleurs le trouver inclus dans les paquets binaires de  &postgres;.
</para>

<para>
  Le moteur de réplication de &slony1; est basé sur les triggers, ce qui permet
  de 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ée 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;&nbsp;:

  <itemizedlist>
    <listitem>
      <para>
        Vous avez la ligne <option>tcpip_socket=true</option> dans votre
        <filename>postgresql.conf</filename>.
      </para>
      
      <note>
        <para>
	  Ce n'est plus nécessaire pour les versions &postgres; 8.0 et
	  ultérieures.
	</para>
      </note>
    </listitem>

    <listitem>
      <para>
        Vous avez activé 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&nbsp;:

  <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&nbsp;:

  <itemizedlist>
    <listitem>
      <para>
        bash, sh, ksh&nbsp;:
        <command>export CLUSTERNAME=exemple_slony</command>
      </para>
    </listitem>
    
    <listitem>
      <para>
        (t)csh&nbsp;:
        <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&nbsp;:
    </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érieures de &slony1;, une 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é fut
  supprimée dans la version 2 de &slony1;. Il est désormais
  <emphasis>nécessaire</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&nbsp;:
</para>

<programlisting>psql -U $PGBENCHUSER -h $HOST1 -d $MASTERDBNAME -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, 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 tâche de premier plan dans une fenêtre
  de terminal séparée, vous pouvez l'arrêter et le 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&nbsp;:

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

<para>
  Ceci lancera <application>pgbench</application> avec cinq 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 n&oelig;uds maître et esclaves.
</para>

<para>
  L'exemple qui suit utilise <xref linkend="slonik"/> directement (ou l'embarque
  directement dans les scripts). Ce n'est pas forcément la façon la plus
  plaisante pour débuter&nbsp;: il existe des outils pour construire les
  scripts de <xref linkend="slonik"/> dans le répertoire
  <filename>tools</filename>&nbsp;:
</para>

<itemizedlist>
  <listitem>
    <para>
      <xref linkend="altperl"/> - un ensemble de scripts Perl qui construisent
      des scripts <xref linkend="slonik"/> basés sur un seul fichier
      <filename>slon_tools.conf</filename>.
    </para>
  </listitem>
  
  <listitem>
    <para>
      <xref linkend="mkslonconf"/> - un script shell (<emphasis>c'est-à-dire</emphasis>
      qu'il fonctionne avec Bash) qui, en se basant soit sur sa configuration
      interne soit sur les variables d'environnement, génère un ensemble de
      scripts <xref linkend="slonik"/> pour configurer un cluster complet.
    </para>
  </listitem>
</itemizedlist>

<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&nbsp;:
</para>

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

slonik <<_EOF_
	#--
	# définition 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 de l'API C
	# --
	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 schéma _$CLUSTERNAME contenant tous les objets
	# spécifiques du système de réplication
	#--
	init cluster ( id=1, comment = 'Master Node');
 
	#--
	# 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ées 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', event node=1);
	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&nbsp;? Si ce n'est pas le cas, redémarrez-la.
</para>

<para>
  À ce moment, nous avons deux bases de données qui sont complètement préparées.
  L'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&nbsp;:

  <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 n&oelig;ud 2
  (l'esclave)&nbsp;:

  <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é à 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 sont toujours pas
  répliquées. L'activité que vous constatez est la synchronisation de la
  configuration du cluster entre les deux processus <xref linkend="slon"/>.
</para>

<para>
  Pour démarrer la réplication des quatre tables <application>pgbench</application>
 (l'ensemble 1) depuis le maître (le n&oelig;ud 1) vers l'esclave (le
 n&oelig;ud 2), lancez le script suivant&nbsp;:

  <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 quatre
  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é, le démon de réplication sur le
  n&oelig;ud <envar>$SLAVEHOST</envar> commencera à se synchroniser en
  appliquant les journaux de réplication qui auront été accumulés. Cela se
  fera par petit à petit, en commençant par tranches de 10 secondes de travail
  applicatifs.
  Selon les performances des deux 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>
  Si vous rencontrez des problèmes pour faire fonctionner ceci, vérifiez les
  journaux applicatifs des processus &lslon; car il y a de fortes chances que
  des messages d'erreur intéressants décrivent la nature du problème. L'outil
  &lteststate; peut aussi être utile pour diagnostiquer les problèmes avec
  des clusters de réplication pratiquement fonctionnels.
</para>

<para>
  Vous avez maintenant configuré avec 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
  compare. Assurez-vous que le test <application>pgbench</application> est
  terminé, qu'il n'y pas d'autres mises à jour en cours sur le n&oelig;ud
  origine, et que les sessions slon 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 renvoie <command>FAILED</command>, merci de contacter les
  développeurs sur <ulink url="http://slony.info/">http://slony.info/</ulink>.
  Préparez-vous aussi à fournir des informations de diagnostique, comme les
  journaux applicatifs créés par les processus &lslon; et les résultats de la
  commande &lteststate;.
</para>

</sect3>

<sect3>
<title>Utiliser les scripts altperl</title>
<indexterm><primary>exemple d'un script altperl</primary></indexterm>

<para>
  L'utilisation des scripts <xref linkend="altperl"/> est une autre façon de
  débuter&nbsp;; cela vous évite d'avoir à écrire les scripts slonik, au moins
  pour certaines des façons simples de configurer &slony1;. Le script
  <command>slonik_build_env</command> génère une sortie fournissant les détails
  dont vous avez besoin pour créer le fichier
  <filename>slon_tools.conf</filename>, dont la présence est nécessaire pour
  les scripts. Un exemple de fichier <filename>slon_tools.conf</filename> est
  fourni dans la distribution pour vous aider à commencer. Les scripts altperl
  font tous référence à ce fichier de configuration central. Une fois que
  slon_tools.conf est créé, vous pouvez continuer ainsi&nbsp;:
</para>

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

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

# Créer les ensembles (ici 1 est le numéro de l'ensemble)
$ slonik_create_set 1 | slonik             

# abonner le second noeud à l'ensemble (1= identifiant du set, 2= identifiant du noeud)
$ slonik_subscribe_set 1 2 | slonik
</programlisting>

<para>
  Vous avez maintenant répliqué votre première base de données. Vous pouvez
  ignorer la section suivante de la documentation si vous le souhaitez. Elle
  documente une approche plus complexe.
</para>

</sect3>

</sect2>

</sect1>