# Uso de Extensiones de lenguaje de confianza para PostgreSQL
Extensiones de lenguaje de confianza para PostgreSQL es un kit de desarrollo de código abierto para crear extensiones de PostgreSQL. Le permite crear extensiones de PostgreSQL de alto rendimiento y ejecutarlas de forma segura en su instancia de base de datos de RDS para PostgreSQL. Al utilizar Extensiones de lenguaje de confianza (TLE) para PostgreSQL, puede crear extensiones de PostgreSQL que sigan el enfoque documentado para ampliar la funcionalidad de PostgreSQL. Para obtener más información, consulte el punto [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.
Una ventaja clave de TLE es que se puede utilizar en entornos que no proporcionan acceso al sistema de archivos subyacente a la instancia de PostgreSQL. Anteriormente, la instalación de una nueva extensión requería acceso al sistema de archivos. TLE elimina esta restricción. Pues proporciona un entorno de desarrollo para crear nuevas extensiones para cualquier base de datos de PostgreSQL, incluidas las que se ejecutan en los instancias de base de datos de RDS para PostgreSQL.
TLE está diseñado para evitar el acceso a recursos no seguros para las extensiones que se crean con TLE. Su entorno de ejecución limita el impacto de cualquier defecto de extensión a una única conexión de base de datos. TLE también proporciona a los administradores de bases de datos un control preciso sobre quién puede instalar las extensiones y proporciona un modelo de permisos para ejecutarlas.
TLE es compatible con las siguientes versiones de RDS para PostgreSQL:
+ Versión 18.1 y versiones posteriores a 18
+ Versión 17.1 y otras versiones 17 superiores
+ Versión 16.1 y versiones posteriores a 16
+ Versión 15.2 y versiones posteriores a 15
+ Versión 14.5 y versiones posteriores a 14
+ Versión 13.12 y versiones posteriores a 13
El entorno de desarrollo y el entorno de ejecución de Extensiones de lenguaje de confianza se empaquetan como la extensión `pg_tle` de PostgreSQL, versión 1.0.1. Admite la creación de extensiones en JavaScript, Perl, Tcl, PL/pgSQL y SQL. La extensión `pg_tle` se instala en la instancia de base de datos de RDS para PostgreSQL del mismo modo que se instalan otras extensiones de PostgreSQL. Una vez configurada `pg_tle`, los desarrolladores pueden usarla para crear nuevas extensiones de PostgreSQL, conocidas como *extensiones TLE*.
En los temas siguientes, encontrará información sobre cómo configurar Extensiones de lenguaje de confianza y cómo comenzar a crear sus propias extensiones TLE.
**Topics**
+ [Terminología](PostgreSQL_trusted_language_extension-terminology.md)
+ [Requisitos para usar Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-requirements.md)
+ [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md)
+ [Información general de Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension.overview.md)
+ [Creación de extensiones TLE para RDS para PostgreSQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md)
+ [Eliminar las extensiones TLE de una base de datos](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md)
+ [Desinstalación de Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-uninstalling-pg_tle-devkit.md)
+ [Uso de enlaces de PostgreSQL con sus extensiones TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)
+ [Uso de tipos de datos personalizados en TLE](PostgreSQL_trusted_language_extension-custom-data-type.md)
+ [Referencia de funciones para Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-functions-reference.md)
+ [Referencia de enlaces para Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-hooks-reference.md)
# Terminología
Para entender mejor Extensiones de lenguaje de confianza, consulta el siguiente glosario para ver los términos utilizados en este tema.
**Extensiones de lenguaje de confianza para PostgreSQL**
*Extensiones de lenguaje de confianza para PostgreSQL* es el nombre oficial del kit de desarrollo de código abierto que se incluye como extensión `pg_tle`. Está disponible para su uso en cualquier sistema PostgreSQL. Para obtener más información, consulte [aws/pg\$1tle](https://github.com/aws/pg_tle) en GitHub.
**Extensiones de lenguaje de confianza**
*Extensiones de lenguaje de confianza* es la versión abreviada de Extensiones de lenguaje de confianza para PostgreSQL. En esta documentación se utilizan el nombre abreviado y sus siglas (TLE).
**lenguaje de confianza**
Un *lenguaje de confianza* es un lenguaje de programación o de scripting que tiene atributos de seguridad específicos. Por ejemplo, los lenguajes de confianza suelen restringir el acceso al sistema de archivos y limitan el uso de las propiedades de red especificadas. El kit de desarrollo TLE está diseñado para ser compatible con lenguajes de confianza. PostgreSQL admite varios lenguajes diferentes que se utilizan para crear extensiones fiables o no fiables. Para ver un ejemplo, consulte el punto [Trusted and Untrusted PL/Perl](https://www.postgresql.org/docs/current/plperl-trusted.html) (PL/Perl fiable y no fiable) en la documentación de PostgreSQL. Al crear una extensión con Extensiones de lenguaje de confianza, la extensión utiliza mecanismos de lenguaje de confianza de forma inherente.
**Extensión TLE**
Una *extensión TLE* es una extensión de PostgreSQL que se ha creado mediante el kit de desarrollo de Extensiones de lenguaje de confianza (TLE).
# Requisitos para usar Extensiones de lenguaje de confianza para PostgreSQL
Estos son los requisitos para configurar y usar el kit de desarrollo TLE.
+ ** Versiones de RDS para PostgreSQL**: las extensiones de lenguaje de confianza se admiten en RDS para PostgreSQL versiones 13.12 y versiones 13 posteriores, 14.5 y versiones 14 posteriores, y 15.2 y versiones posteriores únicamente.
+ Si necesita actualizar su instancia de RDS para PostgreSQL, consulte [Actualizaciones del motor de base de datos de RDS para PostgreSQL](USER_UpgradeDBInstance.PostgreSQL.md).
+ Si aún no tiene un clúster de base de datos de Aurora que ejecute PostgreSQL, puede crear una. Para obtener más información, consulte Instancia de base de datos de RDS para PostgreSQL, consulte [Creación de una instancia de base de datos de PostgreSQL y conexión a ella](CHAP_GettingStarted.CreatingConnecting.PostgreSQL.md).
+ **Requiere privilegios de `rds_superuser`**: para instalar y configurar la extensión `pg_tle`, el rol de usuario de la base de datos debe tener permisos del rol `rds_superuser`. De forma predeterminada, este rol se otorga al usuario `postgres` que crea el Instancia de base de datos RDS para PostgreSQL.
+ **Requiere un grupo de parámetros de base de datos personalizado**: su instancia de base de datos de RDS para PostgreSQL debe configurarse con un grupo de parámetros de base de datos personalizado.
+ Si su instancia de base de datos de RDS para PostgreSQL no está configurado con un grupo de parámetros de base de datos personalizado, debe crear uno y asociarlo su instancia de base de datos de RDS para PostgreSQL. Para obtener un breve resumen de los pasos, consulte [Creación y aplicación de un grupo de parámetros de base de datos personalizado](#PostgreSQL_trusted_language_extension-requirements-create-custom-params).
+ Si su instancia de base de datos de RDS para PostgreSQL ya se ha configurado con un grupo de parámetros de base de datos personalizado, puede configurar Extensiones de lenguaje de confianza. Para obtener más información, consulte [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
## Creación y aplicación de un grupo de parámetros de base de datos personalizado
Siga los siguientes pasos para crear un grupo de parámetros de base de datos personalizado y configure su instancia de base de datos de RDS para PostgreSQL para utilizarlo.
### Consola
**Para crear un grupo de parámetros de base de datos personalizado y utilizarlo con su instancia de base de datos de RDS para PostgreSQL**
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon RDS en [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. Elija Parameter groups (Grupos de parámetros) en el menú de Amazon RDS.
1. Elija **Create parameter group**.
1. En la página **Parameter group details** (Detalles del grupo de parámetros), escriba la siguiente información.
+ En **Parameter group family** (Familia de grupo de parámetros), elija postgres14.
+ En **Type (Tipo)**, elija DB Parameter Group (Grupo de parámetros de bases de datos).
+ En **Group name** (Nombre de grupo), asigne al grupo de parámetros un nombre significativo en el contexto de sus operaciones.
+ En **Description** (Descripción), introduzca una descripción útil para que los demás miembros de su equipo puedan encontrarla fácilmente.
1. Seleccione **Crear**. El grupo de parámetros de base de datos personalizado se crea en su Región de AWS. Ahora puede modificar su instancia de base de datos de RDS para PostgreSQL para usarlo. Para ello, siga los siguientes pasos.
1. Seleccione **Databases** (Bases de datos) en el menú de Amazon RDS.
1. Elija la instancia de base de datos de RDS para PostgreSQL que desea usar con TLE de entre las enumeradas y, a continuación, elija **Modify** (Modificar).
1. En la En la página Modify DB cluster settings (Modificar la configuración del clúster de base de datos), busque **Database options** (Opciones de la base de datos) y elija su grupo de parámetros de base de datos personalizado en el selector.
1. Elija **Continue** (Continuar) para guardar el cambio.
1. Elija **Apply immediately** (Aplicar inmediatamente) para poder seguir configurando la instancia de base de datos de RDS para PostgreSQL para utilizar TLE.
Para continuar con la configuración del sistema para Extensiones de lenguaje de confianza, consulte [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Para obtener más información sobre cómo trabajar con Grupos de parámetros de base de datos, consulte [Grupos de parámetros de base de datos para instancias de Amazon RDS](USER_WorkingWithDBInstanceParamGroups.md).
### AWS CLI
Puede evitar especificar el argumento `--region` al utilizar los comandos de la CLI al configurar su AWS CLI con su Región de AWS predeterminada. Para obtener más información, consulte [Fundamentos de configuración](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) en la *Guía del usuario de AWS Command Line Interface*.
**Para crear un grupo de parámetros de base de datos personalizado y utilizarlo con su instancia de base de datos de RDS para PostgreSQL**
1. Utilice el comando [create-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-parameter-group.html) de la AWS CLI para crear un grupo de parámetros de base de datos personalizado basado en postgres14 para su Región de AWS.
Para Linux, macOS o Unix:
```
aws rds create-db-parameter-group \
--region aws-region \
--db-parameter-group-name custom-params-for-pg-tle \
--db-parameter-group-family postgres14 \
--description "My custom DB parameter group for Trusted Language Extensions"
```
Para Windows:
```
aws rds create-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name custom-params-for-pg-tle ^
--db-parameter-group-family postgres14 ^
--description "My custom DB parameter group for Trusted Language Extensions"
```
Su grupo de parámetros de base de datos personalizado está disponible en su Región de AWS, por lo que puede modificar instancia de base de datos de RDS para PostgreSQL para utilizarla.
1. Utilice el comando [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) de la AWS CLI para aplicar su grupo de parámetros de base de datos personalizado a su instancia de base de datos de RDS para PostgreSQL. Este comando reinicia inmediatamente la instancia activa.
Para Linux, macOS o Unix:
```
aws rds modify-db-instance \
--region aws-region \
--db-instance-identifier your-instance-name \
--db-parameter-group-name custom-params-for-pg-tle \
--apply-immediately
```
Para Windows:
```
aws rds modify-db-instance ^
--region aws-region ^
--db-instance-identifier your-instance-name ^
--db-parameter-group-name custom-params-for-pg-tle ^
--apply-immediately
```
Para continuar con la configuración del sistema para Extensiones de lenguaje de confianza, consulte [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Para obtener más información, consulte [Grupos de parámetros para Amazon RDS](USER_WorkingWithParamGroups.md).
# Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL
En los pasos siguientes se supone que su instancia de base de datos de RDS para PostgreSQL está asociada a un grupo de parámetros de base de datos personalizado. Puede utilizar la Consola de administración de AWS o la AWS CLI para estos pasos.
Al configurar Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL, las instala en una base de datos específica para que las usen los usuarios de la base de datos que tienen permisos en esa base de datos.
## Consola
**Para configurar Extensiones de lenguaje de confianza**
Realice los siguientes pasos con una cuenta que sea miembro del grupo (rol) `rds_superuser`.
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon RDS en [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. En el panel de navegación, elija la instancia de base de datos de RDS for PostgreSQL.
1. Abra la pestaña **Configuration** (Configuración) para su Instancia de base de datos RDS para PostgreSQL. Entre los detalles de la instancia, busque el enlace del **grupo de parámetros**.
1. Elija el enlace para abrir los parámetros personalizados asociados al Instancia de base de datos RDS para PostgreSQL.
1. En el campo de búsqueda **Parametes** (Parámetros), escriba `shared_pre` para buscar el parámetro `shared_preload_libraries`.
1. Seleccione **Edit parameters** (Editar parámetros) para acceder a los valores de las propiedades.
1. Añada `pg_tle` a la lista en el campo **Values** (Valores). Utilice una coma para separar los elementos de la lista de valores.
![\[Imagen del parámetro shared_preload_libraries con pg_tle añadido.\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/UserGuide/images/apg_rpg_shared_preload_pg_tle.png)
1. Reinicie la instancia de base de datos de RDS for PostgreSQL para que surta efecto el cambio en el parámetro `shared_preload_libraries`.
1. Cuando la instancia esté disponible, verifique si se ha inicializado `pg_tle`. Use `psql` para conectarse a la instancia de base de datos de RDS for PostgreSQL y, a continuación, ejecute el siguiente comando.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
1. Con la extensión `pg_tle` inicializada, ahora ya puede crear la extensión.
```
CREATE EXTENSION pg_tle;
```
Para comprobar que la extensión esté instalada, use el metacomando `psql`.
```
labdb=> \dx
List of installed extensions
Name | Version | Schema | Description
---------+---------+------------+--------------------------------------------
pg_tle | 1.0.1 | pgtle | Trusted-Language Extensions for PostgreSQL
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
```
1. Asigne el rol `pgtle_admin` al nombre de usuario principal que creó para la instancia de base de datos de RDS para PostgreSQL al configurarla. Si ha aceptado el valor predeterminado, es `postgres`.
```
labdb=> GRANT pgtle_admin TO postgres;
GRANT ROLE
```
Puede comprobar si se ha realizado la concesión con el metacomando `psql`, tal como se muestra en el siguiente ejemplo. Solo los roles `pgtle_admin` y `postgres` se muestran en el resultado. Para obtener más información, consulte [Descripción del rol rds\$1superuser](Appendix.PostgreSQL.CommonDBATasks.Roles.rds_superuser.md).
```
labdb=> \du
List of roles
Role name | Attributes | Member of
-----------------+---------------------------------+-----------------------------------
pgtle_admin | Cannot login | {}
postgres | Create role, Create DB +| {rds_superuser,pgtle_admin}
| Password valid until infinity |...
```
1. Cierre la sesión de `psql` con el metacomando `\q`.
```
\q
```
Para empezar a crear extensiones TLE, consulte [Ejemplo: creación de una extensión de lenguaje de confianza mediante SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
## AWS CLI
Puede evitar especificar el argumento `--region` al utilizar los comandos de la CLI al configurar su AWS CLI con su Región de AWS predeterminada. Para obtener más información, consulte [Fundamentos de configuración](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) en la *Guía del usuario de AWS Command Line Interface*.
**Para configurar Extensiones de lenguaje de confianza**
1. Use el comando [modify-db-cluster-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) de AWS CLI para añadir `pg_tle` al parámetro `shared_preload_libraries`.
```
aws rds modify-db-parameter-group \
--db-parameter-group-name custom-param-group-name \
--parameters "ParameterName=shared_preload_libraries,ParameterValue=pg_tle,ApplyMethod=pending-reboot" \
--region aws-region
```
1. Use el comando [reboot-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/reboot-db-instance) de AWS CLI para reiniciar la instancia de base de datos de RDS para PostgreSQL e inicialice la biblioteca de `pg_tle`.
```
aws rds reboot-db-instance \
--db-instance-identifier your-instance \
--region aws-region
```
1. Cuando la instancia esté disponible, puede verificar si `pg_tle` se ha inicializado. Use `psql` para conectarse a la instancia de base de datos de RDS for PostgreSQL y, a continuación, ejecute el siguiente comando.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
Con `pg_tle` inicializado, ahora ya puede crear la extensión.
```
CREATE EXTENSION pg_tle;
```
1. Asigne el rol `pgtle_admin` al nombre de usuario principal que creó para la instancia de base de datos de RDS para PostgreSQL al configurarla. Si ha aceptado el valor predeterminado, es `postgres`.
```
GRANT pgtle_admin TO postgres;
GRANT ROLE
```
1. Cierre la sesión de `psql` de la siguiente manera.
```
labdb=> \q
```
Para empezar a crear extensiones TLE, consulte [Ejemplo: creación de una extensión de lenguaje de confianza mediante SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
# Información general de Extensiones de lenguaje de confianza para PostgreSQL
Extensiones de lenguaje de confianza para PostgreSQL es una extensión de PostgreSQL que se instala en la instancia de base de datos de RDS para PostgreSQL de la misma manera que se configuran otras extensiones de PostgreSQL. En la siguiente imagen de un ejemplo de base de datos de la herramienta de cliente pgAdmin, puede ver algunos de los componentes que componen la extensión `pg_tle`.
![\[Imagen que muestra algunos de los componentes que conforman el kit de desarrollo TLE.\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/UserGuide/images/apg-pg_tle-installed-view-in-pgAdmin.png)
Puede ver los siguientes detalles.
1. El kit de desarrollo de Extensiones de lenguaje de confianza (TLE) está empaquetado como la extensión `pg_tle`. De este modo, `pg_tle` se añade a las extensiones disponibles para la base de datos en la que se instala.
1. TLE tiene su propio esquema: `pgtle`. Este esquema contiene funciones auxiliares (3) para instalar y administrar las extensiones que cree.
1. TLE proporciona más de una docena de funciones auxiliares para instalar, registrar y administrar las extensiones. Para obtener más información sobre estas funciones, consulte [Referencia de funciones para Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-functions-reference.md).
Otros componentes de la extensión `pg_tle` incluyen lo siguiente:
+ **El rol `pgtle_admin`**: el rol `pgtle_admin` se crea al instalar la extensión `pg_tle`. Este rol es privilegiado y debe tratarse como tal. Le recomendamos encarecidamente que siga el principio de *privilegio mínimo* al conceder el rol `pgtle_admin` a los usuarios de la base de datos. En otras palabras, conceda el rol `pgtle_admin` solo a los usuarios de bases de datos que estén autorizados a crear, instalar y administrar nuevas extensiones TLE, como `postgres`.
+ **La tabla `pgtle.feature_info`**: la tabla `pgtle.feature_info` es una tabla protegida que contiene información sobre los TLE, los enlaces, los procedimientos y las funciones personalizados almacenados que utilizan. Si tiene privilegios `pgtle_admin`, utilice las siguientes funciones de Extensiones de lenguaje de confianza para añadir y actualizar la información de la tabla.
+ [pgtle.register\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature)
+ [pgtle.register\$1feature\$1if\$1not\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature_if_not_exists)
+ [pgtle.unregister\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature)
+ [pgtle.unregister\$1feature\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature_if_exists)
# Creación de extensiones TLE para RDS para PostgreSQL
Puede instalar cualquier extensión que cree con TLE en cualquier instancia de base de datos de RDS para PostgreSQL que tenga la extensión `pg_tle` instalada. La extensión `pg_tle` se limita a la base de datos PostgreSQL en la que está instalada. Las extensiones que cree con TLE están incluidas en la misma base de datos.
Utilice las distintas funciones de `pgtle` para instalar el código que conforma la extensión TLE. Todas las siguientes funciones de Extensiones de lenguaje de confianza requieren el rol `pgtle_admin`.
+ [pgtle.install\$1extension](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_extension)
+ [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path)
+ [pgtle.register\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature)
+ [pgtle.register\$1feature\$1if\$1not\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature_if_not_exists)
+ [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version)
+ [pgtle.uninstall\$1extension(name)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension(nombre, versión)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name-version)
+ [pgtle.uninstall\$1extension\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension_if_exists)
+ [pgtle.uninstall\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_update_path)
+ [pgtle.uninstall\$1update\$1path\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_update_path_if_exists)
+ [pgtle.unregister\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature)
+ [pgtle.unregister\$1feature\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature_if_exists)
## Ejemplo: creación de una extensión de lenguaje de confianza mediante SQL
El siguiente ejemplo muestra cómo crear una extensión TLE denominada `pg_distance` que contenga algunas funciones SQL para calcular distancias mediante diferentes fórmulas. En la lista, puede encontrar la función para calcular la distancia Manhattan y la función para calcular la distancia euclidiana. Para obtener más información sobre la diferencia entre estas fórmulas, consulte [Geometría del taxista](https://en.wikipedia.org/wiki/Taxicab_geometry) y [Geometría euclidiana](https://en.wikipedia.org/wiki/Euclidean_geometry) en la Wikipedia.
Puede utilizar este ejemplo en su instancia de base de datos de RDS para PostgreSQL si tiene la extensión `pg_tle` configurada como se detalla en [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**nota**
Debe tener los privilegios del rol `pgtle_admin` para seguir este procedimiento.
**Para crear la extensión TLE de ejemplo**
En los pasos siguientes se utiliza un ejemplo de base de datos denominado `labdb`. Esta base de datos es propiedad del usuario `postgres` principal. El rol `postgres` también tiene los permisos del rol `pgtle_admin`.
1. Use `psql` para conectarse a la Instancia de base de datos RDS para PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Cree una extensión TLE denominada `pg_distance` copiando el siguiente código y pegándolo en la consola de sesión de `psql`.
```
SELECT pgtle.install_extension
(
'pg_distance',
'0.1',
'Distance functions for two points',
$_pg_tle_$
CREATE FUNCTION dist(x1 float8, y1 float8, x2 float8, y2 float8, norm int)
RETURNS float8
AS $$
SELECT (abs(x2 - x1) ^ norm + abs(y2 - y1) ^ norm) ^ (1::float8 / norm);
$$ LANGUAGE SQL;
CREATE FUNCTION manhattan_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 1);
$$ LANGUAGE SQL;
CREATE FUNCTION euclidean_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 2);
$$ LANGUAGE SQL;
$_pg_tle_$
);
```
Debería ver un resultado como el siguiente.
```
install_extension
---------------
t
(1 row)
```
Los artefactos que componen la extensión `pg_distance` ahora ya están instalados en su base de datos. Estos artefactos incluyen el archivo de control y el código de la extensión, que son elementos que deben estar presentes para poder crear la extensión mediante el comando `CREATE EXTENSION`. En otras palabras, aún debe crear la extensión para que sus funciones estén disponibles para los usuarios de la base de datos.
1. Para crear la extensión, utilice el comando `CREATE EXTENSION` como lo haría con cualquier otra extensión. Al igual que con otras extensiones, el usuario de la base de datos debe tener los permisos `CREATE` en la base de datos.
```
CREATE EXTENSION pg_distance;
```
1. Para probar la extensión TLE `pg_distance`, puede utilizarla para calcular la [distancia Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry) entre cuatro puntos.
```
labdb=> SELECT manhattan_dist(1, 1, 5, 5);
8
```
Para calcular la [distancia euclidiana](https://en.wikipedia.org/wiki/Euclidean_geometry) entre el mismo conjunto de puntos, puede utilizar lo siguiente.
```
labdb=> SELECT euclidean_dist(1, 1, 5, 5);
5.656854249492381
```
La extensión `pg_distance` carga las funciones de la base de datos y las pone a disposición de cualquier usuario con permisos en la base de datos.
## Modificación de su extensión TLE
Para mejorar el rendimiento de las consultas para las funciones incluidas en esta extensión TLE, añada los dos atributos de PostgreSQL siguientes a sus especificaciones.
+ `IMMUTABLE`: el atributo `IMMUTABLE` garantiza que el optimizador de consultas pueda utilizar optimizaciones para mejorar los tiempos de respuesta de las consultas. Para obtener más información, consulte [Function Volatility Categories](https://www.postgresql.org/docs/current/xfunc-volatility.html) (Categorías de volatilidad de función) en la documentación de PostgreSQL.
+ `PARALLEL SAFE`: el atributo `PARALLEL SAFE` es otro atributo que permite a PostgreSQL ejecutar la función en modo paralelo. Para obtener más información, consulte [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html) en la documentación de PostgreSQL.
En el siguiente ejemplo, puede ver cómo se usa la función `pgtle.install_update_path` para agregar estos atributos a cada función a fin de crear una versión `0.2` de la extensión TLE `pg_distance`. Para obtener más información acerca de esta función, consulte [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path). Debe tener el rol `pgtle_admin` para realizar esta tarea.
**Para actualizar una extensión TLE existente y especificar la versión predeterminada**
1. Conecte con la instancia de base de datos de RDS para PostgreSQL con `psql` u otra herramienta de cliente como pgAdmin.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Modifique una extensión TLE existente copiando el siguiente código y pegándolo en la consola de sesión de `psql`.
```
SELECT pgtle.install_update_path
(
'pg_distance',
'0.1',
'0.2',
$_pg_tle_$
CREATE OR REPLACE FUNCTION dist(x1 float8, y1 float8, x2 float8, y2 float8, norm int)
RETURNS float8
AS $$
SELECT (abs(x2 - x1) ^ norm + abs(y2 - y1) ^ norm) ^ (1::float8 / norm);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
CREATE OR REPLACE FUNCTION manhattan_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 1);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
CREATE OR REPLACE FUNCTION euclidean_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 2);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
$_pg_tle_$
);
```
Verá una respuesta similar a la siguiente.
```
install_update_path
---------------------
t
(1 row)
```
Puede hacer que esta versión de la extensión sea la versión predeterminada para que los usuarios de la base de datos no tengan que especificar una versión al crear o actualizar la extensión en su base de datos.
1. Para especificar que la versión modificada (versión 0.2) de la extensión TLE es la versión predeterminada, utilice la función `pgtle.set_default_version` tal como se muestra en el siguiente ejemplo.
```
SELECT pgtle.set_default_version('pg_distance', '0.2');
```
Para obtener más información acerca de esta función, consulte [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version).
1. Con el código en su lugar, puede actualizar la extensión TLE instalada de la forma habitual, mediante el comando `ALTER EXTENSION ... UPDATE`, tal como se muestra aquí:
```
ALTER EXTENSION pg_distance UPDATE;
```
# Eliminar las extensiones TLE de una base de datos
Puede eliminar sus extensiones TLE mediante el comando `DROP EXTENSION` de la misma manera que lo hace con otras extensiones de PostgreSQL. Al eliminar la extensión, no se eliminan los archivos de instalación que la componen, lo que permite a los usuarios volver a crearla. Para eliminar la extensión y sus archivos de instalación, realice el siguiente proceso de dos pasos.
**Para eliminar la extensión TLE y eliminar sus archivos de instalación**
1. Use `psql` u otra herramienta de cliente para conectarse a la instancia de base de datos de RDS para PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Elimine la extensión tal como haría con cualquier extensión de PostgreSQL.
```
DROP EXTENSION your-TLE-extension
```
Por ejemplo, si crea la extensión `pg_distance` tal como se indica en [Ejemplo: creación de una extensión de lenguaje de confianza mediante SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example), puede eliminarla de la siguiente manera.
```
DROP EXTENSION pg_distance;
```
Verá un resultado que confirma que se ha eliminado la extensión, de la siguiente manera.
```
DROP EXTENSION
```
En este punto, la extensión ya no está activa en la base de datos. Sin embargo, sus archivos de instalación y su archivo de control siguen disponibles en la base de datos, por lo que los usuarios de la base de datos pueden volver a crear la extensión si lo desean.
+ Si desea dejar los archivos de extensión intactos para que los usuarios de la base de datos puedan crear su extensión TLE, puede detenerse aquí.
+ Si desea eliminar todos los archivos que conforman la extensión, proceda con el siguiente paso.
1. Para eliminar todos los archivos de instalación de la extensión, utilice la función `pgtle.uninstall_extension`. Esta función elimina todos los archivos de código y control de la extensión.
```
SELECT pgtle.uninstall_extension('your-tle-extension-name');
```
Por ejemplo, para eliminar todos los archivos de instalación `pg_distance`, utilice el siguiente comando.
```
SELECT pgtle.uninstall_extension('pg_distance');
uninstall_extension
---------------------
t
(1 row)
```
# Desinstalación de Extensiones de lenguaje de confianza para PostgreSQL
Si ya no quiere crear sus propias extensiones TLE con TLE, puede eliminar la extensión `pg_tle` y eliminar todos los artefactos. Esta acción incluye eliminar cualquier extensión TLE de la base de datos y el esquema `pgtle`.
**Para eliminar la extensión `pg_tle` y su esquema de una base de datos**
1. Use `psql` u otra herramienta de cliente para conectarse a la instancia de base de datos de RDS para PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Elimine la extensión `pg_tle` de la base de datos. Si la base de datos está ejecutando sus propias extensiones TLE, también debe eliminar esas extensiones. Para ello, puede utilizar la palabra clave `CASCADE`, tal como se muestra a continuación.
```
DROP EXTENSION pg_tle CASCADE;
```
Si la extensión `pg_tle` no sigue activa en la base de datos, no es necesario que utilice la palabra clave `CASCADE`.
1. Elimine el esquema `pgtle`. Esta acción elimina todas las funciones de administración de la base de datos.
```
DROP SCHEMA pgtle CASCADE;
```
El comando devuelve lo siguiente cuando se completa el proceso.
```
DROP SCHEMA
```
Se eliminan la extensión `pg_tle`, su esquema y sus funciones, así como todos los artefactos. Para crear nuevas extensiones con TLE, vuelva a realizar el proceso de configuración. Para obtener más información, consulte [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
# Uso de enlaces de PostgreSQL con sus extensiones TLE
Un *enlace* es un mecanismo de devolución de llamada disponible en PostgreSQL que permite a los desarrolladores llamar a funciones personalizadas u otras rutinas durante las operaciones normales de la base de datos. El kit de desarrollo de TLE admite enlaces de PostgreSQL para que pueda integrar funciones personalizadas con el comportamiento de PostgreSQL en el tiempo de ejecución. Por ejemplo, puede utilizar un enlace para asociar el proceso de autenticación a su propio código personalizado o para modificar el proceso de planificación y ejecución de consultas según sus necesidades específicas.
Sus extensiones TLE pueden utilizar enlaces. Si un enlace tiene un alcance global, se aplica a todas las bases de datos. Por lo tanto, si su extensión TLE usa un enlace global, debe crear su extensión TLE en todas las bases de datos a las que puedan acceder sus usuarios.
Cuando usa la extensión `pg_tle` para crear sus propias Extensiones de lenguaje de confianza, puede usar los enlaces disponibles de una API de SQL para crear las funciones de su extensión. Debe registrar cualquier enlace con `pg_tle`. Para algunos enlaces, es posible que también tenga que establecer varios parámetros de configuración. Por ejemplo, el enlace de retención `passcode` se puede configurar como activado, desactivado u obligatorio. Para obtener más información sobre los requisitos específicos de los enlaces `pg_tle` disponibles, consulte [Referencia de enlaces para Extensiones de lenguaje de confianza para PostgreSQL](PostgreSQL_trusted_language_extension-hooks-reference.md).
## Ejemplo: Crear una extensión que utilice un enlace de PostgreSQL
El ejemplo descrito en esta sección utiliza un enlace de PostgreSQL para comprobar la contraseña proporcionada durante operaciones SQL específicas e impide que los usuarios de la base de datos establezcan sus contraseñas iguales a las que figuran en la tabla `password_check.bad_passwords`. La tabla contiene las diez opciones de contraseñas más utilizadas, pero fáciles de descifrar.
Para configurar este ejemplo en su instancia de base de datos de RDS para PostgreSQL, ya tiene que tener Extensiones de lenguaje de confianza instalado. Para obtener más información, consulte [Configuración de Extensiones de lenguaje de confianza en su instancia de base de datos de RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**Para configurar el ejemplo del enlace de verificación de contraseñas**
1. Use `psql` para conectarse a la Instancia de base de datos RDS para PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Copie el código de la [Lista de códigos del enlace password\$1check](#PostgreSQL_trusted_language_extension-example-hook_code_listing) y péguelo en su base de datos.
```
SELECT pgtle.install_extension (
'my_password_check_rules',
'1.0',
'Do not let users use the 10 most commonly used passwords',
$_pgtle_$
CREATE SCHEMA password_check;
REVOKE ALL ON SCHEMA password_check FROM PUBLIC;
GRANT USAGE ON SCHEMA password_check TO PUBLIC;
CREATE TABLE password_check.bad_passwords (plaintext) AS
VALUES
('123456'),
('password'),
('12345678'),
('qwerty'),
('123456789'),
('12345'),
('1234'),
('111111'),
('1234567'),
('dragon');
CREATE UNIQUE INDEX ON password_check.bad_passwords (plaintext);
CREATE FUNCTION password_check.passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
RETURNS void AS $$
DECLARE
invalid bool := false;
BEGIN
IF password_type = 'PASSWORD_TYPE_MD5' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE ('md5' || md5(bp.plaintext || username)) = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
ELSIF password_type = 'PASSWORD_TYPE_PLAINTEXT' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE bp.plaintext = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
END IF;
END
$$ LANGUAGE plpgsql SECURITY DEFINER;
GRANT EXECUTE ON FUNCTION password_check.passcheck_hook TO PUBLIC;
SELECT pgtle.register_feature('password_check.passcheck_hook', 'passcheck');
$_pgtle_$
);
```
Cuando la extensión se haya cargado en la base de datos, verá un resultado como el siguiente.
```
install_extension
-------------------
t
(1 row)
```
1. Mientras siga conectado a la base de datos, ya podrá crear la extensión.
```
CREATE EXTENSION my_password_check_rules;
```
1. Puede confirmar que la extensión se ha creado en la base de datos mediante el siguiente metacomando `psql`.
```
\dx
List of installed extensions
Name | Version | Schema | Description
-------------------------+---------+------------+-------------------------------------------------------------
my_password_check_rules | 1.0 | public | Prevent use of any of the top-ten most common bad passwords
pg_tle | 1.0.1 | pgtle | Trusted-Language Extensions for PostgreSQL
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
(3 rows)
```
1. Abra otra sesión de terminal para trabajar con la AWS CLI. Debe modificar su grupo de parámetros de base de datos personalizado para activar el enlace de verificación de contraseñas. Para ello, utilice el comando [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) de la CLI tal como se muestra en el siguiente ejemplo.
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
Cuando el parámetro se haya activado correctamente, verá un resultado como el siguiente.
```
(
"DBParameterGroupName": "docs-lab-parameters-for-tle"
}
```
Puede que el cambio en la configuración del grupo de parámetros tarde unos minutos en aplicarse. Sin embargo, este parámetro es dinámico, por lo que no es necesario reiniciar la instancia de base de datos de RDS para PostgreSQL para que la configuración surta efecto.
1. Abra la sesión `psql` y consulte la base de datos para comprobar que el enlace password\$1check esté activado.
```
labdb=> SHOW pgtle.enable_password_check;
pgtle.enable_password_check
-----------------------------
on
(1 row)
```
El enlace password-check ahora está activo. Puede probarlo creando un rol nuevo y utilizando una de las contraseñas incorrectas, tal como se muestra en el siguiente ejemplo.
```
CREATE ROLE test_role PASSWORD 'password';
ERROR: Cannot use passwords from the common password dictionary
CONTEXT: PL/pgSQL function password_check.passcheck_hook(text,text,pgtle.password_types,timestamp with time zone,boolean) line 21 at RAISE
SQL statement "SELECT password_check.passcheck_hook(
$1::pg_catalog.text,
$2::pg_catalog.text,
$3::pgtle.password_types,
$4::pg_catalog.timestamptz,
$5::pg_catalog.bool)"
```
El resultado se ha modificado para que se pueda leer.
El siguiente ejemplo muestra que el comportamiento `\password` del metacomando interactivo `pgsql` también se ve afectado por el enlace password\$1check.
```
postgres=> SET password_encryption TO 'md5';
SET
postgres=> \password
Enter new password for user "postgres":*****
Enter it again:*****
ERROR: Cannot use passwords from the common password dictionary
CONTEXT: PL/pgSQL function password_check.passcheck_hook(text,text,pgtle.password_types,timestamp with time zone,boolean) line 12 at RAISE
SQL statement "SELECT password_check.passcheck_hook($1::pg_catalog.text, $2::pg_catalog.text, $3::pgtle.password_types, $4::pg_catalog.timestamptz, $5::pg_catalog.bool)"
```
Puede eliminar esta extensión TLE y desinstalar sus archivos de código fuente si lo desea. Para obtener más información, consulte [Eliminar las extensiones TLE de una base de datosEliminar las extensiones TLE de una base de datos](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md).
### Lista de códigos del enlace password\$1check
El código de ejemplo que se muestra aquí define la especificación de la extensión TLE `my_password_check_rules`. Al copiar este código y pegarlo en la base de datos, el código de la extensión `my_password_check_rules` se carga en la base de datos y el enlace `password_check` queda registrado para que lo utilice la extensión.
```
SELECT pgtle.install_extension (
'my_password_check_rules',
'1.0',
'Do not let users use the 10 most commonly used passwords',
$_pgtle_$
CREATE SCHEMA password_check;
REVOKE ALL ON SCHEMA password_check FROM PUBLIC;
GRANT USAGE ON SCHEMA password_check TO PUBLIC;
CREATE TABLE password_check.bad_passwords (plaintext) AS
VALUES
('123456'),
('password'),
('12345678'),
('qwerty'),
('123456789'),
('12345'),
('1234'),
('111111'),
('1234567'),
('dragon');
CREATE UNIQUE INDEX ON password_check.bad_passwords (plaintext);
CREATE FUNCTION password_check.passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
RETURNS void AS $$
DECLARE
invalid bool := false;
BEGIN
IF password_type = 'PASSWORD_TYPE_MD5' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE ('md5' || md5(bp.plaintext || username)) = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
ELSIF password_type = 'PASSWORD_TYPE_PLAINTEXT' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE bp.plaintext = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
END IF;
END
$$ LANGUAGE plpgsql SECURITY DEFINER;
GRANT EXECUTE ON FUNCTION password_check.passcheck_hook TO PUBLIC;
SELECT pgtle.register_feature('password_check.passcheck_hook', 'passcheck');
$_pgtle_$
);
```
# Uso de tipos de datos personalizados en TLE
PostgreSQL admite comandos para registrar nuevos tipos base (también conocidos como tipos escalares) para gestionar con eficiencia estructuras de datos complejas en su base de datos. Un tipo base le permite personalizar la forma en que se almacenan los datos internamente y cómo convertirlos a una representación textual externa y desde ella. Estos tipos de datos personalizados son útiles a la hora de ampliar PostgreSQL para que admita dominios funcionales en los que un tipo integrado, como un número o un texto, no puede proporcionar una semántica de búsqueda suficiente.
RDS para PostgreSQL le permite crear tipos de datos personalizados en su extensión de lenguaje de confianza y definir funciones que admitan operaciones de SQL e indexación para estos nuevos tipos de datos. Los tipos de datos personalizados están disponibles para las siguientes versiones:
+ RDS para PostgreSQL, versión 15.4 y versiones 15 posteriores
+ RDS para PostgreSQL, versión 14.9 y versiones 14 posteriores
+ RDS para PostgreSQL, versión 13.12 y versiones 13 posteriores
Para obtener más información, consulte [Trusted Language Base types](https://github.com/aws/pg_tle/blob/main/docs/09_datatypes.md).
# 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');
```
# Referencia de enlaces para Extensiones de lenguaje de confianza para PostgreSQL
Extensiones de lenguaje de confianza para PostgreSQL admite los enlaces de PostgreSQL. Un *enlace* es un mecanismo interno de devolución de llamada disponible para los desarrolladores para ampliar la funcionalidad principal de PostgreSQL. Mediante el uso de enlaces, los desarrolladores pueden implementar sus propias funciones o procedimientos para utilizarlos durante diversas operaciones de bases de datos, modificando así el comportamiento de PostgreSQL de alguna manera. Por ejemplo, puede utilizar un enlace `passcheck` para personalizar la forma en que PostgreSQL gestiona las contraseñas proporcionadas al crear o cambiar las contraseñas de los usuarios (roles).
Consulte la siguiente documentación para obtener información sobre el enlace de passcheck disponible para sus extensiones TLE. Para obtener más información sobre los enlaces disponibles, incluido el enlace de autenticación del cliente, consulte [Trusted Language Extensions hooks](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md).
## Enlace de comprobación de contraseñas (passcheck)
El enlace `passcheck` se utiliza para personalizar el comportamiento de PostgreSQL durante el proceso de comprobación de contraseñas para los siguientes comandos SQL y el metacomando `psql`.
+ `CREATE ROLE username ...PASSWORD`: para obtener más información, consulte [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) en la documentación de PostgreSQL.
+ `ALTER ROLE username...PASSWORD`: para obtener más información, consulte [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html) en la documentación de PostgreSQL.
+ `\password username`: este metacomando `psql` interactivo cambia de forma segura la contraseña del usuario especificado mediante un hash de la contraseña antes de utilizar la sintaxis `ALTER ROLE ... PASSWORD` de forma transparente. El metacomando es un contenedor seguro para el comando `ALTER ROLE ... PASSWORD`, por lo que el enlace se aplica al comportamiento del metacomando `psql`.
Para ver un ejemplo, consulta [Lista de códigos del enlace password\$1check](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing).
**Contents**
+ [Prototipo de función](#passcheck_hook-prototype)
+ [Argumentos](#passcheck_hook-arguments)
+ [Configuración](#passcheck_hook-configuration)
+ [Notas de uso](#passcheck_hook-usage)
### Prototipo de función
```
passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
```
### Argumentos
La función de enlace `passcheck` acepta los argumentos siguientes:
+ `username`: el nombre (como texto) del rol (nombre de usuario) que establece una contraseña.
+ `password`: la contraseña en texto sin formato o con hash. La contraseña introducida debe coincidir con el tipo especificado en `password_type`.
+ `password_type`: especifique el formato `pgtle.password_type` de la contraseña. Este formato puede ser uno de los siguientes:
+ `PASSWORD_TYPE_PLAINTEXT`: una contraseña sin formato.
+ `PASSWORD_TYPE_MD5`: una contraseña que se ha cifrado con hash mediante el algoritmo MD5 (resumen de mensaje 5).
+ `PASSWORD_TYPE_SCRAM_SHA_256`: una contraseña que se ha cifrado con hash mediante el algoritmo SCRAM-SHA-256.
+ `valid_until`: especifica el momento en que la contraseña deja de ser válida. Este argumento es opcional. Si utiliza este argumento, especifique la hora como valor `timestamptz`.
+ `valid_null`: si este valor booleano está establecido en `true`, la opción `valid_until` se establece en `NULL`.
### Configuración
La función `pgtle.enable_password_check` controla si el enlace de passcheck está activo. El enlace de passcheck tiene tres ajustes posibles.
+ `off`: desactiva el enlace de comprobación de contraseñas `passcheck`. Este es el valor predeterminado.
+ `on`: activa el enlace de comprobación de contraseñas `passcode` para cotejarlas con la tabla.
+ `require`: requiere que se defina un enlace de comprobación de contraseñas.
### Notas de uso
Para activar o desactivar el enlace `passcheck`, debe modificar el grupo de parámetros de base de datos personalizado de su instancia de base de datos de RDS para PostgreSQL.
Para Linux, macOS o Unix:
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
Para Windows:
```
aws rds modify-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name your-custom-parameter-group ^
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```