# Referencia de funciones para Extensiones de lenguaje de confianza para PostgreSQL Consulte la siguiente documentación de referencia sobre las funciones disponibles en Extensiones de lengua de confianza para PostgreSQL. Utilice estas funciones para instalar, registrar, actualizar y administrar sus *extensiones TLE*, es decir, las extensiones de PostgreSQL que desarrolla con el kit de desarrollo de Extensiones de lenguaje de confianza. **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(nombre, versión)](#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 función `pgtle.available_extensions` es una función de devolución de conjuntos. Devuelve todas las extensiones TLE disponibles en la base de datos. Cada fila devuelta contiene información sobre una sola extensión TLE. ### Prototipo de función ``` pgtle.available_extensions() ``` ### Rol Ninguna. ### Argumentos Ninguna. ### Salida + `name`: nombre de la extensión TLE. + `default_version`: versión de la extensión TLE que se utilizará cuando se llame a `CREATE EXTENSION` sin especificar una versión. + `description`: descripción más detallada acerca de la extensión TLE. ### Ejemplo de uso ``` SELECT * FROM pgtle.available_extensions(); ``` ## pgtle.available\$1extension\$1versions La función `available_extension_versions` es una función de devolución de conjuntos. Esta función devuelve una lista de todas las extensiones de TLE disponibles y sus versiones. Cada fila contiene información sobre una versión específica de la extensión TLE dada, incluso si requiere un rol específico. ### Prototipo de función ``` pgtle.available_extension_versions() ``` ### Rol Ninguna. ### Argumentos Ninguna. ### Salida + `name`: nombre de la extensión TLE. + `version`: versión de la extensión TLE. + `superuser`: este valor es siempre `false` para sus extensiones TLE. Los permisos necesarios para crear la extensión TLE o actualizarla son los mismos que para crear otros objetos en la base de datos dada. + `trusted`: este valor es siempre `false` para una extensión TLE. + `relocatable`: este valor es siempre `false` para una extensión TLE. + `schema`: especifica el nombre del esquema en el que está instalada la extensión TLE. + `requires`: matriz que contiene los nombres de otras extensiones que necesita esta extensión TLE. + `description`: descripción detallada de la extensión TLE. Para obtener más información acerca de los valores de salida, vea [Packaging Related Objects into an Extension > Extension Files](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (Empaquetar objetos relacionados en una extensión > Archivos de extensión) en la documentación de PostgreSQL. ### Ejemplo de uso ``` SELECT * FROM pgtle.available_extension_versions(); ``` ## pgtle.extension\$1update\$1paths La función `extension_update_paths` es una función de devolución de conjuntos. Devuelve una lista de todas las rutas de actualización posibles para una extensión TLE. Cada fila incluye las actualizaciones a un nivel superior o inferior disponibles para esa extensión TLE. ### Prototipo de función ``` pgtle.extension_update_paths(name) ``` ### Rol Ninguna. ### Argumentos `name`: nombre de la extensión TLE desde la que se obtienen las rutas de actualización. ### Salida + `source`: versión de origen de una actualización. + `target`: versión de destino de una actualización. + `path`: ruta de actualización utilizada para actualizar una extensión TLE de una versión `source` a otra `target`, por ejemplo, `0.1--0.2`. ### Ejemplo de uso ``` SELECT * FROM pgtle.extension_update_paths('your-TLE'); ``` ## pgtle.install\$1extension La función `install_extension` le permite instalar los artefactos que componen la extensión TLE en la base de datos, después de lo cual se puede crear mediante el comando `CREATE EXTENSION`. ### Prototipo de función ``` pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[]) ``` ### Rol Ninguna. ### Argumentos + `name`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `version`: versión de la extensión TLE. + `description`: descripción detallada acerca de la extensión TLE. Esta descripción se muestra en el campo `comment` de `pgtle.available_extensions()`. + `ext`: contenido de la extensión TLE. Este valor contiene objetos como funciones. + `requires`: parámetro opcional que especifica las dependencias de esta extensión TLE. La extensión `pg_tle` se añade automáticamente como una dependencia. Muchos de estos argumentos son los mismos que se incluyen en un archivo de control de extensiones para instalar una extensión de PostgreSQL en el sistema de archivos de una instancia de PostgreSQL. Para obtener más información acerca de las extensiones de PostgreSQL, vea [Extension Files](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (Archivos de extensión) en [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (Empaquetar objetos relacionados en una extensión) en la documentación de PostgreSQL. ### Salida Esta función devuelve `OK` en caso de éxito y `NULL` en caso de error. + `OK`: la extensión TLE se ha instalado correctamente en la base de datos. + `NULL`: la extensión TLE no se ha instalado correctamente en la base de datos. ### Ejemplo de uso ``` 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 función `install_update_path` proporciona una ruta de actualización entre dos versiones diferentes de una extensión TLE. Esta función permite a los usuarios de la extensión TLE actualizar su versión mediante la sintaxis `ALTER EXTENSION ... UPDATE`. ### Prototipo de función ``` pgtle.install_update_path(name text, fromvers text, tovers text, ext text) ``` ### Rol `pgtle_admin` ### Argumentos + `name`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `fromvers`: versión de origen de la extensión TLE utilizada para la actualización. + `tovers`: versión de destino de la extensión TLE utilizada para la actualización. + `ext`: contenido de la actualización. Este valor contiene objetos como funciones. ### Salida Ninguna. ### Ejemplo de uso ``` 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 función `register_feature` añade la característica interna de PostgreSQL especificada a la tabla `pgtle.feature_info`. Los enlaces de PostgreSQL son un ejemplo de una característica interna de PostgreSQL. El kit de desarrollo de Extensiones de lenguaje de confianza admite el uso de enlaces de PostgreSQL. Actualmente, esta función admite la siguiente característica. + `passcheck`: registra el enlace de comprobación de contraseñas con su procedimiento o función que personaliza el comportamiento de comprobación de contraseñas de PostgreSQL. ### Prototipo de función ``` pgtle.register_feature(proc regproc, feature pg_tle_feature) ``` ### Rol `pgtle_admin` ### Argumentos + `proc`: nombre de un procedimiento o función almacenados que se utilizarán en la característica. + `feature`: nombre de una característica `pg_tle` (como `passcheck`) para registrarla con la función. ### Salida Ninguna. ### Ejemplo de uso ``` SELECT pgtle.register_feature('pw_hook', 'passcheck'); ``` ## pgtle.register\$1feature\$1if\$1not\$1exists La función `pgtle.register_feature_if_not_exists` añade la función de PostgreSQL especificada a la tabla `pgtle.feature_info` e identifica la extensión TLE u otro procedimiento o función que utilice la característica. Para obtener más información sobre los enlaces y las extensiones de lenguaje de confianza, consulte[Uso de enlaces de PostgreSQL con sus extensiones TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). ### Prototipo de función ``` pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature) ``` ### Rol `pgtle_admin` ### Argumentos + `proc`: nombre de una función procedimiento almacenado que contiene la lógica (código) que se utilizará como una característica de la extensión TLE. Por ejemplo, el código `pw_hook`. + `feature`: nombre de una la característica de PostgreSQL para registrarla para la función TLE. Actualmente, la única característica disponible es el enlace `passcheck`. Para obtener más información, consulte [Enlace de comprobación de contraseñas (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook). ### Salida Devuelve `true` después de registrar la característica para la extensión especificada. Devuelve `false` si la característica ya está registrada. ### Ejemplo de uso ``` SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck'); ``` ## pgtle.set\$1default\$1version La función `set_default_version` le permite especificar un `default_version` para su extensión TLE. Puede utilizar esta función para definir una ruta de actualización y designar la versión como la predeterminada para la extensión TLE. Cuando los usuarios de la base de datos especifican la extensión TLE en los comandos `CREATE EXTENSION` y `ALTER EXTENSION ... UPDATE`, esa versión de la extensión TLE se crea en la base de datos para ese usuario. Esta función devuelve `true` en caso de realizarse correctamente. Si la extensión TLE especificada en el argumento `name` no existe, la función devuelve un error. Del mismo modo, si el `version` de la extensión TLE no existe, devuelve un error. ### Prototipo de función ``` pgtle.set_default_version(name text, version text) ``` ### Rol `pgtle_admin` ### Argumentos + `name`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `version`: versión de la extensión TLE para establecer la predeterminada. ### Salida + `true`: cuando la configuración de la versión predeterminada se realiza correctamente, la función devuelve `true`. + `ERROR`: devuelve un mensaje de error si no existe una extensión TLE con el nombre o la versión especificados. ### Ejemplo de uso ``` SELECT * FROM pgtle.set_default_version('my-extension', '1.1'); ``` ## pgtle.uninstall\$1extension(name) La función `uninstall_extension` elimina todas las versiones de una extensión TLE de una base de datos. Esta función evita futuras llamadas de `CREATE EXTENSION` para evitar instalar la extensión TLE. Si la extensión TLE no existe en la base de datos, se genera un error. La función `uninstall_extension` no elimina una extensión TLE que esté activa actualmente en la base de datos. Para eliminar una extensión TLE que está activa actualmente, debes llamar explícitamente a `DROP EXTENSION` para eliminarla. ### Prototipo de función ``` pgtle.uninstall_extension(extname text) ``` ### Rol `pgtle_admin` ### Argumentos + `extname`: nombre de la extensión TLE que se va a desinstalar. Este nombre es el mismo que se usó con `CREATE EXTENSION` para cargar la extensión TLE para usarla en una base de datos determinada. ### Salida Ninguna. ### Ejemplo de uso ``` SELECT * FROM pgtle.uninstall_extension('pg_tle_test'); ``` ## pgtle.uninstall\$1extension(nombre, versión) La función `uninstall_extension(name, version)` elimina la versión especificada de la extensión TLE de la base de datos. Esta función impide a `CREATE EXTENSION` y `ALTER EXTENSION` instalar o actualizar una extensión TLE a la versión especificada. Esta función también elimina todas las rutas de actualización posibles de la extensión TLE especificada. Esta función no desinstala la extensión TLE si actualmente está activa en la base de datos. Debe llamar explícitamente a `DROP EXTENSION` para eliminar la extensión TLE. Para desinstalar todas las versiones de una extensión TLE, consulte [pgtle.uninstall\$1extension(name)](#pgtle.uninstall_extension-name). ### Prototipo de función ``` pgtle.uninstall_extension(extname text, version text) ``` ### Rol `pgtle_admin` ### Argumentos + `extname`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `version`: versión de la extensión TLE que se va a desinstalar de la base de datos. ### Salida Ninguna. ### Ejemplo de uso ``` SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2'); ``` ## pgtle.uninstall\$1extension\$1if\$1exists La función `uninstall_extension_if_exists` elimina todas las versiones de una extensión TLE de una base de datos determinada. Si la extensión TLE no existe, la función la devuelve en silencio (no se genera ningún mensaje de error). Si la extensión especificada está activa actualmente en una base de datos, esta función no la elimina. Debe llamar explícitamente a `DROP EXTENSION` para eliminar la extensión TLE antes de utilizar esta función para desinstalar sus artefactos. ### Prototipo de función ``` pgtle.uninstall_extension_if_exists(extname text) ``` ### Rol `pgtle_admin` ### Argumentos + `extname`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. ### Salida La función `uninstall_extension_if_exists` de vuelve `true` después de desinstalar la extensión especificada. Si la extensión especificada no existe, la función devuelve `false`. + `true`: devuelve `true` después de desinstalar la extensión TLE. + `false`: devuelve `false` cuando la extensión TLE no existe en la base de datos. ### Ejemplo de uso ``` SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test'); ``` ## pgtle.uninstall\$1update\$1path La función `uninstall_update_path` elimina la ruta de actualización específica de una extensión TLE. Esto impide que `ALTER EXTENSION ... UPDATE TO` se utilice como ruta de actualización. Si una de las versiones de esta ruta de actualización utiliza actualmente la extensión TLE, permanecerá en la base de datos. Si la ruta de actualización especificada no existe, esta función genera un error. ### Prototipo de función ``` pgtle.uninstall_update_path(extname text, fromvers text, tovers text) ``` ### Rol `pgtle_admin` ### Argumentos + `extname`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `fromvers`: versión de origen de la extensión TLE utilizada en la ruta de actualización. + `tovers`: versión de destino de la extensión TLE utilizada en la ruta de actualización. ### Salida Ninguna. ### Ejemplo de uso ``` SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2'); ``` ## pgtle.uninstall\$1update\$1path\$1if\$1exists La función `uninstall_update_path_if_exists` es similar a `uninstall_update_path` en el sentido de que elimina la ruta de actualización especificada de una extensión TLE. Sin embargo, si la ruta de actualización no existe, esta función no generará ningún mensaje de error. En su lugar, la función devuelve `false`. ### Prototipo de función ``` pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text) ``` ### Rol `pgtle_admin` ### Argumentos + `extname`: nombre de la extensión TLE. Este valor se utiliza cuando se llama a `CREATE EXTENSION`. + `fromvers`: versión de origen de la extensión TLE utilizada en la ruta de actualización. + `tovers`: versión de destino de la extensión TLE utilizada en la ruta de actualización. ### Salida + `true`: la función ha actualizado correctamente la ruta de la extensión TLE. + `false`: la función no ha podido actualizar la ruta de la extensión TLE. ### Ejemplo de uso ``` SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2'); ``` ## pgtle.unregister\$1feature La función `unregister_feature` proporciona una forma de eliminar las funciones que se han registrado para usar características `pg_tle`, como los enlaces. Para obtener información sobre el registro de una característica, consulte [pgtle.register\$1feature](#pgtle.register_feature). ### Prototipo de función ``` pgtle.unregister_feature(proc regproc, feature pg_tle_features) ``` ### Rol `pgtle_admin` ### Argumentos + `proc`: nombre de una función almacenada para registrarse en una característica de `pg_tle`. + `feature`: nombre de la característica `pg_tle` para registrarla con la función. Por ejemplo, `passcheck` es una característica que se puede registrar para que la utilicen las extensiones de lenguaje de confianza que desarrolle. Para obtener más información, consulte [Enlace de comprobación de contraseñas (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook). ### Salida Ninguna. ### Ejemplo de uso ``` SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck'); ``` ## pgtle.unregister\$1feature\$1if\$1exists La función `unregister_feature` proporciona una forma de eliminar las funciones que se registraron para usar funciones `pg_tle`, como los enlaces. Para obtener más información, consulte [Uso de enlaces de PostgreSQL con sus extensiones TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). Devuelve `true` después de anular satisfactoriamente el registro de la función. Devuelve `false` si la función no se ha registrado. Para obtener información sobre el registro de funciones `pg_tle` para sus extensiones TLE, consulte [pgtle.register\$1feature](#pgtle.register_feature). ### Prototipo de función ``` pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features') ``` ### Rol `pgtle_admin` ### Argumentos + `proc`: nombre de la función almacenada que se registró para incluir una función `pg_tle`. + `feature`: nombre de la función `pg_tle` que se registró con la extensión de lenguaje de confianza. ### Salida Devuelve `true` o `false`, de la siguiente manera. + `true`: la función ha cancelado satisfactoriamente el registro de la función de la extensión. + `false`: la función no ha podido anular el registro de la función de la extensión TLE. ### Ejemplo de uso ``` SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck'); ```