root/traduc/trunk/postgresql/bki.xml

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

<chapter id="bki">
 <title>Interface du moteur, <acronym>BKI</acronym></title>

 <para>
  Les fichiers d'interface du moteur (<acronym>BKI</acronym> pour
  <foreignphrase>Backend Interface</foreignphrase>) sont des scripts
  écrits dans un langage spécial, compris par le serveur
  <productname>PostgreSQL</productname> lorsqu'il est exécuté en mode
  <quote>bootstrap</quote>. Ce mode autorise la création et le remplissage des catalogues
  systèmes <foreignphrase>ab initio</foreignphrase>, là où les commandes SQL
  exigent leur existence préalable. 
  Les fichiers <acronym>BKI</acronym> peuvent donc être utilisés en premier
  lieu pour créer le système de base de données. (Ils n'ont probablement
  pas d'autre utilité.)
 </para>

 <para>
  <application>initdb</application> utilise un fichier <acronym>BKI</acronym>
  pour réaliser une partie de son travail lors de la création d'un nouveau
  cluster de bases de données. Le fichier d'entrée utilisé par
  <application>initdb</application> est créé, lors de la construction et de
  l'installation de <productname>PostgreSQL</productname>, par un programme
  nommé <filename>genbki.sh</filename> qui lit différents fichiers d'en-têtes
  C spécialement formatés à partir du répertoire
  <filename>src/include/catalog</filename> des sources. Le fichier
  <acronym>BKI</acronym> créé est appelé <filename>postgres.bki</filename> et
  est normalement installé dans le sous-répertoire <filename>share</filename>
  du répertoire d'installation.
 </para>

 <para>
  D'autres informations sont disponibles dans la documentation
  d'<application>initdb</application>.
 </para>

 <sect1 id="bki-format">
  <title>Format des fichiers <acronym>BKI</acronym></title>

  <para>
   Cette section décrit l'interprétation des fichiers <acronym>BKI</acronym>
   par le moteur de <productname>PostgreSQL</productname>. Cette description
   est plus facile à comprendre si le fichier <filename>postgres.bki</filename>
   est utilisé comme exemple.
  </para>

  <para>
   L'entrée de <acronym>BKI</acronym> représente une séquence de commandes. Les
   commandes sont constituées de lexèmes
   (<foreignphrase>tokens</foreignphrase>) dont le nombre dépend de la syntaxe de
   la commande. Les lexèmes sont habituellement séparés par des espaces
   fines, mais en l'absence d'ambiguïté ce n'est pas nécessaire. Il n'y a pas
   de séparateur spécial pour les commandes&nbsp;; le prochain lexème qui ne
   peut syntaxiquement pas appartenir à la commande qui précède en lance une
   autre. (En général, il est préférable, pour des raisons de clarté, de
   placer toute nouvelle commande sur une nouvelle ligne.) Les lexèmes peuvent être
   des mots clés, des caractères spéciaux (parenthèses, virgules, etc.), nombres ou
   chaînes de caractères entre guillemets doubles. Tous sont sensibles à la
   casse.
  </para>

  <para>
   Les lignes qui débutent par <literal>#</literal> sont ignorées.
  </para>

 </sect1>

 <sect1 id="bki-commands">
  <title>Commandes <acronym>BKI</acronym></title>

  <variablelist>
   <varlistentry>
    <term>
     <literal>create</literal>
     <optional><literal>bootstrap</literal></optional>
     <optional><literal>shared_relation</literal></optional>
     <optional><literal>without_oids</literal></optional>
     <replaceable class="parameter">tablename</replaceable>
     <replaceable class="parameter">tableoid</replaceable>
     (<replaceable class="parameter">name1</replaceable> =
     <replaceable class="parameter">type1</replaceable>
     <optional>, <replaceable class="parameter">name2</replaceable> =
     <replaceable class="parameter">type2</replaceable>, ...</optional>)
    </term>

    <listitem>
     <para>
      Crée une table nommée <replaceable class="parameter">nomtable</replaceable>,
      possédant l'OID
      <replaceable class="parameter">tableoid</replaceable> et composée des colonnes
      données entre parenthèses.
     </para>

     <para>
      Les types de colonnes suivants sont supportés directement par
      <filename>bootstrap.c</filename>: <type>bool</type>,
      <type>bytea</type>, <type>char</type> (1 byte),
      <type>name</type>, <type>int2</type>,
      <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
      <type>regtype</type>, <type>text</type>,
      <type>oid</type>, <type>tid</type>, <type>xid</type>,
      <type>cid</type>, <type>int2vector</type>, <type>oidvector</type>,
      <type>_int4</type> (array), <type>_text</type> (array),
      <type>_oid</type> (array), <type>_char</type> (array),
      <type>_aclitem</type> (array). Bien qu'il soit possible de créer des
      tables contenant des colonnes d'autres types, cela ne peut pas être
      réalisé avant que <structname>pg_type</structname> ne soit créé et
      rempli avec les entrées
      appropriées. (Ce qui signifie en fait que seuls ces types de colonnes
      peuvent être utilisés dans les tables utilisant le
      <quote>bootstrap</quote> mais que les catalogues ne l'utilisant pas
      peuvent contenir tout type interne.)
     </para>

     <para>
      Quand <literal>bootstrap</literal> est précisé, la table est
      uniquement construite sur disque&nbsp;; rien n'est entré dans
      <structname>pg_class</structname>, <structname>pg_attribute</structname>,
      etc, pour cette table. Du coup, la table n'est pas accessible par les
      opérations SQL standard tant que ces entrées ne sont pas
      réalisées en dur (à l'aide de commandes <literal>insert</literal>).
      Cette option est utilisée pour créer <structname>pg_class</structname>, etc.
     </para>

     <para>
      La table est créée partagée si <literal>shared_relation</literal> est
      indiqué. Elle possède des OID à moins que
      <literal>without_oids</literal> ne soit précisé.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>open</literal> <replaceable class="parameter">nomtable</replaceable>
    </term>

    <listitem>
     <para>
      Ouvre la table nommée
      <replaceable class="parameter">nomtable</replaceable>
      pour l'ajout de données. Toute table alors ouverte est fermée.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>close</literal> <optional><replaceable class="parameter">nomtable</replaceable></optional>
    </term>

    <listitem>
     <para>
      Ferme la table ouverte. Le nom de la
      table peut-être indiqué pour vérification mais ce n'est pas nécessaire.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>insert</literal> <optional><literal>OID =</literal> <replaceable class="parameter">valeur_oid</replaceable></optional> <literal>(</literal><replaceable class="parameter">valeur1</replaceable> <replaceable class="parameter">valeur2</replaceable> ...<literal>)</literal>
    </term>

    <listitem>
     <para>
      Insère une nouvelle ligne dans la table ouverte en utilisant
      <replaceable class="parameter">valeur1</replaceable>,
      <replaceable class="parameter">valeur2</replaceable>, etc., comme valeurs de
      colonnes et <replaceable class="parameter">valeur_oid</replaceable>
      comme OID. Si
      <replaceable class="parameter">valeur_oid</replaceable> vaut zéro
      (0) ou si la clause est omise, et que la table a des OID, alors le
      prochain OID disponible est utilisé.
     </para>

     <para>
      La valeur NULL peut être indiquée en utilisant le mot clé spécial
      <literal>_null_</literal>. Les valeurs contenant des espaces doivent être
      placées entre des guillemets doubles.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>declare</literal> <optional><literal>unique</literal></optional>
     <literal>index</literal> <replaceable class="parameter">nomindex</replaceable>
     <replaceable class="parameter">oidindex</replaceable>
     <literal>on</literal> <replaceable class="parameter">nomtable</replaceable>
     <literal>using</literal> <replaceable class="parameter">nomam</replaceable>
     <literal>(</literal> <replaceable class="parameter">classeop1</replaceable>
     <replaceable class="parameter">nom1</replaceable>
     <optional>, ...</optional> <literal>)</literal>
    </term>

    <listitem>
     <para>
      Crée un index nommé
      <replaceable class="parameter">nomindex</replaceable>, d'OID
      <replaceable class="parameter">indexoid</replaceable>, sur la table nommée
      <replaceable class="parameter">nomtable</replaceable> en utilisant la
      méthode d'accès nommée <replaceable class="parameter">nomam</replaceable>.
      Les champs à indexer sont appelés
      <replaceable class="parameter">nom1</replaceable>,
      <replaceable class="parameter">nom2</replaceable> etc., et les classes d'opérateur à
      utiliser sont respectivement
      <replaceable class="parameter">classeop1</replaceable>,
      <replaceable class="parameter">classeop2</replaceable> etc.
      Le fichier index est créé et les entrées appropriées du catalogue sont
      ajoutées pour lui, mais le contenu de l'index n'est pas initialisé par
      cette commande.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>declare toast</literal>
     <replaceable class="parameter">toasttableoid</replaceable>
     <replaceable class="parameter">toastindexoid</replaceable>
     <literal>on</literal> <replaceable class="parameter">nomtable</replaceable>
    </term>

    <listitem>
     <para>
      Crée une table TOAST pour la table nommée
      <replaceable class="parameter">nomtable</replaceable>.
      La table TOAST se voit affecter l'OID
      <replaceable class="parameter">toasttableoid</replaceable>
      et son index l'OID
      <replaceable class="parameter">toastindexoid</replaceable>.
      Comme avec <literal>declare index</literal>, le remplissage de l'index
      est reporté.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>build indices</literal></term>

    <listitem>
     <para>
      Remplit les index précédemment déclarés.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

 </sect1>

 <sect1 id="bki-structure">
  <title>Structure du fichier <acronym>BKI</acronym> de <quote>bootstrap</quote></title>

  <para>
   La commande <literal>open</literal> ne peut pas être utilisée avant que les
   tables qu'elle utilise n'existent et n'aient des entrées pour la table à
   ouvrir. (Ces tables minimales sont <structname>pg_class</structname>,
   <structname>pg_attribute</structname>, <structname>pg_proc</structname> et
   <structname>pg_type</structname>.) Pour permettre le remplissage de ces
   tables elles-mêmes,
   <literal>create</literal> utilisé avec l'option <literal>bootstrap</literal>
   ouvre implicitement la table créée pour l'insertion de données.
  </para>

  <para>
   De la même façon, les commandes <literal>declare index</literal> et
   <literal>declare toast</literal> ne peuvent pas être utilisées tant que
   les catalogues systèmes dont elles ont besoin n'ont pas été créés et remplis.
  </para>

  <para>
   Du coup, la structure du fichier <filename>postgres.bki</filename> doit
   être&nbsp;:
   <orderedlist>
    <listitem>
     <para>
      <literal>create bootstrap</literal> une des tables critiques
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>insert</literal> les données décrivant au moins les tables critiques
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>close</literal>
     </para>
    </listitem>
    <listitem>
     <para>
      Répéter pour les autres tables critiques.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>create</literal> (sans <literal>bootstrap</literal>) une table non critique
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>open</literal>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>insert</literal> les données souhaitées
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>close</literal>
     </para>
    </listitem>
    <listitem>
     <para>
      Répéter pour les autres tables non critiques.
     </para>
    </listitem>
    <listitem>
     <para>
      Définir les index et les tables TOAST.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>build indices</literal>
     </para>
    </listitem>
   </orderedlist>
  </para>

  <para>
   Il existe, sans doute, d'autres dépendances d'ordre non documentées.
  </para>
 </sect1>

 <sect1 id="bki-example">
  <title>Exemple</title>

 <para>
   La séquence de commandes suivante crée la table
   <literal>test_table</literal> avec l'OID 420, deux colonnes
   <literal>cola</literal> et <literal>colb</literal> de types respectifs
   <type>int4</type> et <type>text</type> et insère deux lignes dans la
   table&nbsp;:
<programlisting>create test_table 420 (cola = int4, colb = text)
open test_table
insert OID=421 ( 1 "value1" )
insert OID=422 ( 2 _null_ )
close test_table
</programlisting>
  </para>
 </sect1>
</chapter>