38.3. Acc�s � la base de donn�es

Le module du langage PL/Python importe automatiquement un module Python appel� plpy. Les fonctions et constantes de ce module vous sont accessibles dans le code Python via plpy.foo. Actuellement, plpy impl�mente les fonctions plpy.debug(msg), plpy.log(msg), plpy.info(msg), plpy.notice(msg), plpy.warning(msg), plpy.error(msg) et plpy.fatal(msg). plpy.error et plpy.fatal("msg") l�vent une exception Python qui, si non attrap�e, se propage � la requ�te appelante causant l'annulation de la transaction ou sous-transaction en cours. raise plpy.ERROR(msg) et raise plpy.FATAL(msg) sont �quivalent � appeler, respectivement, plpy.error et plpy.fatal. Les autres fonctions g�n�rent uniquement des messages de niveaux de priorit� diff�rents. Que les messages d'une priorit� particuli�re soient report�s au client, �crit dans les journaux du serveur ou les deux, cette configuration est contr�l�e par les variables log_min_messages et client_min_messages. Voir le Section 16.4 pour plus d'informations.

De plus, le module plpy fournit deux fonctions appel�es execute et prepare. Appeler plpy.execute avec une cha�ne de requ�te et un argument de limite optionnel fait que la requ�te est lanc�e et que le r�sultat est renvoy� dans un objet r�sultat. L'objet r�sultat �mule une liste ou un objet dictionnaire. L'objet r�sultat est accessible par le num�ro de ligne et le nom de la colonne. Il a plusieurs m�thodes suppl�mentaires : nrows qui renvoie le nombre de lignes retourn�es par la requ�te et status qui est le code de retour de SPI_execute(). L'objet r�sultat peut �tre modifi�.

Par exemple,

rv = plpy.execute("SELECT * FROM ma_table", 5)

renvoie cinq lignes de ma_table. Si ma_table dispose d'une colonne ma_colonne, elle sera accessible avec

foo = rv[i]["ma_colonne"]

La seconde fonction, plpy.prepare, pr�pare le plan d'ex�cution pour une requ�te. Il est appel� avec une cha�ne contenant la requ�te et une liste des types de param�tres si vous avez des r�f�rences de param�tres dans la requ�te. Par exemple :

plan = plpy.prepare("SELECT nom FROM mes_utilisateurs WHERE prenom = $1", [
"text" ])

text est le type de la variable que vous voulez passer via $1. Apr�s avoir pr�par� une instruction, vous utilisez la fonction plpy.execute pour l'ex�cuter :

rv = plpy.execute(plan, [ "nom" ], 5)

Le troisi�me argument est la limite et est optionnelle.

Lorsque vous pr�parez un plan en utilisant le module PL/Python, il est automatiquement sauvegard�. Lisez la documentation SPI (Chapitre 39) pour une description de ce que cela signifie. Pour faire r�ellement usage de ceci dans les appels de fonction, vous avez besoin d'utiliser un des dictionnaires � stockage permanent SD ou GD (voir le Section 38.1). Par exemple :

CREATE FUNCTION utiliseplansauvegarde() RETURNS trigger AS $$
    if SD.has_key("plan"):
        plan = SD["plan"]
    else:
        plan = plpy.prepare("SELECT 1")
        SD["plan"] = plan
    # reste de la fonction
$$ LANGUAGE plpythonu;