root/traduc/trunk/postgresql/dblink.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<sect1 id="dblink">
 <title>dblink</title>

 <indexterm zone="dblink">
  <primary>dblink</primary>
 </indexterm>

 <para>
  <filename>dblink</filename> est un module qui permet de se connecter à
  d'autres bases de données <productname>PostgreSQL</productname> depuis
  une session de base de données.
 </para>

 <refentry id="CONTRIB-DBLINK-CONNECT">
  <refnamediv>
   <refname>dblink_connect</refname>
   <refpurpose>ouvre une connexion persistante vers une base de données
    distante.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_connect(text connstr) returns text
    dblink_connect(text connname, text connstr) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_connect()</function> établit une connexion à une
    base de données <productname>PostgreSQL</productname> distante. Le
    serveur et la base de données à contacter sont identifiées par
    une chaine de connexion standard de la
    <application>libpq</application>. Il est possible d'affecter un nom
    à la connexion. Plusieurs connexions nommées peuvent être ouvertes 
    en une seule fois, mais il ne peut y avoir qu'une seule connexion
    anonyme à la fois. Toute connexion est maintenue jusqu'à ce qu'elle
    soit close ou que la session de base de données soit terminée.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom à utiliser pour la connexion&nbsp;; en cas d'omission,
       une connexion sans nom est ouverte, qui remplace toute autre connexion
       sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>connstr</parameter></term>
     <listitem>
      <para>
       Chaîne de connexion au format standard de la
       <application>libpq</application>, par exemple
       <literal>hostaddr=127.0.0.1 port=5432 dbname=mabase user=postgres
       password=monmotdepasse</literal>.
       Pour les détails, voir <function>PQconnectdb</function> dans
       <xref linkend="libpq-connect"/>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie le statut qui est toujours <literal>OK</literal> (puisque toute
    erreur amène la fonction à lever une erreur, sans retour).
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    Seuls les super-utilisateurs peuvent utiliser
    <function>dblink_connect</function> pour créer des connexions authentifiées
    sans mot de passe. Si des utilisateurs standard ont ce besoin, il faut
    utiliser la fonction <function>dblink_connect_u</function> à sa place.
   </para>

   <para>
    Il est déconseillé de choisir des noms de connexion contenant
    des signes d'égalité car ils peuvent introduire des risques de confusion
    avec les chaînes de connexion dans les autres fonctions
    <filename>dblink</filename>.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)

 select dblink_connect('myconn', 'dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-CONNECT-U">
  <refnamediv>
   <refname>dblink_connect_u</refname>
   <refpurpose>ouvre une connexion distante à une base de données de
    façon non sécurisée.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_connect_u(text connstr) returns text
    dblink_connect_u(text connname, text connstr) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_connect_u()</function> est identique à
    <function>dblink_connect()</function>, à ceci près qu'elle permet à des
    utilisateurs non-privilégiés de se connecter par toute méthode
    d'authentification.
   </para>

   <para>
    Si le serveur distant sélectionne une méthode d'authentification qui
    n'implique pas de mot de passe, une impersonnalisation et une escalade
    de droits peut survenir car la session semble émaner de l'utilisateur
    qui exécute le serveur <productname>PostgreSQL</productname> local.
    C'est pourquoi,
    <function>dblink_connect_u()</function> est installé initialement sans
    aucun droit pour <literal>PUBLIC</literal>, ce qui restreint son
    utilisation aux seuls super-utilisateurs. Dans certaines cas,
    le droit <literal>EXECUTE</literal> sur
    <function>dblink_connect_u()</function> peut être accordé à quelque utilisateur
    spécifique digne de confiance, mais cela doit se faire
    avec une extrême prudence.
   </para>

   <para>
    Pour plus de détails, voir <function>dblink_connect()</function>.
   </para>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-DISCONNECT">
  <refnamediv>
   <refname>dblink_disconnect</refname>
   <refpurpose>ferme une connexion persistante vers une base de données
    distante.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_disconnect() returns text
    dblink_disconnect(text connname) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_disconnect()</function> ferme une connexion ouverte
    par <function>dblink_connect()</function>. La forme sans argument
    ferme une connexion non nommée.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à fermer
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie le statut qui est toujours <literal>OK</literal> (puisque toute
    erreur amène la fonction à lever une erreur, sans retour).
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 select dblink_disconnect();
  dblink_disconnect
 -------------------
  OK
 (1 row)

 select dblink_disconnect('myconn');
  dblink_disconnect
 -------------------
  OK
 (1 row)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK">
  <refnamediv>
   <refname>dblink</refname>
   <refpurpose>exécute une requête sur une base de données
   distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink(text connname, text sql [, bool fail_on_error]) returns setof record
    dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
    dblink(text sql [, bool fail_on_error]) returns setof record
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink</function> exécute une requête (habituellement un
    <command>SELECT</command>, mais toute instruction
    SQL qui renvoie des lignes est valable) sur une base de données distante.
   </para>

   <para>
    Si deux arguments <type>text</type> sont présents, le premier est d'abord
    considéré comme nom de connexion persistante&nbsp;; si cette connexion
    est trouvée, la commande est exécutée sur cette connexion. Dans le cas
    contraire, le premier argument est considéré être une chaîne de connexion
    comme dans le cas de <function>dblink_connect</function>, et la connexion
    indiquée n'est conservée que pour la durée d'exécution de cette commande.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser&nbsp;; ce paramètre doit être omis
       pour utiliser une connexion sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>connstr</parameter></term>
     <listitem>
      <para>
       Une chaîne de connexion similaire à celle décrite précédemment pour
       <function>dblink_connect</function>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>sql</parameter></term>
     <listitem>
      <para>
        L'instruction SQL à exécuter sur l'hôte distant, par exemple
        <literal>select * from foo</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       Si true (valeur par défaut en cas d'omission), une erreur distante
       est reportée localement comme une erreur. Dans le cas contraire, un
       message d'erreur distant est traité localement comme un message de type 
       NOTICE, et la fonction ne retourne aucune ligne.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    La fonction renvoie les lignes produites par la requête. Comme
    <function>dblink</function> peut être utilisée avec toute requête, elle
    est déclarée comme renvoyant le type <type>record</type>, plutôt que de
    préciser un ensemble particulier de colonnes. Cela signifie que
    l'ensemble des colonnes attendues doit être précisé dans la
    requête appelante &mdash; sinon <productname>PostgreSQL</productname>
    ne sait pas quoi attendre. Voici un exemple&nbsp;:

<programlisting>
SELECT *
    FROM dblink('dbname=mydb', 'select proname, prosrc from pg_proc')
      AS t1(proname name, prosrc text)
    WHERE proname LIKE 'bytea%';
</programlisting>

    La partie <quote>alias</quote> de la clause <literal>FROM</literal> doit
    spécifier les noms et types des colonnes retournés par la fonction.
    (La précision des noms des colonnes dans un alias est une syntaxe
    du standard SQL mais la précision des types des colonnes est une extension
    <productname>PostgreSQL</productname>.) Cela permet au système de
    savoir comment étendre <literal>*</literal>, et à quoi correspond
    <structname>proname</structname> dans la clause
    <literal>WHERE</literal> 
    avant de tenter l'exécution de la fonction. À l'exécution, une erreur
    est renvoyée si le nombre de colonnes du résultat effectif de la requête
    sur la base de données distante diffère de celui indiqué
    dans la clause <literal>FROM</literal>. Les noms de colonnes n'ont pas
    besoin de correspondre et <function>dblink</function> n'impose pas
    une correspondance exacte des types. L'opération réussit
    si les chaînes de données renvoyées sont valides pour le type déclaré
    dans la clause <literal>FROM</literal>.
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    <function>dblink</function> récupère l'intégralité des résultats de la
    requête avant de les renvoyer au système local. Si la requête doit
    renvoyer un grand nombre de lignes, il est préférable d'ouvrir un
    curseur avec <function>dblink_open</function> puis de récupérer un
    nombre gérable de lignes.
   </para>

   <para>
    Il est souvent plus pratique de créer une vue pour utiliser
    <function>dblink</function> avec des requêtes prédéterminées.
    Cela permet de laisser la vue gérer le type de la colonne plutôt que
    d'avoir à le saisir pour chaque requête. Par exemple&nbsp;:

    <programlisting>
CREATE VIEW myremote_pg_proc AS
  SELECT *
    FROM dblink('dbname=postgres', 'SELECT proname, prosrc FROM pg_proc')
    AS t1(proname name, prosrc text);

SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%';
    </programlisting>
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
SELECT * FROM dblink('dbname=postgres', 'SELECT proname, prosrc FROM pg_proc')
  AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
   proname   |   prosrc
 ------------+------------
  byteacat   | byteacat
  byteaeq    | byteaeq
  bytealt    | bytealt
  byteale    | byteale
  byteagt    | byteagt
  byteage    | byteage
  byteane    | byteane
  byteacmp   | byteacmp
  bytealike  | bytealike
  byteanlike | byteanlike
  byteain    | byteain
  byteaout   | byteaout
 (12 rows)

SELECT dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)

SELECT * FROM dblink('SELECT proname, prosrc FROM pg_proc')
  AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
   proname   |   prosrc
 ------------+------------
  byteacat   | byteacat
  byteaeq    | byteaeq
  bytealt    | bytealt
  byteale    | byteale
  byteagt    | byteagt
  byteage    | byteage
  byteane    | byteane
  byteacmp   | byteacmp
  bytealike  | bytealike
  byteanlike | byteanlike
  byteain    | byteain
  byteaout   | byteaout
 (12 rows)

 SELECT dblink_connect('myconn', 'dbname=regression');
  dblink_connect
 ----------------
  OK
 (1 row)

 SELECT * FROM dblink('myconn', 'SELECT proname, prosrc FROM pg_proc')
  AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
   proname   |   prosrc
 ------------+------------
  bytearecv  | bytearecv
  byteasend  | byteasend
  byteale    | byteale
  byteagt    | byteagt
  byteage    | byteage
  byteane    | byteane
  byteacmp   | byteacmp
  bytealike  | bytealike
  byteanlike | byteanlike
  byteacat   | byteacat
  byteaeq    | byteaeq
  bytealt    | bytealt
  byteain    | byteain
  byteaout   | byteaout
 (14 rows)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-EXEC">
  <refnamediv>
   <refname>dblink_exec</refname>
   <refpurpose>exécute une commande sur une base de données
    distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
    dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
    dblink_exec(text sql [, bool fail_on_error]) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_exec</function> exécute une commande (c'est-à-dire toute
    instruction SQL qui ne renvoie pas de lignes) dans une base de données
    distante.
   </para>

   <para>
    Quand deux arguments de type <type>text</type> sont fournis, le premier
    est d'abord considéré comme nom d'une connexion persistante&nbsp;; si cette
    connexion est trouvée, la commande est exécutée sur cette connexion. Dans
    le cas contraire, le premier argument est traitée comme une chaîne de
    connexion pour <function>dblink_connect</function>, et la connexion
    indiquée n'est maintenue que pour la durée d'exécution de cette
    commande.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser&nbsp;; ce paramètre doit être omis 
       pour utiliser une connexion sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>connstr</parameter></term>
     <listitem>
      <para>
        Une chaîne de connexion similaire à celle décrite précédemment pour
        <function>dblink_connect</function>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>sql</parameter></term>
     <listitem>
      <para>
       La commande SQL à exécuter sur la base de données
       distante&nbsp;; par exemple
       <literal>INSERT INTO foo VALUES(0,'a','{"a0","b0","c0"}')</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       Si true (valeur par défaut en cas d'omission), une erreur distante
       est reportée localement comme une erreur locale. Dans le cas contraire, un
       message d'erreur distant est traité localement comme un message de type 
       NOTICE, et la valeur de retour de la fonction est positionné à
       <literal>ERROR</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie le statut de la commande ou <literal>ERROR</literal> en cas
    d'échec.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 SELECT dblink_connect('dbname=dblink_test_slave');
  dblink_connect
 ----------------
  OK
 (1 row)

 SELECT dblink_exec('INSERT INTO foo VALUES(21,''z'',''{"a0","b0","c0"}'');');
    dblink_exec
 -----------------
  INSERT 943366 1
 (1 row)

 SELECT dblink_connect('myconn', 'dbname=regression');
  dblink_connect
 ----------------
  OK
 (1 row)

 SELECT dblink_exec('myconn', 'INSERT INTO foo VALUES(21,''z'',''{"a0","b0","c0"}'');');
    dblink_exec
 ------------------
  INSERT 6432584 1
 (1 row)

 SELECT dblink_exec('myconn', 'INSERT INTO pg_class values (''foo'')',false);
 NOTICE:  sql error
 DETAIL:  ERROR:  null value in column "relnamespace" violates not-null constraint

  dblink_exec
 -------------
  ERROR
 (1 row)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-OPEN">
  <refnamediv>
   <refname>dblink_open</refname>
   <refpurpose>ouvre un curseur sur une base de données distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text
    dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_open()</function> ouvre un curseur sur une base de
    données distante. Le curseur peut ensuite être manipulé avec
    <function>dblink_fetch()</function> et
    <function>dblink_close()</function>.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser&nbsp;; ce paramètre doit être omis 
       pour utiliser une connexion sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>cursorname</parameter></term>
     <listitem>
      <para>
       Nom à affecter au curseur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>sql</parameter></term>
     <listitem>
      <para>
       L'instruction <command>SELECT</command> à exécuter sur l'hôte distant,
       par exemple <literal>SELECT * FROM pg_class</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       Si true (valeur par défaut en cas d'omission), une erreur distante
       est reportée localement comme une erreur locale. Dans le cas contraire, un
       message d'erreur distant est traité localement comme un message de type 
       NOTICE, et la valeur de retour de la fonction est positionné à
       <literal>ERROR</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie le statut, soit <literal>OK</literal> soit
    <literal>ERROR</literal>.
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    Puisqu'un curseur ne peut persister qu'au sein d'une transaction,
    <function>dblink_open</function> lance un bloc de transaction explicite
    (<command>BEGIN</command>) côté distant, si le côté distant n'est
    pas déjà à l'intérieur d'une transaction. Cette transaction est refermée
    à l'exécution de l'instruction <function>dblink_close</function>.
    Si <function>dblink_exec</function> est utilisée
    pour modifier les données entre <function>dblink_open</function> et
    <function>dblink_close</function>, et qu'une erreur survient ou
    que <function>dblink_disconnect</function> est utilisé avant
    <function>dblink_close</function>, les modifications <emphasis>sont
    perdues</emphasis> car la transaction est annulée.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 SELECT dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)

 SELECT dblink_open('foo', 'SELECT proname, prosrc FROM pg_proc');
  dblink_open
 -------------
  OK
 (1 row)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-FETCH">
  <refnamediv>
   <refname>dblink_fetch</refname>
   <refpurpose>renvoie des lignes à partir d'un curseur ouvert sur une
    base de données distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
    dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_fetch</function> récupère des lignes à partir d'un
    curseur déjà ouvert par <function>dblink_open</function>.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Nom de la connexion à utiliser&nbsp;; ce paramètre doit être omis pour
       utiliser une connexion sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>cursorname</parameter></term>
     <listitem>
      <para>
       Le nom du curseur à partir duquel récupérer les lignes.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>howmany</parameter></term>
     <listitem>
      <para>
       Nombre maximum de lignes à récupérer. Les
       <parameter>howmany</parameter> lignes suivantes sont récupérées, en
       commençant à la position actuelle du curseur, vers l'avant. Une fois
       le curseur arrivé à la fin, aucune ligne supplémentaire n'est
       renvoyée.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       Si true (valeur par défaut en cas d'omission), une erreur distante
       est reportée localement comme une erreur locale. Dans le cas contraire, un
       message d'erreur distant est traité localement comme un message de type 
       NOTICE, et la fonction ne retourne aucune ligne.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    La fonction renvoie les lignes récupérées à partir du curseur. Pour
    utiliser cette fonction, l'ensemble des colonnes 
    attendues doit être spécifié, comme décrit précédemment pour
    <function>dblink</function>. 
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    Si le nombre de colonnes de retour spécifiées dans
    la clause <literal>FROM</literal>, et le nombre réel de colonnes renvoyées
    par le curseur distant diffèrent, une erreur est remontée. Dans ce cas, le curseur
    distant est tout de même avancé du nombre de lignes indiqué, comme si
    l'erreur n'avait pas eu lieu. Il en est de même pour toute autre erreur
    survenant dans la requête locale après l'exécution
    du <command>FETCH</command> distant.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)

 SELECT dblink_open('foo', 'SELECT proname, prosrc FROM pg_proc WHERE proname LIKE ''bytea%''');
  dblink_open
 -------------
  OK
 (1 row)

 SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
  funcname |  source
 ----------+----------
  byteacat | byteacat
  byteacmp | byteacmp
  byteaeq  | byteaeq
  byteage  | byteage
  byteagt  | byteagt
 (5 rows)

 SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
  funcname  |  source
 -----------+-----------
  byteain   | byteain
  byteale   | byteale
  bytealike | bytealike
  bytealt   | bytealt
  byteane   | byteane
 (5 rows)

 SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
   funcname  |   source
 ------------+------------
  byteanlike | byteanlike
  byteaout   | byteaout
 (2 rows)

 SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
  funcname | source
 ----------+--------
 (0 rows)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-CLOSE">
  <refnamediv>
   <refname>dblink_close</refname>
   <refpurpose>ferme un curseur sur une base de données distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_close(text cursorname [, bool fail_on_error]) returns text
    dblink_close(text connname, text cursorname [, bool fail_on_error]) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_close</function> ferme un curseur précédemment ouvert
    avec <function>dblink_open</function>.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser&nbsp;; ce paramètre doit être omis pour
       utiliser une connexion sans nom.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>cursorname</parameter></term>
     <listitem>
      <para>
       Nom du curseur à fermer.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       Si true (valeur par défaut en cas d'omission), une erreur distante
       est reportée localement comme une erreur. Dans le cas contraire, un
       message d'erreur distant est traité localement comme un message de type 
       NOTICE, et la valeur de retour est positionnée à 
       <literal>ERROR</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie le statut, soit <literal>OK</literal> soit
    <literal>ERROR</literal>.
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    Si <function>dblink_open</function> a ouvert un bloc de transaction
    explicite, et que c'est le dernier curseur ouvert restant dans cette
    connexion, <function>dblink_close</function> exécute le
    <command>COMMIT</command> correspondant.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
 select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)

 select dblink_open('foo', 'select proname, prosrc from pg_proc');
  dblink_open
 -------------
  OK
 (1 row)

 select dblink_close('foo');
  dblink_close
 --------------
  OK
 (1 row)
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-GET-CONNECTIONS">
  <refnamediv>
   <refname>dblink_get_connections</refname>
   <refpurpose>renvoie les noms de toutes les connexions nommées
   ouvertes</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_get_connections() returns text[]
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_get_connections</function> renvoie un tableau contenant
    le nom de toutes les connexions nommées ouvertes de
    <filename>dblink</filename>.
   </para>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>Renvoie un tableau texte des noms des connexions, ou NULL s'il n'y
   en a pas.</para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
   SELECT dblink_get_connections();
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-ERROR-MESSAGE">
  <refnamediv>
   <refname>dblink_error_message</refname>
   <refpurpose>récupère le dernier message d'erreur sur la connexion
    nommée</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_error_message(text connname) returns text
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_error_message</function> récupère le dernier message
    d'erreur sur une connexion donnée.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Nom de la connexion à utiliser.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Return Value</title>

   <para>
    Renvoie le dernier message, ou une chaîne vide s'il n'y a pas eu
    d'erreur sur cette connexion.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
    SELECT dblink_error_message('dtest1');
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-SEND-QUERY">
  <refnamediv>
   <refname>dblink_send_query</refname>
   <refpurpose>envoie une requête asynchrone à une base de données
    distante</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_send_query(text connname, text sql) returns int
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_send_query</function> envoie une requête à exécuter
    de façon asynchrone, c'est-à-dire sans attendre immédiatement le résultat.
    Il ne doit pas déjà exister de requête asynchrone en exécution sur la
    connexion.
   </para>

   <para>
    Après l'envoi réussi d'une requête asynchrone, le statut de fin
    d'exécution de la requête se vérifie avec
    <function>dblink_is_busy</function>, et les résultats sont finalement
    récupérés avec <function>dblink_get_result</function>. Il est
    aussi possible de tenter l'annulation d'une rquête asynchrone
    active en utilisant  <function>dblink_cancel_query</function>. 
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>sql</parameter></term>
     <listitem>
      <para>
       L'instruction SQL à exécuter dans la base de données
       distante, par exemple <literal>select * from pg_class</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie 1 si la requête a été envoyée avec succès, 0 sinon.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
    SELECT dblink_send_query('dtest1', 'SELECT * FROM foo WHERE f1 &lt; 3');
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-IS-BUSY">
  <refnamediv>
   <refname>dblink_is_busy</refname>
   <refpurpose>vérifie si la connexion est occupée par le traitement d'une requête
   asynchrone</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_is_busy(text connname) returns int
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_is_busy</function> teste si une requête asynchrone est
    en cours d'exécution.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à vérifier.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Valeur de retour</title>

   <para>
    Renvoie 1 si la connexion est occupée, 0 dans le cas contraire.
    Si cette fonction renvoie 0, il est garanti que l'appel à
    <function>dblink_get_result</function> ne bloque pas.
   </para>
  </refsect1>

  <refsect1>
   <title>Exemple</title>

   <programlisting>
    SELECT dblink_is_busy('dtest1');
   </programlisting>
  </refsect1>
 </refentry>

 <refentry id="CONTRIB-DBLINK-GET-RESULT">
  <refnamediv>
   <refname>dblink_get_result</refname>
   <refpurpose>récupère le résultat d'une requête asynchrone</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
   <synopsis>
    dblink_get_result(text connname [, bool fail_on_error]) returns setof record
   </synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_get_result</function> récupère le résultat d'une
    requête asynchrone précédemment envoyée avec
    <function>dblink_send_query</function>. Si la requête n'est pas 
    terminée, <function>dblink_get_result</function> en attend la fin.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>conname</parameter></term>
     <listitem>
      <para>
       Le nom de la connexion à utiliser.