Référence de fonction pour Trusted Language Extensions pour PostgreSQL - Amazon Relational Database Service
pgtle.available_extensionspgtle.available_extension_versionspgtle.extension_update_pathspgtle.install_extensionpgtle.install_update_pathpgtle.register_featurepgtle.register_feature_if_not_existspgtle.set_default_versionpgtle.uninstall_extensionpgtle.uninstall_extensionpgtle.uninstall_extension_if_existspgtle.uninstall_update_pathpgtle.uninstall_update_path_if_existspgtle.unregister_featurepgtle.unregister_feature_if_exists

Référence de fonction pour Trusted Language Extensions pour PostgreSQL

Consultez la documentation de référence suivante sur les fonctions disponibles dans Trusted Language Extensions pour PostgreSQL. Utilisez ces fonctions pour installer, enregistrer, mettre à jour et gérer vos extensions TLE, c'est-à-dire les extensions PostgreSQL que vous développez à l'aide du kit de développement Trusted Language Extensions.

pgtle.available_extensions

La fonction pgtle.available_extensions est une fonction à renvoi d'ensemble. Elle renvoie toutes les extensions TLE disponibles dans la base de données. Chaque ligne renvoyée contient des informations sur une seule extension TLE.

Prototype de fonction

pgtle.available_extensions()

Rôle

Aucune.

Arguments

Aucune.

Sortie

  • name : nom de l'extension TLE.

  • default_version : la version de l'extension TLE à utiliser lorsque la commande CREATE EXTENSION est appelée sans version spécifiée.

  • description : une description plus détaillée de l'extension TLE.

Exemple d'utilisation

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

La fonction available_extension_versions est une fonction à renvoi d'ensemble. Elle renvoie une liste de toutes les extensions TLE disponibles et de leurs versions. Chaque ligne contient des informations sur une version spécifique de l'extension TLE donnée, y compris si elle nécessite un rôle spécifique.

Prototype de fonction

pgtle.available_extension_versions()

Rôle

Aucune.

Arguments

Aucune.

Sortie

  • name : nom de l'extension TLE.

  • version : version de l'extension TLE.

  • superuser : cette valeur est toujours false pour vos extensions TLE. Les autorisations nécessaires pour créer l'extension TLE ou la mettre à jour sont les mêmes que pour la création d'autres objets dans la base de données donnée.

  • trusted : cette valeur est toujours false pour une extension TLE.

  • relocatable : cette valeur est toujours false pour une extension TLE.

  • schema : spécifie le nom du schéma dans lequel l'extension TLE est installée.

  • requires : tableau contenant les noms des autres extensions requises par cette extension TLE.

  • description : description détaillée de l'extension TLE.

Pour obtenir plus d'informations sur les valeurs de sortie, consultez la section Packaging Related Objects into an Extension > Extension Files (Packaging des objets connexes dans une extension > Fichiers d'extension) dans la documentation de PostgreSQL.

Exemple d'utilisation

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

La fonction extension_update_paths est une fonction à renvoi d'ensemble. Elle renvoie une liste de tous les chemins de mise à jour possibles pour une extension TLE. Chaque ligne comprend les mises à niveau ou les rétrogradations disponibles pour cette extension TLE.

Prototype de fonction

pgtle.extension_update_paths(name)

Rôle

Aucune.

Arguments

name : nom de l'extension TLE à partir de laquelle obtenir les chemins de mise à niveau.

Sortie

  • source : version source d'une mise à jour.

  • target : version cible d'une mise à jour.

  • path : chemin de mise à niveau utilisé pour mettre à jour une extension TLE d'une version source à une version target, par exemple, 0.1--0.2.

Exemple d'utilisation

SELECT * FROM pgtle.extension_update_paths('your-TLE');

pgtle.install_extension

La fonction install_extension vous permet d'installer les artefacts qui composent votre extension TLE dans la base de données, après quoi elle peut être créée à l'aide de la commande CREATE EXTENSION.

Prototype de fonction

pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])

Rôle

Aucune.

Arguments

  • name : nom de l'extension TLE. Cette valeur est utilisée lors d’un appel de CREATE EXTENSION.

  • version : version de l'extension TLE.

  • description : description détaillée de l'extension TLE. Cette description est affichée dans le champ comment de pgtle.available_extensions().

  • ext : contenu de l'extension TLE. Cette valeur contient des objets tels que des fonctions.

  • requires : paramètre facultatif qui spécifie les dépendances pour cette extension TLE. L'extension pg_tle est automatiquement ajoutée en tant que dépendance.

Plusieurs de ces arguments sont les mêmes que ceux qui sont inclus dans un fichier de contrôle d'extension pour installer une extension PostgreSQL sur le système de fichiers d'une instance PostgreSQL. Pour plus d'informations, consultez Extension Files (Fichiers d'extension) dans Packaging Related Objects into an Extension (Packaging des objets connexes dans une extension) de la documentation PostgreSQL.

Sortie

Cette fonction renvoie OK en cas de réussite ou NULL en cas d'erreur.

  • OK : l'extension TLE a été installée avec succès dans la base de données.

  • NULL : l'extension TLE n'a pas été installée dans la base de données.

Exemple d'utilisation

SELECT pgtle.install_extension(
 'pg_tle_test',
 '0.1',
 'My first pg_tle extension',
$_pgtle_$
  CREATE FUNCTION my_test()
  RETURNS INT
  AS $$
    SELECT 42;
  $$ LANGUAGE SQL IMMUTABLE;
$_pgtle_$
);

pgtle.install_update_path

La fonction install_update_path fournit un chemin de mise à jour entre deux versions différentes d'une extension TLE. Cette fonction permet aux utilisateurs de votre extension TLE de mettre à jour sa version en utilisant la syntaxe ALTER EXTENSION ... UPDATE.

Prototype de fonction

pgtle.install_update_path(name text, fromvers text, tovers text, ext text)

Rôle

pgtle_admin

Arguments

  • name : nom de l'extension TLE. Cette valeur est utilisée lors d’un appel de CREATE EXTENSION.

  • fromvers : version source de l'extension TLE pour la mise à niveau.

  • tovers : version de destination de l'extension TLE pour la mise à niveau.

  • ext : contenu de la mise à jour. Cette valeur contient des objets tels que des fonctions.

Sortie

Aucune.

Exemple d'utilisation

SELECT pgtle.install_update_path('pg_tle_test', '0.1', '0.2',
  $_pgtle_$
    CREATE OR REPLACE FUNCTION my_test()
    RETURNS INT
    AS $$
      SELECT 21;
    $$ LANGUAGE SQL IMMUTABLE;
  $_pgtle_$
);

pgtle.register_feature

La fonction register_feature ajoute la fonctionnalité interne PostgreSQL spécifiée à la table pgtle.feature_info. Les hooks PostgreSQL sont un exemple de fonctionnalité interne de PostgreSQL. Le kit de développement Trusted Language Extensions prend en charge l'utilisation des hooks PostgreSQL. Actuellement, cette fonction prend en charge la fonctionnalité suivante.

  • passcheck : enregistre le hook de vérification de mot de passe avec votre procédure ou fonction qui personnalise le comportement de vérification de mot de passe de PostgreSQL.

Prototype de fonction

pgtle.register_feature(proc regproc, feature pg_tle_feature)

Rôle

pgtle_admin

Arguments

  • proc : nom d'une procédure ou d'une fonction stockée à utiliser pour la fonctionnalité.

  • feature : nom de la fonctionnalité pg_tle (tel que passcheck) à enregistrer avec la fonction.

Sortie

Aucune.

Exemple d'utilisation

SELECT pgtle.register_feature('pw_hook', 'passcheck');

pgtle.register_feature_if_not_exists

La fonction pgtle.register_feature_if_not_exists ajoute la fonctionnalité PostgreSQL spécifiée à la table pgtle.feature_info et identifie l'extension TLE ou toute autre procédure ou fonction qui utilise la fonctionnalité. Pour plus d'informations sur les hooks et le kit Trusted Language Extensions, consultez Utilisation des hooks PostgreSQL avec vos extensions TLE.

Prototype de fonction

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

Rôle

pgtle_admin

Arguments

  • proc : nom d'une procédure ou d'une fonction stockée qui contient la logique (code) à utiliser comme fonctionnalité pour votre extension TLE. Par exemple, le code pw_hook.

  • feature : nom de la fonctionnalité PostgreSQL à enregistrer pour la fonction TLE. Actuellement, la seule fonctionnalité disponible est le hook passcheck. Pour plus d’informations, consultez Crochet de vérification du mot de passe (passcheck).

Sortie

Renvoie true après l'enregistrement de la fonction pour l'extension spécifiée. Renvoie false si la fonctionnalité est déjà enregistrée.

Exemple d'utilisation

SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck');

pgtle.set_default_version

La fonction set_default_version vous permet de spécifier une valeur default_version pour votre extension TLE. Vous pouvez utiliser cette fonction pour définir un chemin de mise à niveau et désigner la version comme étant la version par défaut pour votre extension TLE. Lorsque les utilisateurs de la base de données spécifient votre extension TLE dans les commandes CREATE EXTENSION et ALTER EXTENSION ... UPDATE, cette version de votre extension TLE est créée dans la base de données pour cet utilisateur.

Cette fonction renvoie true en cas de réussite. Si l'extension TLE spécifiée dans l'argument name n'existe pas, la fonction renvoie une erreur. De même, si la version de l'extension TLE n'existe pas, elle renvoie une erreur.

Prototype de fonction

pgtle.set_default_version(name text, version text)

Rôle

pgtle_admin

Arguments

  • name : nom de l'extension TLE. Cette valeur est utilisée lors d’un appel de CREATE EXTENSION.

  • version : version de l'extension TLE à définir par défaut.

Sortie

  • true : lorsque la définition de la version par défaut réussit, la fonction renvoie true.

  • ERROR : renvoie un message d'erreur si une extension TLE avec le nom ou la version spécifiés n'existe pas.

Exemple d'utilisation

SELECT * FROM pgtle.set_default_version('my-extension', '1.1');

pgtle.uninstall_extension(name)

La fonction uninstall_extension supprime toutes les versions d'une extension TLE d'une base de données. Cette fonction empêche les appels futurs de CREATE EXTENSION d'installer l'extension TLE. Si l'extension TLE n'existe pas dans la base de données, une erreur est signalée.

La fonction uninstall_extension n'abandonne pas une extension TLE qui est actuellement active dans la base de données. Pour supprimer une extension TLE actuellement active, vous devez appeler explicitement DROP EXTENSION.

Prototype de fonction

pgtle.uninstall_extension(extname text)

Rôle

pgtle_admin

Arguments

  • extname : nom de l'extension TLE à désinstaller. Ce nom est le même que celui utilisé avec CREATE EXTENSION pour charger l'extension TLE à utiliser dans une base de données spécifiée.

Sortie

Aucune.

Exemple d'utilisation

SELECT * FROM pgtle.uninstall_extension('pg_tle_test');

pgtle.uninstall_extension(name, version)

La fonction uninstall_extension(name, version) supprime la version spécifiée de l'extension TLE de la base de données. Cette fonction empêche CREATE EXTENSION et ALTER EXTENSION d'installer ou de mettre à jour une extension TLE à la version spécifiée. Cette fonction supprime également tous les chemins de mise à jour pour la version spécifiée de l'extension TLE. Cette fonction ne désinstallera pas l'extension TLE si elle est actuellement active dans la base de données. Vous devez appeler explicitement DROP EXTENSION pour retirer l'extension TLE. Pour désinstaller toutes les versions d'une extension TLE, consultez pgtle.uninstall_extension(name).

Prototype de fonction

pgtle.uninstall_extension(extname text, version text)

Rôle

pgtle_admin

Arguments

  • extname : nom de l'extension TLE. Cette valeur est utilisée lors d'un appel de CREATE EXTENSION.

  • version : la version de l'extension TLE à désinstaller de la base de données.

Sortie

Aucune.

Exemple d'utilisation

SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2');

pgtle.uninstall_extension_if_exists

La fonction uninstall_extension_if_exists supprime toutes les versions d'une extension TLE d'une base de données spécifiée. Si l'extension TLE n'existe pas, la fonction ne renvoie rien (aucun message d'erreur n'est affiché). Si l'extension spécifiée est actuellement active dans une base de données, cette fonction ne la supprime pas. Vous devez explicitement appeler DROP EXTENSION pour supprimer l'extension TLE avant d'utiliser cette fonction pour désinstaller ses artefacts.

Prototype de fonction

pgtle.uninstall_extension_if_exists(extname text)

Rôle

pgtle_admin

Arguments

  • extname : nom de l'extension TLE. Cette valeur est utilisée lors d’un appel de CREATE EXTENSION.

Sortie

La fonction uninstall_extension_if_exists renvoie true après avoir désinstallé l'extension spécifiée. Si l'extension spécifiée n'existe pas, la fonction renvoie false.

  • true : renvoie true après la désinstallation de l'extension TLE.

  • false : renvoie false lorsque l'extension TLE n'existe pas dans la base de données.

Exemple d'utilisation

SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test');

pgtle.uninstall_update_path

La fonction uninstall_update_path supprime le chemin de mise à jour spécifique pour l'extension TLE. Cela empêche ALTER EXTENSION ... UPDATE TO de l'utiliser comme chemin de mise à jour.

Si l'extension TLE est actuellement utilisée par l'une des versions de ce chemin de mise à jour, elle reste dans la base de données.

Si le chemin de mise à jour spécifié n'existe pas, cette fonction génère une erreur.

Prototype de fonction

pgtle.uninstall_update_path(extname text, fromvers text, tovers text)

Rôle

pgtle_admin

Arguments

  • extname : nom de l'extension TLE. Cette valeur est utilisée lors de l'appel de CREATE EXTENSION.

  • fromvers : la version source de l'extension TLE utilisée sur le chemin de mise à jour.

  • tovers : la version destination de l'extension TLE utilisée sur le chemin de mise à jour.

Sortie

Aucune.

Exemple d'utilisation

SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2');

pgtle.uninstall_update_path_if_exists

La fonction uninstall_update_path_if_exists est similaire à uninstall_update_path, car elle supprime le chemin de mise à jour spécifié d'une extension TLE. Toutefois, si le chemin de mise à jour n'existe pas, cette fonction ne renvoie pas de message d'erreur. Au lieu de cela, la fonction renvoie false.

Prototype de fonction

pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text)

Rôle

pgtle_admin

Arguments

  • extname : nom de l'extension TLE. Cette valeur est utilisée lors de l'appel de CREATE EXTENSION.

  • fromvers : la version source de l'extension TLE utilisée sur le chemin de mise à jour.

  • tovers : la version destination de l'extension TLE utilisée sur le chemin de mise à jour.

Sortie

  • true : la fonction a mis à jour avec succès le chemin pour l'extension TLE.

  • false : la fonction n'a pas pu mettre à jour le chemin pour l'extension TLE.

Exemple d'utilisation

SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2');

pgtle.unregister_feature

La fonction unregister_feature permet de supprimer les fonctions qui ont été enregistrées pour utiliser des fonctionnalités pg_tle, telles que les hooks. Pour obtenir des informations sur l'enregistrement d'une fonctionnalité, consultez pgtle.register_feature.

Prototype de fonction

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

Rôle

pgtle_admin

Arguments

  • proc : nom d'une fonction stockée à enregistrer avec une fonctionnalité pg_tle.

  • feature : nom de la fonctionnalité pg_tle à enregistrer avec la fonction. Par exemple, passcheck est une fonctionnalité qui peut être enregistrée pour être utilisée par les extensions Trusted Language Extensions (TLE) que vous développez. Pour plus d’informations, consultez Crochet de vérification du mot de passe (passcheck).

Sortie

Aucune.

Exemple d'utilisation

SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');

pgtle.unregister_feature_if_exists

La fonction unregister_feature permet de supprimer les fonctions qui ont été enregistrées pour utiliser des fonctionnalités pg_tle, telles que les hooks. Pour plus d’informations, consultez Utilisation des hooks PostgreSQL avec vos extensions TLE. Renvoie true après avoir réussi à annuler l'enregistrement de la fonctionnalité. Renvoie false si la fonctionnalité n'a pas été enregistrée.

Pour obtenir des informations sur l'enregistrement de fonctionnalités pg_tle pour vos extensions TLE, consultez pgtle.register_feature.

Prototype de fonction

pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')

Rôle

pgtle_admin

Arguments

  • proc : nom de la fonction stockée qui a été enregistrée pour inclure une fonctionnalité pg_tle.

  • feature : nom de la fonctionnalité pg_tle qui a été enregistrée avec l'extension de langage approuvé.

Sortie

Renvoie true ou false, comme suit.

  • true : la fonction a annulé l'enregistrement de la fonctionnalité à l'extension.

  • false : la fonction n'a pas pu annuler l'enregistrement de la fonctionnalité à l'extension TLE.

Exemple d'utilisation

SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck');