De Cantine - Documentation.

Utilisation de l'utilitaire fourni

Un programme utilitaire destiné à l'initialisation et la mise à niveau des bases de données est fourni.

Il s'agit d'un logiciel libre sous licence GPL qui n'est pas en relation directe avec Cantine, mais je tiens à votre disposition les sources en leur état actuel sur simple demande.
N'hésitez pas si vous le souhaitez à me contacter pour me faire part de vos remarques et suggestions.

Pour y accéder, vous pouvez cocher la case adéquate lors de la dernière étape de l'installation ou lancer le raccourci depuis le menu démarrer/cantine. Il est également possible d'appeler la commande java -jar xtnd_db_updater.jar depuis le dossier d'installation de Cantine (par défaut C:\Program Files\Cantine sous Windows).

Interface de l'utilitaire

Cette fenêtre se divise en trois parties :

• Projets : choix du projet logiciel à traiter. Seule une entrée nommée Cantine est disponible avec cette version.
• Fichier de mise à jour : sélection du fichier à traiter. Il s'agit ici de choisir le fichier qui convient à votre cas. On distingue deux « types » de fichiers : les mises à jour (nommés maj_{moteur}_{version_initiale}-{version_finale}) et les initialisations (nommés init_{moteur}_{version}). En cas de nouvelle installation, sélectionnez le fichier d'initialisation correspondant à la version que vous installez (il ne devrait y en avoir qu'un seul) ; en cas de mise à jour, choisissez le fichier dont le nom contient le numéro de votre version actuelle (par exemple, si vous passez de la version 1.0.2 à la 1.1 sous HsqlDB, le nom de fichier sera maj_hsql_1.0.2-1.1.xml).
• Donnés de connexion : les données par défaut sont extraites du fichier sélectionné.

Une fois le fichier sélectionné diverses informations seront indiquées :

• Date : la date du fichier
• Juste sous le titre, le nom du programme et les informations de version (version initiale et de destination pour une mise à jour, version de destination seule pour une installation)
• Driver : pilote de base de données utilisé
• Utilisateur : nom de l'utilisateur de la base de données. Par défaut, l'utilisateur "root" pour MySQL et "sa" pour HsqlDB seront proposés.
• Mot de passe : mot de passe de l'utilisateur choisi. Pour Hsql, l'utilisateur "sa" ne possède par défaut pas de mot de passe. Pour MySQL, le mot de passe "root" est celui défini lors de l'installation du moteur. Lors d'une mise à jour MySQL il est possible d'utiliser l'utilisateur spécifique à la base (voir l'explication sur le parcours des bases MySQL).
• Serveur hôte : nom ou adresse du serveur MySQL
• Port (MySQL uniquement) : port de connexion au serveur (3306 par défaut).
• Base de données : chemin (pour hsql) ou nom (pour mysql) de la base de données à utiliser. Pour HsqlDB, le bouton ... ouvrira une fenêtre qui vous permettra de sélectionner le fichier adéquat ; pour MySQL l'interface décrite dans le paragraphe parcours des bases MySQL.
• Arguments : arguments supplémentaires à la connexion.

Pour effectuer une initialisation ou une mise à jour, il faut impérativement que la base de données existe.

• MySQL : il faut pour effectuer l'initialisation préalablement créer la base. Pour ce faire, utilisez l'interface de gestion des bases MySQL. Lors d'une mise à jour, il faut bien évidemment que la base existe. Dans ce cas, n'utilisez l'interface de gestion des bases MySQL que pour sélectionner la base dans la liste.
• HsqlDB : lors de l'initialisation, la base de données est automatiquement créée. Lors d'une mise à jour par contre, il faut évidemment que la base existe déjà.

Une fois les renseignements de connexion dument complétés, choisissez le bouton Mise à jour. Une fenêtre récapitulative sera affichée :

Chacune des lignes de cette fenêtre correspond à une instruction particulière. Trois états de sortie sont possibles :

• Passé (image V verte) : l'instruction a été correctement traitée par le moteur
• sauté (croix noire) : l'instruction a été ignorée, cela se produit typiquement lorsque tout ou partie de l'initialisation/mise à jour a déjà été lancée
• échec (croix rouge) : une erreur est survenue. Si tel est le cas, vous ne pourrez pas utiliser le logiciel correctement. Utilisez le forum sur le site du logiciel pour nous décrire les circonstances du problème (un fichier de log qui stocke toutes les erreurs se trouve dans le répertoire d'installation du logiciel (C:\Program Files\Cantine\.logs\update.log), communiquez le contenu de ce fichier pour que nous puissions déterminer la cause du problème.

Parcours des bases MySQL

Si les informations de connexion sont correctes, vous accédez à la liste des bases de données sur le serveur.

Les différents champs texte sur la droite vous permettent de vous connecter sur un autre serveur ou avec un autre utilisateur. La liste des bases sera mise à jour en conséquence.

L'utilitaire permet également la sauvegarde des données et/ou de la structure d'une base de données vers un fichier XML ou SQL.

Pour effectuer une mise à jour, il vous suffit de sélectionner la base à mettre à jour dans la liste puis de cliquer sur le bouton Sélectionner.

Pour une nouvelle installation, il faut créer une base. Pour ce faire, remplissez le champ Entrez un nom dans le bas de la fenêtre. Il est possible et même conseillé à ce stade de créer un utilisateur spécifique pour la base (il est généralement déconseillé pour des raisons de sécurité de recourir à l'utilisateur root pour l'utilisation d'un logiciel).
Pour créer un utilisateur, cochez la case Enregistrer l'utilisateur puis renseignez les champs Utilisateur et Password. Ensuite, activez le bouton Créer la base. A titre d'information, les fichiers de configuration par défaut utilisent la base nommée "cantine", l'utilisateur et le mot de passe sont "cantine" également.

Une fois la base créée, elle est automatiquement sélectionnée dans la liste, il ne vous reste plus qu'à cliquer sur sélectionner.

Ensuite, la fenêtre de parcours se referme, et le champ Base de données de la fenêtre principale est mis à jour selon votre sélection.

Initialisation et mise à jour manuelle

HSQL

Actuellement, à moins de bien connaitre HSQLDB, vous devez utiliser l'utilitaire fourni pour initialiser ou mettre à jour une base HSQL.

MySQL

L'initialisation de la base MySQL se compose de n étapes :

• création de la base de données
• import du script SQL
• création de l'utilisateur

Placez vous dans le dossier files du répertoire d'installation de Cantine, puis connectez-vous à votre serveur MySQL en root :

mysql -u root -p

L'option -p n'est pas requise si l'utilisateur root ne possède pas de mot de passe.

Vous pourrez ensuite créer la base, importer le script et créer l'utilisateur :

mysql> CREATE DATABASE cantine;
Query OK, 1 row affected (0.08 sec)
mysql> USE cantine;
Database changed
mysql> SOURCE init_mysql_{version}.sql
Query OK, 0 rows affected (0.00 sec)
[...]
mysql > GRANT USAGE ON cantine.* TO '{utilisateur}'@'%' IDENTIFIED BY '{mot_de_passe}';

Dans les lignes qui précèdent, veillez à remplacer {version} par la version de cantine utilisée, {utilisateur} par le nom d'utilisateur que vous souhaitez créer et {mot_de_passe} par le mot de passe de cet utilisateur.