Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # 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. **Topics** + [pgtle.available\$1extensions](#pgtle.available_extensions) + [pgtle.available\$1extension\$1versions](#pgtle.available_extension_versions) + [pgtle.extension\$1update\$1paths](#pgtle.extension_update_paths) + [pgtle.install\$1extension](#pgtle.install_extension) + [pgtle.install\$1update\$1path](#pgtle.install_update_path) + [pgtle.register\$1feature](#pgtle.register_feature) + [pgtle.register\$1feature\$1if\$1not\$1exists](#pgtle.register_feature_if_not_exists) + [pgtle.set\$1default\$1version](#pgtle.set_default_version) + [pgtle.uninstall\$1extension(name)](#pgtle.uninstall_extension-name) + [pgtle.uninstall\$1extension(name, version)](#pgtle.uninstall_extension-name-version) + [pgtle.uninstall\$1extension\$1if\$1exists](#pgtle.uninstall_extension_if_exists) + [pgtle.uninstall\$1update\$1path](#pgtle.uninstall_update_path) + [pgtle.uninstall\$1update\$1path\$1if\$1exists](#pgtle.uninstall_update_path_if_exists) + [pgtle.unregister\$1feature](#pgtle.unregister_feature) + [pgtle.unregister\$1feature\$1if\$1exists](#pgtle.unregister_feature_if_exists) ## pgtle.available\$1extensions 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\$1extension\$1versions 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](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (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\$1update\$1paths 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\$1extension 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](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (Fichiers d'extension) dans [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (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\$1update\$1path 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\$1feature 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\$1feature\$1if\$1not\$1exists 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](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). ### 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)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook). ### 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\$1default\$1version 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\$1extension(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\$1extension(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\$1extension(name)](#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\$1extension\$1if\$1exists 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\$1update\$1path 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\$1update\$1path\$1if\$1exists 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\$1feature 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\$1feature](#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)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook). ### Sortie Aucune. ### Exemple d'utilisation ``` SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck'); ``` ## pgtle.unregister\$1feature\$1if\$1exists 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](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). 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\$1feature](#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'); ```