Utilisation de l'API mySQL avec Delphi

Ce document a pour but de montrer comment exploiter une connexion à une base de données mySQL, en utilisant uniquement l'API fournie avec mySQL.
Le code a été écrit et testé avec Delphi et mySQL version 4.0.4 bêta. Pour une description des fonctions de l'API, je vous renvoie à la documentation fournie avec mySQL sur www.mysql.com.

I-A. Création du projet▲

I-B. Mise à jour de mySQL.pas▲

type
    PMYSQL_FIELD = ^TMYSQL_FIELD;
    TMYSQL_FIELD = record
    name: pChar;
    table: pChar;
    org_table : pChar;
    db : pChar;
    def: pChar;
    length: longword;
    max_length: longword;
    flags: longword;
    decimals: longword;
    _type: enum_field_types;
end;

Avant tout chose il est nécessaire d'initialiser l'accès à la DLL :

var
   mySQLConnection : PMYSQL;
                
begin
    mySQLConnection := mysql_init(nil);
end;

Au retour, mySQLConnection contient l'adresse de la structure permettant l'interfaçage avec mySQL, ou nil en cas d'erreur.
Il est tout à fait possible d'avoir plusieurs connexions dans le même programme.

var
    mySQLConnection : PMYSQL;
                
begin
    mysql_close(mySQLConnection);
end;

mysql_close ferme la connexion à la base de données et libère les ressources allouées lors de la création de la connexion.

var
    mySQLConnection : PMYSQL;
                
begin
    if mysql_real_connect(mySQLConnection, '127.0.0.1', 'root', 'root', 'test', 0, nil, 0) <> nil then begin
        // Connexion réussie
    end else begin
        // Échec de connexion
    end;
end;

mysql_real_connect ouvre la connexion à la base de données, et met à jour la structure mySQL en fonction de cette connexion.
Les paramètres sont :

• le handle de connexion ;
• l'adresse du serveur où mySQL est installé ;
• le nom d'utilisateur ;
• le mot de passe ;
• le nom de la base de données ;
• le n° de port (0 indique que l'on utilise le port par défaut) ;
• le nom du pipe ou le socket qui sera utilisé (habituellement NULL) ;
• des statuts permettant de configurer la connexion (habituellement 0).

Une valeur de retour de 0 indique qu'une erreur s'est produite.
Une valeur autre indique que la connexion est ouverte.

var
    mySQLConnection : PMYSQL;
    myROW : PMYSQL_ROW;
    myRES : PMYSQL_RES;
    aStr : AnsiString;
    i, j : Cardinal;
                
begin
    myRES := mysql_list_tables(mySQLConnection, nil);
    if myRES <> nil then begin
        for i := 0 to myRES.row_count-1 do begin
            myROW := mysql_fetch_row(myRES);
            for j := 0 to mysql_num_fields(myRES) - 1 do begin
                aStr := myROW^[j];
                ListBox1.Items.Add(aStr);
            end;
        end;
        mysql_free_result(myRES);
    end;
end;

mysql_list_tables permet de lire le nom de toutes les tables de la base de données associée à mySQL.
Ses paramètres sont :

• le handle de connexion ;
• un masque permettant de filtrer les noms de tables à lire.

La valeur de retour est une structure de type PMYSQL_RES qui est un handle vers le résultat de la requête. Si la requête échoue, la valeur de retour est nil.

La propriété row_count de myRES contient le nombre d'enregistrements contenus dans le résultat.

mysql_fetch_row renvoie l'enregistrement suivant du résultat de la requête, dans une structure de type PMYSQL_ROW.

La fonction mysql_num_fields permet quant à elle de connaître le nombre de champs renvoyés par la requête.

Une fois que l'on n'a plus besoin du résultat de la requête, il ne faut pas oublier de libérer les ressources en appelant la fonction mysql_free_results.

var
    mySQLConnection : PMYSQL;
    myRES : PMYSQL_RES;
    myROW : PMYSQL_ROW;
    aStr : AnsiString;
    i, j : Cardinal;
                
begin
    if mysql_query(mySQLConnection, 'select * from testbcb') = 0 then begin
        myRES := mysql_store_result(mySQLConnection);
        if (myRES <> nil) then begin
            for i := 0 to myRES.row_count - 1 do begin
                myROW := mysql_fetch_row(myRES);
                for j := 0 to mysql_num_fields(myRES) - 1 do begin
                    aStr := myROW^[j];
                    ListBox1.Items.Add(aStr);
                end;
            end;
            mysql_free_result(myRES);
        end;
    end;
end;

La fonction mysql_query exécute une requête.
Une valeur de retour à 0 indique que la requête a abouti. Une valeur autre indique une erreur.

Pour accéder au résultat de la requête, il est nécessaire d'appeler la fonction mysql_store_results qui renvoie un pointeur de type PMYSQL_RES.

mysql_fetch_row renvoie l'enregistrement suivant du résultat de la requête, dans une structure de type PMYSQL_ROW.

var
    mySQLConnection : PMYSQL;
    myRES : PMYSQL_RES;
    myFields : PMYSQL_FIELDS;
    aStr : AnsiString;
    CountFields : Integer;
    i : Cardinal;
                    
begin
    if mysql_query(mySQLConnection, 'select * from testbcb') = 0 then begin
        myRES := mysql_store_result(mySQLConnection);
        if (myRES <> nil) then begin
            CountFields := mysql_num_fields(myRES);
            myFields := mysql_fetch_fields(myRES);
            for i := 0 to CountFields - 1 do begin
                aStr := 'field name ' + myFields^[i].name;
                ListBox1.Items.Add(aStr);
            end;
        end;
        mysql_free_result(myRES);
    end;
end;

La fonction mysql_fetch_fields remplit une structure de type PMYSQL_FIELDS qui contient alors un tableau contenant toutes les informations des champs renvoyés par la requête.

VIII-A. Obtenir le code d'erreur▲

var
    myErrorCode : Cardinal;
                    
begin
    myErrorCode := mysql_errno(mySQLConnection);
end;

VIII-B. Obtenir un message décrivant l'erreur▲

var
    myErrorMsg : AnsiString;
                    
begin
    myErrorMsg := mysql_error(mySQLConnection);
end;

Dans la version 4, il y a la possibilité d'embarquer le serveur mySQL dans l'application. L'utilisation de cette version implique quelques modifications au projet et au fichier de configuration de mySQL.

IX-A. Modification du fichier de configuration de mySQL▲

[embedded]
basedir=e:/mysql
datadir=e:/mysql/data

IX-B. Modification du projet▲

                    mysql_server_init: function(argc: integer; argv: pointer; groups :pointer) : integer ; stdcall;
                    mysql_server_end: procedure; stdcall;

                    assign_proc(@mysql_server_init, 'mysql_server_init');
                    assign_proc(@mysql_server_end, 'mysql_server_end');

                    {$LIBMYSQLD}

IX-C. Démarrage du serveur▲

if mysql_server_init(0, nil, nil) = 0 then begin
    // le serveur est démarré
end else begin
    // le serveur n'est pas démarré
end;

IX-D. Arrêt du serveur▲

mysql_server_end;