<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="dbforge">
<title>DBForge</title>

<side>
<page-toc><en>On this page:</en><fr>Sur cette page:</fr></page-toc>
<p class="center"><a href="dbforge.png"><img src="dbforge_small.png"
alt="DBForge, a code generator to access databases"
title="DBForge, a code generator to access databases"/></a></p>
</side>

<section name="dbforge:whatis">
<title><en>What is DBForge ?</en><fr>Qu'est-ce que DBForge ?</fr></title>
<p>
<en>DBForge is a tool to describe database schemas and generate
OCaml code to access these databases.
</en>
<fr>DBForge est un outil pour dcrire des schmas de base de donnes
et gnrer le code OCaml permettant d'accder  ces bases.
</fr>
</p>
</section>

<section name="dbforge:principle">
<title><en>Principle</en><fr>Principe</fr></title>
<p>
<en>The idea of the tool is based on the following problem:
The creation of functions executing SQL queries
</en>
<fr>L'ide de l'outil est base sur le problme suivant:
La cration de fonctions excutant des requtes SQL
</fr>
</p>
<ul>
<li><en>is repetitive:
 	translation of parameters into strings and concatenation of strings
	to create the query, execution of the query, test on the return value,
	translation of the returned data (for
</en>
<fr>est rptitive: traduction de paramtres en chanes de caractres et
concatnation pour crer les requte, excution de la requte, test de la
valeur de retour, traduction des donnes (pour les requtes
</fr>
<tt>select</tt>
<en> queries) into the correct OCaml type,
</en>
<fr>) vers les type OCaml correspondant,
</fr>
</li>
<li><en>is error prone:
	an error in the concatenation of strings to create the query
	(for example a missing blank) or in the concatenated strings
	will cause an error
</en>
<fr>est source d'erreurs: une erreur dans la concatnation de chanes
pour crer la requte (par exemple l'oubli d'un espace) ou dans les
chanes concatnes causer une erreur
</fr>
<em><en>at run time</en><fr> l'excution</fr></em>,
</li>
<li><en>does not allow a high maintainability: indeed, when the database
	schema is modified, one must verify that each query is still correct
	against the new database schema.
</en>
<fr>ne permet pas une bonne maintenabilit: en effet, quand le schma
de la base de donnes est modifi, il faut vrifier que chaque requte
est encore correcte par rapport au schma.
</fr>
</li>
</ul>
<p>
<en>To solve these problems, we want to
</en>
<fr>Pour rsoudre ces problmes, nous voulons
</fr>
</p>
<ul><li>
<en>automatically generate the functions executing basic queries on each table,
</en>
<fr>gnrer automatiquement les fonctions qui excutent les requtes de base
sur chaque table,
</fr>
</li>
<li><en>allow the user to define complex queries, using the SQL language ;
	the OCaml functions executing these queries being automatically
	generated, we want to guarantee
</en>
<fr>permettre  l'utilisateur la dfinition de requtes complexes, en
langage SQL; les fonctions OCaml excutant ces requtes tant automatiquement
gnres, nous voulons garantir
</fr>
<em><en>at compile time</en><fr> la compilation</fr></em>
<en>that execution of these queries will not fail at run time
	(because of errors like syntax errors or referencing a non-existent
	column of a table, for example),
</en>
<fr>que l'excution de ces requtes n'chouera (par exemple  cause d'erreurs
de syntaxe ou encore par rfrencement de colonne non existente dans une table),
</fr>
</li>
<li>
<en>automatically verify and invalidate some queries when the database schema
is modified.
</en>
<fr>vrifier automatiquement et invalider des requtes quand le schma de la
base est modifi.
</fr>
</li>
</ul>
<p>
<en>To do so, we must have the following information about each colum of each table:
</en>
<fr>Pour faire tout cela, nous avons besoin des informations suivantes  propos
de chaque colonne de chaque table:
</fr>
</p>
<ul>
<li>
<en>its name,
</en>
<fr>son nom,
</fr>
</li>
<li>
<en>its type definition for the target DBMS,
</en>
<fr>la dfinition de son type selon la base de donnes cible,
</fr>
</li>
<li>
<en>some attributes like whether the column is nullable, whether it's a key
	for this table,
</en>
<fr>des attributs indiquant par exemple si la colonne peut tre NULL,
si c'est une cl,
</fr>
</li>
<li>
<en>its OCaml type in the source code we want to generate,
</en>
<fr>son type OCaml dans le code source que nous voulons gnrer,
</fr>
</li>
<li>
<en>the functions to use to translate DBMS (resp. OCaml) values into OCaml
	(resp. DBMS) values.
</en>
<fr>les fonctions  utiliser pour traduire les valeurs de la base de
donnes vers des valeurs OCaml et rciproquement.
</fr>
</li>
</ul>
<p>
<en>The list of tables with the above information for each column is what
we call the database schema.
</en>
<fr>La liste des tables avec les informations ci-dessus pour chaque colonne
est ce que nous appelons le schma de base de donnes.
</fr>
</p>
<p>
<en>The DBForge tool allows to edit such a schema in a graphical user interface,
and generates the corresponding OCaml code. The user can also define
SQL queries to be embedded in OCaml functions in the generared code.
For now, only "select" and "union" queries are accepted.</en>
<fr>L'outil DBForge permet de dfinir un tel schma dans une interface
graphique et de gnrer le code OCaml correspondant. L'utilisateur peut galement
dfinir des requtes SQL pour qu'elles soient encapsules dans des fonctions OCaml
dans le code gnr. Pour l'instant, seules les requtes de type "select" et "union"
sont supportes.
</fr>
</p>

</section>

<section>
<title><en>Example</en><fr>Exemple</fr></title>
<p>
<en>The </en>
<fr>La </fr>
<local href="main:install">distribution</local>
<en> contains an example in the directory
</en>
<fr> contient un exemple dans le rpertoire
</fr>
<tt>src/dbforge/example</tt>.
<en>You will find several files.
</en>
<fr>On y trouve plusieurs fichiers.
</fr>
</p>
<p><tt>Makefile</tt>
<en> is the file used to compile with
</en>
<fr> est le fichier pour compiler avec
</fr>
<tt>make</tt>.
</p>

<p><tt>base.xml</tt>
<en> is the file containing the schema. It can be edited with the graphical
interface, launched by the following command:
</en>
<fr> est le fichier contenant le schma. Il peut tre dit par l'diteur graphique
lanc avec la commande suivante:
</fr>
</p>
<command-line>dbforge2.gui.{x,byte} base.xml</command-line>
<p>
<en>The OCaml code is generated from this file with the follownig command:
</en>
<fr>Le code OCaml est gnr  partir de ce fichier par la commande suivante:
</fr>
</p>
<command-line>dbforge2.{x,byte} -o base.ml base.xml</command-line>
<p>
<en>The file
</en>
<fr>Le fichier </fr>
<tt>base.ml</tt>
<en> then contains the generated OCaml code. This code uses two modules
installed with Cameleon2: Dbf_sql_driver and Dbf_sql_misc.
You can get the module interface of the generated file with the following command:
</en>
<fr> contient alors le code OCaml gnr. Ce dernier utilise deux modules
installs en mme temps que Cameleon2: Dbf_sql_driver et Dbf_sql_misc.
On peut obtenir le fichier d'interface avec la commande suivante:
</fr>
</p>
<command-line>
ocamlc -I +cameleon2 -i base.ml > base.mli
</command-line>
<p>
<en>The generated code is composed of functers, one per table and one more
for the additional queries defined in the schema. These functers take in
parameter a module of type Dbf_sql_driver.SqlDriver, which allows to abstract
the underlying database system, by providing a common interface.
</en>
<fr>Le code gnr est compos de foncteurs, un par table et un pour les requtes
additionnelles. Ces foncteurs prennent tous en paramtre un module du type
Dbf_sql_driver.SqlDriver, qui permet d'abstraire le systme de gestion de base de
donnes utilis en utilisant des modules partageant la mme interface.
</fr>
</p>

<p><tt>example.ml</tt>
<en> is the main file of the example. It uses the module Dbf_mysql whose source is
installed with Cameleon2. Since it needs the OCaml-MySQL library to be installed,
this module is not compiled when Cameleon2 is installed, but must be compiled by
the application which uses it. This module has the type Dbf_sql_driver.SqlDriver and
can therefore be passed in parameter to the functers of the generated code in
file
</en>
<fr> est le fichier principal de l'exemple. Il utilise le module Dbf_mysql
dont le source est install en mme temps que Cameleon2. Comme il ncessite
que la bibliothque OCaml-Mysql soit installe, il n'est pas compil  l'installation
mais doit tre compil par l'application qui souhaite s'en servir.
Ce module est du type Dbf_sql_driver.SqlDriver et peut donc tre pass en paramtre
aux foncteurs gnrs dans le fichier
</fr>
<tt>base.ml</tt>.
<en> The modules obtained then offer the functions to access the database.
</en>
<fr> Les modules obtenus fournissent les fonctions d'accs  la base de donnes.
</fr>
</p>

<linkline>
<link href="refdoc/Dbf_sql_driver.html">module Dbf_sql_driver</link>
<link href="refdoc/Dbf_sql_misc.html">module Dbf_sql_misc</link>
</linkline>
<p>
<en>
</en>
<fr>
</fr>
</p>

<p>
<en>
</en>
<fr>
</fr>
</p>


</section>


<section>
<p>
<todo>
<en>To complete...</en>
<fr>A complter...</fr>
</todo>
</p>
</section>
</page>