8.2.2 L'interface DBI

$dbh

Gestionnaire de base de données

$sth

Gestionnaire de requête

$rc

Code de retour (souvent un status)

$rv

Valeur de retour (souvent un comptage de lignes)

connect($data_source, $username, $password)

Utilise la méthode connect pour crée une connexion de base de données à la source. La valeur doit commencer par DBI:nom_pilote: . Exemples d'utilisation de connect avec le pilote DBD::mysql :

$dbh = DBI->connect("DBI:mysql:$database", $user, $password); $dbh = DBI->connect("DBI:mysql:$database:$hostname",                     $user, $password); $dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",                     $user, $password);

Si le nom d'utilisateur et/ou le mot de passe ne sont pas définis, DBI utilises la valeur des variables d'environnements DBI_USER et DBI_PASS , respectivement. Si vous ne spécifiez pas un nom d'hôte, il est à 'localhost' par défaut. Si vous ne spécifiez pas un numéro de port, il est mit par défaut au port par défaut de MySQL (3306).Depuis la version 1.2009 de Msql-Mysql-modules , la valeur de $data_source accepte certains modificateurs :

mysql_read_default_file=nom_du_fichier

Lit le fichier filename en tant que fichier d'options. Pour plus d'informations sur les fichiers d'options, consulter Fichier d'options my.cnf .

mysql_read_default_group=nom_du_groupe

Le groupe par défaut lors de la lecture d'un fichier d'options est normalement le groupe [client] . En spécifiant l'option mysql_read_default_group , le groupe par défaut devient le groupe [nom_du_groupe] .

mysql_compression=1

Utiliser la communication compressée entre le client et le serveur (à partir de la version 3.22.3 de MySQL).

mysql_socket=/path/to/socket

Spécifie le chemin vers la socket Unix qui est utilisée pour se connecter au serveur. (MySQL version 3.21.15 ou plus).

Plusieurs modificateurs peuvent être donnés, ils doivent être séparés par des point-virgules.Par exemple, si vous voulez éviter d'avoir à écrire le nom d'utilisateur et le mot de passe en dur dans un script DBI , vous pouvez le prendre du fichier utilisateur d'options ~/.my.cnf en écrivant votre appel à connect de la façon suivante :

$dbh = DBI->connect("DBI:mysql:$database"                 . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",                 $user, $password);

Cet appel lira les options définies pour le groupe [client] dans le fichier d'options. Si vous voulez le faire aussi pour le groupe [perl] par exemple, vous pouvez utiliser ce qui suit :

$dbh = DBI->connect("DBI:mysql:$database"                 . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"                 . ";mysql_read_default_group=perl",                 $user, $password);

disconnect

La méthode disconnect déconnecte le gestionnaire de base de données du serveur. On y fait appel avant de terminer le programme.Exemple :

$rc = $dbh->disconnect;

prepare($statement)

Prépare une requête SQL pour l'exécution par le serveur de base de données et retourne un gestionnaire de requête ($sth) , que vous pouvez utiliser pour invoquer la méthode execute . Le plus souvent, vous gérez les requêtes SELECT (et ceux qui s'en rapprochent, comme SHOW , DESCRIBE , et EXPLAIN ) à l'aide de prepare et execute .Exemple :

$sth = $dbh->prepare($statement)     or die "Impossible de préparer $statement: $dbh->errstr\n";

execute

La méthode execute exécute une requête préparée. Pour les commandes qui ne se rapprochent pas de SELECT , execute retourne le nombre de lignes affectées. Si aucune ligne ne l'est, execute retourne "0E0" , que Perl traite comme zéro mais considère comme vrai (true). Si une erreur survient, execute retourne undef . Pour les requêtes SELECT , execute ne fait que démarrer la requête SQL dans la base de données; vous avez besoin d'utiliser une des méthodes fetch_* décrites ici pour récupérer les données.Exemple :

$rv = $sth->execute           or die "ne peut exécuter la requête : $sth->errstr;

do($statement)

La méthode do prépare et exécute une requête SQL et retourne le nombre de lignes affectées. Si aucune ne l'est, do retourne "0E0" , que Perl traite comme zéro mais considère comme vrai (true). Cette méthode est généralement utilisée pour les requêtes qui ne se rapprochent pas de SELECT qui ne peuvent être préparées à l'avance (à cause d'une limitation du pilote) ou qui n'ont pas besoin d'être exécutées plus d'une fois (insertions, suppressions, etc.). Exemple :

$rv = $dbh->do($statement)         or die "Ne peut exécuter la commande $statement: $dbh- >errstr\n";

Généralement, la commande 'do' est plus rapide (et préférable) à prepare/execute pour les requêtes ne contenant pas de paramètres.

quote($string)

La méthode quote est utilisée pour protéger les caractères spéciaux contenus dans la chaîne et ajouter les guillemets externes requis.Exemple :

$sql = $dbh->quote($string)

fetchrow_array

Cette méthode récupère la ligne de données suivante et la retourne en tant que tableau de valeurs de champs.Exemple :

while(@row = $sth->fetchrow_array) {         print qw($row[0]\t$row[1]\t$row[2]\n); }

fetchrow_arrayref

Cette méthode récupère la ligne de données suivante et la retourne en tant que référence de tableau de valeurs de champs.Exemple :

while($row_ref = $sth->fetchrow_arrayref) {         print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n); }

fetchrow_hashref

Cette méthode récupère la ligne de données et retourne une référence vers un tableau associatif contenant des paires nom du champ / valeur. Cette méthode n'est pas aussi efficace que l'utilisation des références sur tableaux comme expliqué plus haut.Exemple :

while($hash_ref = $sth->fetchrow_hashref) {         print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\                 $hash_ref- > title}\n); }

fetchall_arrayref

Cette méthode est utilisée pour faire en sorte que toutes les données (lignes) soient retournées par la requête SQL. Elle retourne une référence à un tableau de références à des tableaux pour chaque ligne. Vous pouvez accéder aux données en utilisant des boucles profondes.Exemple :

my $table = $sth->fetchall_arrayref                 or die "$sth->errstr\n"; my($i, $j); for $i ( 0 .. $#{$table} ) {         for $j ( 0 .. $#{$table->[$i]} ) {                 print "$table->[$i][$j]\t";         }         print "\n"; }

finish

Indique que plus aucune donnée ne sera récupérée du gestionnaire de requête. Vous appelez cette méthode pour libérer le gestionnaire de connexion et les ressources système lui étant associées.Exemple :

$rc = $sth->finish;

rows

Retourne le nombre de lignes changées (mises à jour, supprimées, etc.) par la dernière commande. En l'utilise généralement après les requêtes autres que SELECT exécutées avec la méthode execute .Exemple :

$rv = $sth->rows;

NULLABLE

Retourne une référence vers un tableau de valeurs qui indiquent si les colonnes peuvent contenir des valeurs NULL . Les valeurs possibles pour chaque élément sont 0 ou la chaîne vide si la colonne ne peut être NULL , 1 si elle peut, et 2 si l'état NULL de la colonne est inconnu.Exemple :

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

Cet attribut indique le nombre de champs retournés par une requête SELECT ou SHOW FIELDS . Vous pouvez l'utiliser pour savoir si une requête a retourné un résultat : une valeur nulle indique que la requête n'est pas une sélection, comme INSERT , DELETE , ou UPDATE .Exemple :

$nr_of_fields = $sth->{NUM_OF_FIELDS};

data_sources($driver_name)

Cette méthode retourne un tableau contenant les noms des bases de données disponibles pour le serveur MySQL sur l'hôte 'localhost' .Exemple :

@dbs = DBI->data_sources("mysql");

ChopBlanks

Cet attribut détermine si les méthodes fetchrow_* enlèvent les caractères blancs au début et à la fin des valeurs retournées.Exemple :

$sth->{'ChopBlanks'} =1;

trace($trace_level)

trace($trace_level, $trace_filename)

La méthode trace active ou désactive le traçage. Lorsqu'elle est invoquée en tant que méthode de la classe DBI , elle affecte le traçage à tout les gestionnaire. Lorsqu'elle est invoquée comme un gestionnaire de base de données ou de requête, elle n'affecte le traçage que pour le gestionnaire donné (et tout ses descendants). Mettre $trace_level à 2 fournit des informations détaillées de traçage. Le mettre à 0 désactive le traçage. Les sorties de traçages vont dans la sortie d'erreurs standards par défaut. Si $trace_filename est spécifié, le fichier est ouvert et le pointeur de fichier est placé à la fin de celui-ci et les sorties de tout les gestionnaires tracés sont écrits dans ce fichier.Exemple :

DBI->trace(2);                # trace tout DBI->trace(2,"/tmp/dbi.out"); # trace tout dans                               # /tmp/dbi.out $dth->trace(2);               # trace ce gestionnaire de base de données $sth->trace(2);               # trace ce gestionnaire de requête

Vous pouvez aussi activer le traçage DBI en définissant la variable d'environnement DBI_TRACE . La définir en tant que valeur numérique revient à appeler DBI->(value) . La définir en tant que chemin revient à appeler DBI->(2,value) .

Méthodes spécifiques à MySQL

insertid

Si vous utilisez la fonctionnalité AUTO_INCREMENT de MySQL, la nouvelle valeur auto-incrémentée sera stockée ici.Exemple :

$new_id = $sth->{insertid};

Vous pouvez, en alternative, utiliser $dbh->{'mysql_insertid'} .

is_blob

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est un BLOB .Exemple :

$keys = $sth->{is_blob};

is_key

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est une clef.Exemple :

$keys = $sth->{is_key};

is_num

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question contient une valeur numérique.Exemple :

$nums = $sth->{is_num};

is_pri_key

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est une clef primaire.Exemple :

$pri_keys = $sth->{is_pri_key};

is_not_null

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur FALSE indique que la colonne peut contenir NULL values.Exemple :

$not_nulls = $sth->{is_not_null};

is_not_null est désapprouvé; il est préférable d'utiliser l'attribut NULLABLE (décrit plus haut), car c'est un standard DBI.

length

max_length

Chacune de ces méthodes retourne une référence vers un tableau de tailles de colonnes. Le tableau length indique les tailles maximales de colonnes (comme déclarés lors de la création de la table). Le tableau max_length indique la plus grande taille occupée jusqu'à présent dans les colonnes de la table. Exemple :

$lengths = $sth->{length}; $max_lengths = $sth->{max_length};

NAME

Retourne une référence vers un tableau de noms de colonnes.Exemple :

$names = $sth->{NAME};

table

Retourne une référence vers un tableau de noms de tables.Exemple :

$tables = $sth->{table};

type

Retourne une référence vers un tableau de types de colonnes.Exemple :

$types = $sth->{type};