Chapitre 27 Etendre MySQL

Le système de tests est constitué d'un interpréteur de langage de tests (mysqltest), un script Shell qui exécute tous les scripts (mysql-test-run), les cas de tests réels, écrits dans un langage spécial de tests, et leur résultats attendus. Pour exécuter ces tests sur votre système après une compilation, tapez make test ou mysql-test/mysql-test-run depuis la racine de la distribution. Si vous avez installé une distribution binaire, cd jusqu'au dossier d'installation (par exemple, /usr/local/mysql), et exécutez scripts/mysql-test-run. Tous les tests doivent réussir. Si ce n'est pas le cas, vous devriez essayer de trouver pourquoi, et faire un rapport de bogues à MySQL. See Section 27.1.2.3, « Rapporter des bugs dans la suite de tests MySQL ».

Si vous avez une copie de mysqld qui fonctionne sur la machine où vous voulez faire des tests, vous n'avez pas à l'arrêter, tant qu'elle n'utilise pas les ports 9306 et 9307. Si l'un de ces ports est pris, vous devriez éditer le script mysql-test-run et changer les valeurs des ports des maîtres et esclaves, en les rempla¸ant par des ports libres.

Vous pouvez exécuter des tests individuels avec mysql-test/mysql-test-run test_name.

Si l'un des tests échoue, vous devriez tester mysql-test-run avec l'option --force pour vérifier si aucun autre test n'échoue.

Vous pouvez utiliser le langage de mysqltest pour écrire vos propres cas de tests. Malheureusement, nous n'avons pas encore écrit une documentation complète pour ce logiciel, et nous prévoyons de le faire rapidement. Vous pouvez, toutefois, utiliser les cas de tests actuels comme exemples. Les points suivants devraient vous mettre le pied à l'étrier.

Si votre version de MySQL ne passe pas un teste, vous devez faire ceci :

La fonction principale doit être déclarée comme illustrée ici. Notez que le type de retour et les paramètres diffèrent, suivant que vous voulez déclarer une fonction SQL XXX() qui retournera une STRING, un INTEGER ou un REAL dans la commande CREATE FUNCTION :

Pour les fonctions de chaînes STRING :

char *xxx(UDF_INIT *initid, UDF_ARGS *args,
          char *result, unsigned long *length,
          char *is_null, char *error);

Pour les fonctions d'entiers INTEGER :

long long xxx(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Pour les fonctions de nombres à virgule flottante REAL :

double xxx(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Les fonctions d'initialisation et de terminaison sont déclarées comme ceci :

my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);

void xxx_deinit(UDF_INIT *initid);

Le paramètre initid est passé aux trois fonctions. Il pointe sur une structure UDF_INIT qui est utilisée pour communiquer des informations entre les fonctions. Les membres de la structure UDF_INIT sont ceux qui sont listés ci-dessous. La fonction d'initialisation doit préparer les membres qu'elle veut, et notamment leur donner une valeur initiale (pour utiliser les valeurs par défaut, laissez le membre intact) :

Voici une description des différentes fonctions que vous devez définir pour réaliser des calculs sur des regroupements, avec une fonction utilisateur :

Notez que ce qui suit n'est pas demandé ou utilisé par MySQL 4.1.1. Vous pouvez conserver cette définition pour assurer la compatibilité entre MySQL 4.0 et MySQL 4.1.1.

char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
                char *is_null, char *error);

Cette fonction est appelée lorsque MySQL trouve la première ligne dans un nouveau groupe. Dans cette fonction, vous devez remettre à zéro des variables internes de sommaire, puis indique le nouvel argument comme premier membre du nouveau groupe.

Dans de nombreuses situations, cela se fait en interne en remettant à zéro toutes les variables, et en appelant xxx_add().

Cette fonction n'est demandée que par MySQL 4.1.1 et plus récent :

char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);

Cette fonction est appelée à chaque fois qu'une ligne qui appartient à un groupe est trouvée, hormis la première ligne. Durant cette fonction, vous devez ajouter les données dans votre variable interne de sommaire.

Vous pouvez utiliser le pointeur error pour stocker un octet si quelque chose n'a pas fonctionné.

char *xxx_add(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Cette fonction est appelée pour toutes les lignes du même groupe, hormis pour la première ligne. Dans cette dernière, vous devez ajouter la valeur dans UDF_ARGS pour vos variables internes.

La fonction xxx() doit être déclarée de manière identique à celle d'un fonction utilisateur simple. See Section 27.2.3.1, « Fonctions utilisateur : appeler des fonctions simples ».

Cette fonction est appelée lorsque toutes les lignes d'un groupe ont été traitées. Vous ne devez normalement pas accéder à la variable args ici, mais retourner votre valeur, à partir des valeurs du sommaire interne.

Tous les traitements des arguments de xxx_reset() et xxx_add() doivent être fait d'une manière similaire à celle des fonctions UDF normales. See Section 27.2.3.3, « Traitement des arguments ».

La gestion de la valeur retournée par xxx() doit être identique à celle d'une fonction utilisateur classique. See Section 27.2.3.4, « Valeurs de retour et gestion d'erreurs. ».

Le pointeur argument de is_null et error sont les mêmes pour tous les appels de xxx_reset(), xxx_add() et xxx(). Vous pouvez utiliser ces valeur pour vous rappeler si vous avez rencontré une erreur, ou si la fonction xxx() doit retourner NULL. Notez que vous ne devez pas stocker de chaîne dans *error! C'est un conteneur d'un seul octet!

is_null est remis à zéro pour chaque (avant d'appeler xxx_reset(). error n'est jamais remis à zéro.

Si isnull ou error sont modifiés après xxx(), alors MySQL va retourner NULL comme résultat de la fonction de groupement.

Le paramètre args pointe sur une structure UDF_ARGS qui dispose des membre suivants :

La fonction d'initialisation doit retourner 0 si aucune erreur ne s'est produite et 1 sinon. Si une erreur s'est produite, xxx_init() doit stocker un message se terminant par un NULL dans le paramètre message. Le message sera retourné au client. La taille du tampon du message est de MYSQL_ERRMSG_SIZE caractères, mais vous devez essayer de garder une taille de message inférieure à 80 caractères, sinon, il remplit la largeur d'un écran de terminal standard.

La valeur de retour de la fonction principale xxx() est la valeur de la fonction, pour les fonctions long long et double. Une fonction de chaîne de caractères doit retourner un pointeur vers le résultat et stocker la taille de la chaîne de caractères dans l'argument length.

Affectez cette valeur au contenu et à la longueur de la valeur retournée. Par exemple :

memcpy(result, "chaîne retournée", 16);
*length = 16;

Le tampon result qui est passé à la fonction a une taille de 255 bits. Si votre résultat dépasse ceci, ne vous inquiétez pas de l'allocation de mémoire pour ce résultat.

Si votre fonction de chaînes de caractères a besoin de retourner une chaîne de caractères plus grande que 255 bits, vous devez allouer de l'espace pour cela avec malloc() dans votre fonction xxx_init(). Vous pouvez stocker la mémoire allouée dans le buffer ptr de la structure UDF_INIT pour être ré-utilisée par les appels futurs de xxx(). See Section 27.2.3.1, « Fonctions utilisateur : appeler des fonctions simples ».

Pour indiquer une valeur de retour NULL dans la fonction principale, mettez is_null à 1 :

*is_null = 1;

Pour indiquer une erreur retournée dans la fonction principale, mettez le paramètre error à 1:

*error = 1;

Si xxx() met *error à 1 pour chaque ligne, la valeur de la fonction est NULL pour la ligne en question et pour chaque ligne suivante traitée par le processus dans lequel XXX() est invoqué. (xxx() ne sera même pas appelé pour les lignes suivantes.) Remarque : dans les versions antérieures à 3.22.10, vous devez définir *error et *is_null :

*error = 1;
*is_null = 1;

Les fichiers qui implémentent des fonctions utilisateurs doivent être compilés et installés sur le même hôte que celui du serveur. Ce processus est décrit plus bas, avec le fichier udf_example.cc qui est inclut dans les sources MySQL. Ce fichier contient les fonctions suivantes :

Un fichier dynamiquement chargé doit être compilé sous la forme d'un objet partagé, grâce à une commande comme celle-ci :

shell> gcc -shared -o udf_example.so myfunc.cc

Vous pouvez facilement trouver les options correctes pour la compilation en exécutant cette commande dans le dossier sql de votre installation source :

shell> make udf_example.o

Vous devez exécuter une commande de compilation similaire à celle que le make affiche, sauf que vous devrez supprimer l'option -c près de la fin de la ligne, et ajouter -o udf_example.so à la fin de la ligne. Sur certains systèmes, vous devrez aussi supprimer -c de la commande).

Une fois que vous compilez un objet partagés contenant des fonctions utilisateurs, vous devez les installer, et prévenir le serveur MYSQL. Compiler un objet partagé avec udf_example.cc produit un fichier qui s'appelle udf_example.so (le nom exact peut varier suivant la plate-forme). Copiez ce fichier dans l'un des dossiers utilisé par ld, tel que /usr/lib. Par exemple, /etc/ld.so.conf.

Sur de nombreux systèmes, vous pouvez faire pointer la variable d'environnement LD_LIBRARY ou LD_LIBRARY_PATH pour qu'elle pointe dans le dossier où vous avez vos fichiers de fonctions. Le manuel de dlopen vous indiquera quelle variable utiliser sur votre système. Vous devriez indiquer cette valeur dans les options de démarrage de mysql.server et safe_mysqld, et redémarrer mysqld.

Après que la bibliothèque ait été installée, indiquez à mysqld ces nouvelles fonctions avec ces commandes :

mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "udf_example.so";
mysql> CREATE FUNCTION myfunc_double RETURNS REAL SONAME "udf_example.so";
mysql> CREATE FUNCTION myfunc_int RETURNS INTEGER SONAME "udf_example.so";
mysql> CREATE FUNCTION lookup RETURNS STRING SONAME "udf_example.so";
mysql> CREATE FUNCTION reverse_lookup
    ->        RETURNS STRING SONAME "udf_example.so";
mysql> CREATE AGGREGATE FUNCTION avgcost
    ->        RETURNS REAL SONAME "udf_example.so";

Les fonctions peuvent être effacées plus tard avec DROP FUNCTION:

mysql> DROP FUNCTION metaphon;
mysql> DROP FUNCTION myfunc_double;
mysql> DROP FUNCTION myfunc_int;
mysql> DROP FUNCTION lookup;
mysql> DROP FUNCTION reverse_lookup;
mysql> DROP FUNCTION avgcost;

Les commandes CREATE FUNCTION et DROP FUNCTION modifient la table système func dans la base mysql. Le nom de la fonction, son type et le nom de la bibliothèque partagée sont alors sauvés dans la table. Vous devez avoir les droits de INSERT et DELETE dans la base mysql pour ajouter et effacer des fonctions.

Vous ne devez pas utiliser la commande CREATE FUNCTION pour ajouter une fonction qui a déjà été créée. Si vous devez reinstaller une fonction, vous devez la supprimer avec la commande DROP FUNCTION puis la reinstaller avec CREATE FUNCTION. Vous devrez faire cela, par exemple, si vous recompilez une nouvelle version de votre fonction, pour que mysqld utilise cette nouvelle version. Sinon, le serveur va continuer à utiliser l'ancienne version.

Les fonctions actives sont rechargées à chaque fois que le serveur démarre, à moins que vous ne démarriez le serveur mysqld avec l'option --skip-grant-tables. Dans ce cas, l'initialisation des fonctions utilisateurs sont ignorées, et ces fonctions sont inutilisables. Une fonction active doit avoir été créée avec CREATE FUNCTION et pas supprimée avec DROP FUNCTION.

MySQL prend les mesures suivantes pour éviter une utilisation abusive des fonctions utilisateurs.

Vous devez avoir les droits de INSERT pour être capable d'utiliser la commande CREATE FUNCTION et le droit de DELETE pour être capable d'effacer une fonction (DROP FUNCTION. Ceci est nécessaire car ces commandes ajoutent et suppriment des lignes dans la table mysql.func.

UDF doit avoir au moins un symbole défini, en plus du symbole xxx qui correspond à la fonction principale xxx(). Ces symboles auxiliaires correspondent aux fonctions xxx_init(), xxx_deinit(), xxx_reset(), xxx_clear() et xxx_add(). Depuis MySQL 4.0.24, 4.1.10a et 5.0.3, mysqld supporte l'option --allow-suspicious-udfs qui spécifie si les UDF qui n'ont qu'une fonction xxx peuvent être chargées. Par défaut, cette fonction est désactivée, ce qui empêche les fonctions de charger des fonctions depuis des objets partagés autres que les UDF légales. Si vous avez de vieilles fonctions UDF qui contiennent uniquement le symbole xxx qui ne peuvent pas être recompilées pour utiliser un symbole auxiliaire, il sera nécessaire d'utiliser l'option --allow-suspicious-udfs. Sinon, vous devrez vous passer de cette fonctionnalité.

Les fichiers d'objet UDF ne peuvent pas être placés dans n'importe quel dossier. Ils doivent être placés dans un dossier système que le compilateur dynamique peut analyser. Pour assurer le fonctionnement de cette restriction, et éviter les attaques par spécification de chemins arbitraires en dehors de ceux que le compilateur dynamique peut atteindre, MySQL vérifie dans le nom de l'objet partagé spécifié dans la commande CREATE FUNCTION la présence de délimiteurs de dossiers. Depuis MySQL 4.0.24, 4.1.10a et 5.0.3, MySQL vérifie aussi les délimiteurs de fichiers stockés dans la table mysql.func lorsque vous chargez les fonctions. Cela évite les tentatives de spécifications de chemins interdits, en manipulant directement les tables mysql.func. Pour plus de détails sur les UDF et le compilateur dynamique, voyez Section 27.2.3.5, « Compiler et installer des fonctions utilisateurs ».