# Trabalhar com Trusted Language Extensions para PostgreSQL
O Trusted Language Extensions para PostgreSQL é um kit de desenvolvimento de código aberto para criar extensões do PostgreSQL. Ele permite que você crie extensões do PostgreSQL de alta performance e as execute com segurança em sua instância de banco de dados do RDS para PostgreSQL. Ao usar o Trusted Language Extensions (TLE) para PostgreSQL, você pode criar extensões do PostgreSQL que sigam a abordagem documentada para estender a funcionalidade do PostgreSQL. Para obter mais informações, consulte [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (Compactar objetos relacionados em uma extensão) na documentação do PostgreSQL.
Um dos principais benefícios do TLE é que você pode usá-lo em ambientes que não fornecem acesso ao sistema de arquivos subjacente à instância do PostgreSQL. Anteriormente, a instalação de uma nova extensão exigia acesso ao sistema de arquivos. O TLE remove essa restrição. Ele fornece um ambiente de desenvolvimento para criar extensões para qualquer banco de dados do PostgreSQL, como as executadas em suas instâncias de banco de dados do RDS para PostgreSQL.
O TLE foi projetado para impedir o acesso a recursos inseguros para as extensões criadas com o uso do TLE. Seu ambiente de execução limita o impacto de qualquer defeito de extensão em uma única conexão de banco de dados. O TLE também oferece aos administradores de banco de dados um controle refinado sobre quem pode instalar extensões e fornece um modelo de permissões para executá-las.
O TLE é compatível com as seguintes versões do RDS para PostgreSQL:
+ Versão 18.1 e versões 18 posteriores
+ Versão 17.1 e versões 17 posteriores
+ Versão 16.1 e versões 16 posteriores
+ Versão 15.2 e versões 15 posteriores
+ Versão 14.5 e versões 14 posteriores
+ Versão 13.12 e versões 13 posteriores
O ambiente de desenvolvimento e de execução do Trusted Language Extensions são empacotados como a extensão `pg_tle` do PostgreSQL, versão 1.0.1. É compatível com a criação de extensões em JavaScript, Perl, Tcl, PL/pgSQL e SQL. Você instala a extensão `pg_tle` em sua instância de banco de dados do RDS para PostgreSQL da mesma forma que instala outras extensões do PostgreSQL. Depois de configurar `pg_tle`, os desenvolvedores podem usá-lo para criar extensões do PostgreSQL, conhecidas como *extensões TLE*.
Nos tópicos a seguir, você encontrará informações sobre como configurar Trusted Language Extensions e como começar a criar suas próprias extensões TLE.
**Topics**
+ [Terminologia](PostgreSQL_trusted_language_extension-terminology.md)
+ [Requisitos para usar Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-requirements.md)
+ [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md)
+ [Visão geral do Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension.overview.md)
+ [Criar extensões TLE para RDS para PostgreSQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md)
+ [Descartar suas extensões TLE de um banco de dados](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md)
+ [Desinstalar o Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-uninstalling-pg_tle-devkit.md)
+ [Usar ganchos do PostgreSQL com suas extensões TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)
+ [Usar tipos de dados personalizados no TLE](PostgreSQL_trusted_language_extension-custom-data-type.md)
+ [Referência de funções para Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-functions-reference.md)
+ [Referência de ganchos para Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-hooks-reference.md)
# Terminologia
Para ajudar você a entender melhor o Trusted Language Extensions, consulte o glossário a seguir para conhecer os termos usados neste tópico.
**Trusted Language Extensions para PostgreSQL**
*Trusted Language Extensions para PostgreSQL* é o nome oficial do kit de desenvolvimento de código aberto que vem com a extensão `pg_tle`. Ele está disponível para uso em qualquer sistema PostgreSQL. Para obter mais informações, consulte [aws/pg\$1tle](https://github.com/aws/pg_tle) no GitHub.
**Trusted Language Extensions**
*Trusted Language Extensions* é o nome abreviado de Trusted Language Extensions para PostgreSQL. Esse nome curto e sua abreviatura (TLE) também são utilizados nesta documentação.
**linguagem confiável**
Uma *linguagem confiável* é uma linguagem de programação ou script que tem atributos de segurança específicos. Por exemplo, as linguagens confiáveis geralmente restringem o acesso ao sistema de arquivos e limitam o uso de propriedades de rede especificadas. O kit de desenvolvimento TLE foi projetado para oferecer suporte a linguagens confiáveis. O PostgreSQL é compatível com várias linguagens diferentes que são usadas para criar extensões confiáveis ou não confiáveis. Por exemplo, consulte [Trusted and Untrusted PL/Perl](https://www.postgresql.org/docs/current/plperl-trusted.html) (PL/Perl confiável e não confiável) na documentação do PostgreSQL. Quando você cria uma extensão com o uso de Trusted Language Extensions, a extensão usa inerentemente mecanismos de linguagem confiáveis.
**Extensão TLE**
Uma *extensão TLE* é uma extensão do PostgreSQL criada com o uso do kit de desenvolvimento Trusted Language Extensions (TLE).
# Requisitos para usar Trusted Language Extensions para PostgreSQL
A seguir são apresentados os requisitos para configurar e usar o kit de desenvolvimento TLE.
+ ** Versões do RDS para PostgreSQL**: o Trusted Language Extensions só é compatível com o RDS para PostgreSQL versões 13.12 e versões 13 posteriores, 14.5 e versões 14 posteriores e 15.2 e versões posteriores.
+ Se você precisar atualizar sua instância do RDS para PostgreSQL, consulte [Atualizações do mecanismo de banco de dados do RDS para PostgreSQL](USER_UpgradeDBInstance.PostgreSQL.md).
+ Se você ainda não tem uma instância de banco de dados do Amazon RDS que execute o PostgreSQL, você pode criar uma. Para ter mais informações, consulte Instância de banco de dados do RDS para PostgreSQL, consulte [Criar uma instância de banco de dados PostgreSQL e conectar-se a ela](CHAP_GettingStarted.CreatingConnecting.PostgreSQL.md).
+ **Requer privilégios `rds_superuser`**: para instalar e configurar a extensão `pg_tle`, sua função de usuário do banco de dados deve ter as permissões da função `rds_superuser`. Por padrão, essa função é concedida ao usuário `postgres` que cria o Instância de banco de dados do RDS para PostgreSQL.
+ **Requer um grupo de parâmetros de banco de dados personalizado**: sua instância de banco de dados do RDS para PostgreSQL deve ser configurada com um grupo de parâmetros de banco de dados personalizado.
+ Se sua instância do RDS para PostgreSQL não estiver configurada com um grupo de parâmetros de banco de dados personalizado, você deverá criar um e associá-lo à sua instância de banco de dados do RDS para PostgreSQL. Para obter um breve resumo das etapas, consulte [Criar e aplicar um grupo de parâmetros de banco de dados personalizado](#PostgreSQL_trusted_language_extension-requirements-create-custom-params).
+ Se sua instância de banco de dados do RDS para PostgreSQL já estiver configurada usando um grupo de parâmetros de banco de dados, você poderá configurar o Trusted Language Extensions. Para obter detalhes, consulte [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
## Criar e aplicar um grupo de parâmetros de banco de dados personalizado
Use as etapas a seguir para criar um grupo de parâmetros de banco de dados personalizado e configurar sua instância de banco de dados do RDS para PostgreSQL para usá-lo.
### Console
**Como criar um grupo de parâmetros de banco de dados personalizado e usá-lo com a instância de banco de dados do RDS para PostgreSQL**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon RDS em [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. Selecione Parameter groups (Grupos de parâmetros) no menu do Amazon RDS
1. Escolha **Criar grupo de parâmetros**.
1. Na página **Parameter group details** (Detalhes do grupo de parâmetros), insira as informações a seguir.
+ Em **Parameter group family** (Família de grupos de parâmetros), selecione postgres14.
+ Em **Type** (Tipo), selecione DB Parameter Group (Grupo de parâmetros de banco de dados).
+ Em **Group name** (Nome do grupo), forneça ao seu grupo de parâmetros um nome significativo no contexto de suas operações.
+ Em **Description** (Descrição), insira uma descrição útil para que outras pessoas de sua equipe possam encontrá-lo facilmente.
1. Escolha **Criar**. Seu grupo de parâmetros de banco de dados personalizado é criado em sua Região da AWS. Agora você pode modificar sua instância do RDS para PostgreSQL para usá-la seguindo as próximas etapas.
1. Selecione **Databases** (Bancos de dados) no menu do Amazon RDS.
1. Selecione a instância de banco de dados do RDS para PostgreSQL que você deseja usar com o TLE dentre as opções listadas e, depois, selecione **Modify** (Modificar).
1. Na Na página Modify DB instance settings (Modificar configurações da instância de banco de dados), encontre **Database options** (Opções de banco de dados) na seção Additional configuration (Configuração adicional) e selecione seu grupo de parâmetros de banco de dados personalizado no seletor.
1. Selecione **Continue** (Continuar) para salvar a alteração.
1. Selecione **Apply immediately** (Aplicar imediatamente) para que você possa continuar configurando da instância de banco de dados do RDS para PostgreSQL para usar o TLE.
Para continuar configurando seu sistema para Trusted Language Extensions, consulte [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Para obter mais informações sobre como trabalhar com Grupos de parâmetros do banco de dados, consulte [Grupos de parâmetros de banco de dados para instâncias de banco de dados do Amazon RDS](USER_WorkingWithDBInstanceParamGroups.md).
### AWS CLI
Você pode evitar especificar o argumento `--region` ao usar comandos da CLI configurando sua AWS CLI com sua Região da AWS padrão. Para obter mais informações, consulte [Conceitos básicos de configuração da ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) no *Guia do usuário do AWS Command Line Interface*.
**Como criar um grupo de parâmetros de banco de dados personalizado e usá-lo com a instância de banco de dados do RDS para PostgreSQL**
1. Use o comando [create-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-parameter-group.html) da AWS CLI para criar um grupo de parâmetros de banco de dados personalizado com base em postgres14 para sua Região da AWS.
Para Linux, macOS ou 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"
```
Seu grupo de parâmetros de banco de dados personalizado está disponível em sua Região da AWS, para que você possa modificar a instância de banco de dados do RDS para PostgreSQL para usá-lo.
1. Use o comando [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) da AWS CLI para aplicar seu grupo de parâmetros de banco de dados personalizado à instância de banco de dados do RDS para PostgreSQL. Esse comando reinicia imediatamente a instância ativa.
Para Linux, macOS ou 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 configurando seu sistema para Trusted Language Extensions, consulte [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Para ter mais informações, consulte [Grupos de parâmetros para Amazon RDS](USER_WorkingWithParamGroups.md).
# Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL
As etapas a seguir pressupõem que sua instância de banco de dados do RDS para PostgreSQL esteja associada a um grupo de parâmetros de banco de dados. Você pode usar o Console de gerenciamento da AWS ou a AWS CLI para essas etapas.
Ao configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL, você o instala em um banco de dados específico para uso pelos usuários do banco de dados que têm permissões nesse banco de dados.
## Console
**Como configurar o Trusted Language Extensions**
Execute as etapas a seguir usando uma conta que seja membro do grupo `rds_superuser` (função).
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon RDS em [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. No painel de navegação, selecione sua instância de banco de dados do RDS para PostgreSQL.
1. Abra a guia **Configuration** (Configuração) para sua Instância de banco de dados do RDS para PostgreSQL. Entre os detalhes da instância, encontre o link **Parameter group** (Grupo de parâmetros).
1. Clique no link para abrir os parâmetros personalizados associados ao seu Instância de banco de dados do RDS para PostgreSQL.
1. No campo **Parameters** (Parâmetros), digite `shared_pre` para encontrar o parâmetro `shared_preload_libraries`.
1. Selecione **Edit parameters** (Editar parâmetros) para acessar os valores das propriedades.
1. Adicione `pg_tle` à lista no campo **Values** (Valores). Use uma vírgula para separar itens na lista de valores.
![\[Imagem do parâmetro shared_preload_libraries com pg_tle adicionado.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/apg_rpg_shared_preload_pg_tle.png)
1. Reinicie a instância de banco de dados do RDS para PostgreSQL para que a alteração no parâmetro `shared_preload_libraries` tenha efeito.
1. Quando a instância estiver disponível, verifique se `pg_tle` foi inicializado. Use `psql` para se conectar à instância de banco de dados do RDS para PostgreSQL e depois execute o comando a seguir.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
1. Com a extensão `pg_tle` inicializada, agora você pode criar a extensão.
```
CREATE EXTENSION pg_tle;
```
Para verificar se a extensão está instalada, você pode usar o metacomando `psql` a seguir.
```
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. Conceda a função `pgtle_admin` ao nome de usuário principal que você criou para sua instância de banco de dados do RDS para PostgreSQL ao configurá-la. Se você aceitou o padrão, é `postgres`.
```
labdb=> GRANT pgtle_admin TO postgres;
GRANT ROLE
```
É possível verificar se a concessão ocorreu usando o metacomando `psql` conforme mostrado no exemplo a seguir. Somente as funções `pgtle_admin` e `postgres` são mostradas na saída. Para ter mais informações, consulte [Noções básicas sobre o perfil 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. Feche a sessão `psql` usando o metacomando `\q`.
```
\q
```
Para começar a criar extensões TLE, consulte [Exemplo: Criar uma extensão de linguagem confiável usando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
## AWS CLI
Você pode evitar especificar o argumento `--region` ao usar comandos da CLI configurando sua AWS CLI com sua Região da AWS padrão. Para obter mais informações, consulte [Conceitos básicos de configuração da ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) no *Guia do usuário do AWS Command Line Interface*.
**Como configurar o Trusted Language Extensions**
1. Utilize o comando [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) AWS CLI para adicionar `pg_tle` ao 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. Utilize o comando [reboot-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/reboot-db-instance) da AWS CLI para reinicializar a instância de banco de dados do RDS para PostgreSQL e inicialize a biblioteca `pg_tle`.
```
aws rds reboot-db-instance \
--db-instance-identifier your-instance \
--region aws-region
```
1. Quando a instância estiver disponível, verifique se a `pg_tle` foi inicializada. Use `psql` para se conectar à instância de banco de dados do RDS para PostgreSQL e, depois, execute o comando a seguir.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
Com `pg_tle` inicializado, agora você pode criar a extensão.
```
CREATE EXTENSION pg_tle;
```
1. Conceda a função `pgtle_admin` ao nome de usuário principal que você criou para sua instância de banco de dados do RDS para PostgreSQL ao configurá-la. Se você aceitou o padrão, é `postgres`.
```
GRANT pgtle_admin TO postgres;
GRANT ROLE
```
1. Feche a sessão `psql` da forma a seguir.
```
labdb=> \q
```
Para começar a criar extensões TLE, consulte [Exemplo: Criar uma extensão de linguagem confiável usando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
# Visão geral do Trusted Language Extensions para PostgreSQL
O Trusted Language Extensions para PostgreSQL é uma extensão do PostgreSQL que você instala em sua instância de banco de dados do RDS para PostgreSQL da mesma forma que configura outras extensões do PostgreSQL. Na imagem a seguir de um exemplo de banco de dados na ferramenta cliente pgAdmin, você pode ver alguns dos componentes que compõem a extensão `pg_tle`.
![\[Imagem mostrando alguns dos componentes que compõem o kit de desenvolvimento TLE.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/apg-pg_tle-installed-view-in-pgAdmin.png)
É possível ver os detalhes a seguir.
1. O kit de desenvolvimento Trusted Language Extensions para PostgreSQL é embalado como a extensão `pg_tle`. Assim, o `pg_tle` é adicionado às extensões disponíveis para o banco de dados no qual está instalado.
1. O TLE tem seu próprio esquema, `pgtle`. Esse esquema contém funções auxiliares (3) para instalar e gerenciar as extensões criadas.
1. O TLE fornece mais de uma dúzia de funções auxiliares para instalar, registrar e gerenciar suas extensões. Para saber mais sobre essas funções, consulte [Referência de funções para Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-functions-reference.md).
São outros componentes da extensão `pg_tle`:
+ **A função `pgtle_admin`**: a função `pgtle_admin` é criada quando a extensão `pg_tle` é instalada. Essa função é privilegiada e deve ser tratada como tal. É altamente recomendável seguir o princípio de *privilégio mínimo* ao conceder a função `pgtle_admin` a usuários de banco de dados. Em outras palavras, conceda a função `pgtle_admin` somente aos usuários do banco de dados que tenham permissão para criar, instalar e gerenciar novas extensões TLE, como `postgres`.
+ **A tabela `pgtle.feature_info`**: `pgtle.feature_info` é uma tabela protegida que contém informações sobre seus TLEs, ganchos e as funções e os procedimentos armazenados personalizados utilizados. Se você tiver privilégios `pgtle_admin`, use as funções de Trusted Language Extensions a seguir para adicionar e atualizar essas informações na tabela.
+ [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)
# Criar extensões TLE para RDS para PostgreSQL
Você pode instalar qualquer extensão criada com o TLE em qualquer instância de banco de dados do RDS para PostgreSQL que tenha a extensão `pg_tle` instalada. A extensão `pg_tle` tem como escopo o banco de dados PostgreSQL no qual ela está instalada. As extensões que você cria usando o TLE têm como escopo o mesmo banco de dados.
Use as várias funções `pgtle` para instalar o código que compõe sua extensão TLE. As funções do Trusted Language Extensions a seguir exigem a função `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 (nome)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension (nome, versão)](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)
## Exemplo: Criar uma extensão de linguagem confiável usando SQL
O exemplo a seguir mostra como criar uma extensão TLE chamada `pg_distance` que contém algumas funções SQL para calcular distâncias usando fórmulas diferentes. Na lista, você pode encontrar a função para calcular a distância de Manhattan e a função para calcular a distância euclidiana. Para obter mais informações sobre a diferença entre essas fórmulas, consulte [Geometria taxicab](https://en.wikipedia.org/wiki/Taxicab_geometry) [Geometria euclidiana](https://en.wikipedia.org/wiki/Euclidean_geometry) na Wikipedia.
Você poderá usar esse exemplo em sua própria instância de banco de dados do RDS para PostgreSQL se tiver a extensão `pg_tle` configurada conforme detalhado em [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**nota**
Você precisa ter os privilégios da função `pgtle_admin` para seguir esse procedimento.
**Como criar o exemplo de extensão TLE**
As etapas a seguir usam um exemplo de banco de dados chamado `labdb`. Esse banco de dados é de propriedade do usuário primário `postgres`. A função `postgres` também tem as permissões da função `pgtle_admin`.
1. Use o `psql` para se conectar à Instância de banco de dados do RDS para PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Crie uma extensão TLE denominada `pg_distance` copiando o código a seguir e colando-o no console da sessão `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_$
);
```
Você verá a saída da forma a seguir.
```
install_extension
---------------
t
(1 row)
```
Os artefatos que compõem a extensão `pg_distance` agora estão instalados em seu banco de dados. Esses artefatos incluem o arquivo de controle e o código da extensão, que são itens que precisam estar presentes para que a extensão possa ser criada usando o comando `CREATE EXTENSION`. Em outras palavras, você ainda precisa criar a extensão para disponibilizar suas funções aos usuários do banco de dados.
1. Para criar a extensão, use o comando `CREATE EXTENSION` como você faz com qualquer outra extensão. Assim como acontece com outras extensões, o usuário do banco de dados precisa ter as permissões `CREATE` no banco de dados.
```
CREATE EXTENSION pg_distance;
```
1. Para testar a extensão TLE `pg_distance`, você pode usá-la para calcular a [distância de Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry) entre quatro pontos.
```
labdb=> SELECT manhattan_dist(1, 1, 5, 5);
8
```
Para calcular a [distância euclidiana](https://en.wikipedia.org/wiki/Euclidean_geometry) entre o mesmo conjunto de pontos, você pode usar o seguinte.
```
labdb=> SELECT euclidean_dist(1, 1, 5, 5);
5.656854249492381
```
A extensão `pg_distance` carrega as funções no banco de dados e as disponibiliza para qualquer usuário com permissões no banco de dados.
## Modificar a extensão TLE
Para melhorar a performance da consulta para as funções empacotadas nessa extensão TLE, adicione os dois atributos do PostgreSQL a seguir às suas especificações.
+ `IMMUTABLE`: o atributo `IMMUTABLE` garante que o otimizador de consultas possa usar otimizações para melhorar os tempos de resposta da consulta. Para obter mais informações, consulte [Function Volatility Categories](https://www.postgresql.org/docs/current/xfunc-volatility.html) (Categorias de volatilidade de funções) na documentação do PostgreSQL.
+ `PARALLEL SAFE`: o atributo `PARALLEL SAFE` é outro atributo que permite que o PostgreSQL execute a função no modo paralelo. Para obter mais informações, consulte [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html) na documentação do PostgreSQL.
No exemplo a seguir, você pode ver como a função `pgtle.install_update_path` é usada para adicionar esses atributos a cada função para criar uma versão `0.2` da extensão TLE `pg_distance`. Para ter mais informações sobre essa função, consulte [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path). Você precisa ter a função `pgtle_admin` para realizar essa tarefa.
**Como atualizar uma extensão TLE existente e especificar a versão padrão**
1. Conecte-se à instância de banco de dados do RDS para PostgreSQL usando `psql` ou outra ferramenta de cliente, como o pgAdmin
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Modifique a extensão TLE existente copiando o código a seguir e colando-o no console da sessão `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_$
);
```
Você verá uma resposta semelhante ao seguinte.
```
install_update_path
---------------------
t
(1 row)
```
Você pode tornar essa versão da extensão a versão padrão, para que os usuários do banco de dados não precisem especificar uma versão ao criar ou atualizar a extensão em seu banco de dados.
1. Para especificar que a versão modificada (versão 0.2) de sua extensão TLE é a versão padrão, use a função `pgtle.set_default_version` conforme mostrado no exemplo a seguir.
```
SELECT pgtle.set_default_version('pg_distance', '0.2');
```
Para ter mais informações sobre essa função, consulte [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version).
1. Com o código implementado, você pode atualizar a extensão TLE instalada da maneira usual, utilizando o comando `ALTER EXTENSION ... UPDATE`, conforme mostrado aqui:
```
ALTER EXTENSION pg_distance UPDATE;
```
# Descartar suas extensões TLE de um banco de dados
Você pode descartar suas extensões TLE usando o comando `DROP EXTENSION` da mesma forma que faz com outras extensões do PostgreSQL. Descartar a extensão não remove os arquivos de instalação que a compõem, o que permite aos usuários recriar a extensão. Para remover a extensão e seus arquivos de instalação, execute o processo de duas etapas a seguir.
**Como descartar a extensão TLE e remover seus arquivos de instalação**
1. Use `psql` ou outra ferramenta de cliente para se conectar à instância de banco de dados do RDS para PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Descarte a extensão como você faria com qualquer extensão do PostgreSQL.
```
DROP EXTENSION your-TLE-extension
```
Por exemplo, se você criar a extensão `pg_distance` conforme detalhado em [Exemplo: Criar uma extensão de linguagem confiável usando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example), poderá descartar a extensão da forma a seguir.
```
DROP EXTENSION pg_distance;
```
Você vê uma saída confirmando que a extensão foi descartada da forma a seguir.
```
DROP EXTENSION
```
Neste ponto, a extensão não estará mais ativa no banco de dados. No entanto, seus arquivos de instalação e arquivo de controle ainda estão disponíveis no banco de dados, portanto, os usuários do banco de dados poderão criar a extensão novamente, se desejarem.
+ Se quiser deixar os arquivos de extensão intactos para que os usuários do banco de dados possam criar sua extensão TLE, você pode parar neste ponto.
+ Se quiser remover todos os arquivos que compõem a extensão, siga para a próxima etapa.
1. Para remover todos os arquivos de instalação da sua extensão, use a função `pgtle.uninstall_extension`. Essa função remove todos os arquivos de código e controle de sua extensão.
```
SELECT pgtle.uninstall_extension('your-tle-extension-name');
```
Por exemplo, para remover todos os arquivos de instalação `pg_distance`, use o comando a seguir.
```
SELECT pgtle.uninstall_extension('pg_distance');
uninstall_extension
---------------------
t
(1 row)
```
# Desinstalar o Trusted Language Extensions para PostgreSQL
Se você não quiser mais criar suas próprias extensões TLE usando o TLE, poderá descartar a extensão `pg_tle` e remover todos os artefatos. Essa ação inclui descartar todas as extensões TLE no banco de dados e o esquema `pgtle`.
**Como descartar a extensão `pg_tle` e seu esquema de um banco de dados**
1. Use `psql` ou outra ferramenta de cliente para se conectar à instância de banco de dados do RDS para PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Descarte a extensão `pg_tle` do banco de dados. Se o banco de dados tiver suas próprias extensões TLE ainda em execução no banco de dados, você também precisará descartar essas extensões. Para isso, você pode usar a palavra-chave `CASCADE`, conforme mostrado a seguir.
```
DROP EXTENSION pg_tle CASCADE;
```
Se a extensão `pg_tle` ainda não estiver ativa no banco de dados, você não precisará usar a palavra-chave `CASCADE`.
1. Descarte o esquema `pgtle`. Essa ação remove todas as funções de gerenciamento do banco de dados.
```
DROP SCHEMA pgtle CASCADE;
```
O comando retornará o seguinte quando o processo for concluído.
```
DROP SCHEMA
```
A extensão `pg_tle`, seu esquema e funções e todos os artefatos são removidos. Para criar extensões usando o TLE, execute o processo de configuração novamente. Para ter mais informações, consulte [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
# Usar ganchos do PostgreSQL com suas extensões TLE
Um *gancho* é um mecanismo de retorno de chamada disponível no PostgreSQL que possibilita aos desenvolvedores chamar funções personalizadas ou outras rotinas durante operações regulares de banco de dados. O kit de desenvolvimento TLE é compatível com ganchos do PostgreSQL para que você possa integrar funções personalizadas com o comportamento do PostgreSQL no ambiente de execução. Por exemplo, você pode usar um gancho para associar o processo de autenticação ao seu próprio código personalizado ou modificar o processo de planejamento e execução de consultas de acordo com suas necessidades específicas.
Suas extensões TLE podem usar ganchos. Se um gancho tiver escopo global, ele se aplicará a todos os bancos de dados. Portanto, se sua extensão TLE usar um gancho global, você precisará criar sua extensão TLE em todos os bancos de dados que seus usuários puderem acessar.
Ao usar a extensão `pg_tle` para criar seu próprio Trusted Language Extensions, você pode usar os ganchos disponíveis de uma API SQL para criar as funções de sua extensão. Você deve registrar todos os ganchos com `pg_tle`. Para alguns ganchos, talvez você também precise definir vários parâmetros de configuração. Por exemplo, o gancho de verificação `passcode` pode ser configurado como ativado, desativado ou obrigatório. Para obter mais informações sobre os requisitos específicos dos ganchos `pg_tle` disponíveis, consulte [Referência de ganchos para Trusted Language Extensions para PostgreSQL](PostgreSQL_trusted_language_extension-hooks-reference.md).
## Exemplo: Criar uma extensão que use um gancho do PostgreSQL
O exemplo abordado nesta seção usa um gancho do PostgreSQL para conferir a senha fornecida durante operações específicas de SQL e impede que os usuários do banco de dados definam suas senhas como qualquer uma das contidas na tabela `password_check.bad_passwords`. A tabela contém as dez opções de senhas mais usadas, mas facilmente identificáveis.
Para configurar esse exemplo em sua instância de banco de dados do RDS para PostgreSQL, você já deve ter instalado o Trusted Language Extensions. Para obter detalhes, consulte [Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**Como configurar o exemplo de gancho de verificação de senha**
1. Use o `psql` para se conectar à Instância de banco de dados do RDS para PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Copie o código do [Lista de códigos do gancho de verificação de senha](#PostgreSQL_trusted_language_extension-example-hook_code_listing) e cole-o no banco de dados.
```
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_$
);
```
Quando a extensão for carregada em seu banco de dados, você verá uma saída como a seguinte.
```
install_extension
-------------------
t
(1 row)
```
1. Enquanto ainda estiver conectado ao banco de dados, agora você poderá criar a extensão.
```
CREATE EXTENSION my_password_check_rules;
```
1. Você pode confirmar que a extensão foi criada no banco de dados usando o metacomando `psql` a seguir.
```
\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 outra sessão do terminal para trabalhar com o AWS CLI. Você precisa modificar seu grupo de parâmetros de banco de dados personalizado para ativar o gancho de verificação de senha. Para isso, use o comando [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) da CLI, conforme mostrado no exemplo a seguir.
```
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"
```
Quando o parâmetro é ativado com êxito, você vê uma saída como a seguinte.
```
(
"DBParameterGroupName": "docs-lab-parameters-for-tle"
}
```
Poderá levar alguns minutos para que a alteração na configuração do grupo de parâmetros tenha efeito. No entanto, esse parâmetro é dinâmico, portanto, você não precisa reiniciar a instância de banco de dados do RDS para PostgreSQL para que a configuração tenha efeito.
1. Abra a sessão `psql` e consulte o banco de dados para verificar se o gancho password\$1check foi ativado.
```
labdb=> SHOW pgtle.enable_password_check;
pgtle.enable_password_check
-----------------------------
on
(1 row)
```
O gancho de verificação de senha agora está ativo. É possível testá-lo criando uma função e usando uma das senhas incorretas, conforme mostrado no exemplo a seguir.
```
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)"
```
A saída foi formatada para facilitar a leitura.
O exemplo a seguir mostra que o comportamento do metacomando interativo `pgsql` `\password` também é afetado pelo gancho 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)"
```
Você poderá descartar essa extensão TLE e desinstalar seus arquivos de origem, se desejar. Para obter mais informações, consulte [Descartar suas extensões TLE de um banco de dadosDescartar suas extensões TLE de um banco de dados](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md).
### Lista de códigos do gancho de verificação de senha
O código de exemplo mostrado aqui define a especificação da extensão TLE `my_password_check_rules`. Quando você copia esse código e o cola em seu banco de dados, o código da extensão `my_password_check_rules` é carregado no banco de dados e o gancho `password_check` é registrado para uso pela extensão.
```
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_$
);
```
# Usar tipos de dados personalizados no TLE
O PostgreSQL comporta comandos para registrar novos tipos básicos (também conhecidos como tipos escalares) para lidar de forma eficiente com estruturas de dados complexas no banco de dados. Um tipo básico permite que você personalize como os dados são armazenados internamente e como convertê-los de e em uma representação textual externa. Esses tipos de dados personalizados são úteis ao estender o PostgreSQL para comportar domínios funcionais em que um tipo integrado, como número ou texto, não pode fornecer semântica de pesquisa suficiente.
O RDS para PostgreSQL permite que você crie tipos de dados personalizados em sua extensão de linguagem confiável e defina funções que comportem operações de SQL e indexação para esses novos tipos de dados. Os tipos de dados estão disponíveis para as seguintes versões:
+ RDS para PostgreSQL 15.7 e as versões 15 posteriores
+ RDS para PostgreSQL 14.9 e versões 14 posteriores
+ RDS para PostgreSQL 13.2 e versões 13 posteriores
Para obter mais informações, consulte [Tipos de Trusted Language Base](https://github.com/aws/pg_tle/blob/main/docs/09_datatypes.md).
# Referência de funções para Trusted Language Extensions para PostgreSQL
Veja a documentação de referência a seguir sobre as funções disponíveis em Trusted Language Extensions para PostgreSQL. Use essas funções para instalar, registrar, atualizar e gerenciar suas *extensões TLE*, ou seja, as extensões do PostgreSQL que você desenvolve usando o kit de desenvolvimento 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 (nome)](#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension (nome, versão)](#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
A função `pgtle.available_extensions` é uma função de retorno de conjunto. Ela retorna todas as extensões TLE disponíveis no banco de dados. Cada linha retornada contém informações sobre uma única extensão TLE.
### Protótipo de função
```
pgtle.available_extensions()
```
### Função
Nenhum.
### Argumentos
Nenhum.
### Saída
+ `name`: o nome da extensão TLE.
+ `default_version`: a versão da extensão TLE a ser usada quando `CREATE EXTENSION` é chamada sem uma versão especificada.
+ `description`: uma descrição mais detalhada sobre a extensão TLE.
### Exemplo de uso
```
SELECT * FROM pgtle.available_extensions();
```
## pgtle.available\$1extension\$1versions
A função `available_extension_versions` é de retorno de conjunto. Ela retorna uma lista de todas as extensões TLE disponíveis e suas versões. Cada linha contém informações sobre uma versão específica de determinada extensão TLE, incluindo se ela requer uma função específica.
### Protótipo de função
```
pgtle.available_extension_versions()
```
### Função
Nenhum.
### Argumentos
Nenhum.
### Saída
+ `name`: o nome da extensão TLE.
+ `version`: a versão da extensão TLE.
+ `superuser`: esse valor é sempre `false` para suas extensões TLE. As permissões necessárias para criar a extensão TLE ou atualizá-la são as mesmas para criar outros objetos em determinado banco de dados.
+ `trusted`: esse valor é sempre `false` para uma extensão TLE.
+ `relocatable`: esse valor é sempre `false` para uma extensão TLE.
+ `schema`: especifica o nome do esquema no qual a extensão TLE está instalada.
+ `requires`: uma matriz contendo os nomes de outras extensões necessárias para essa extensão TLE.
+ `description`: uma descrição detalhada da extensão TLE.
Para obter mais informações sobre valores de saída, consulte [Packaging Related Objects into an Extension > Extension Files](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (Compactação de objetos relacionados em uma extensão > arquivos de extensão) na documentação do PostgreSQL.
### Exemplo de uso
```
SELECT * FROM pgtle.available_extension_versions();
```
## pgtle.extension\$1update\$1paths
A função `extension_update_paths` é de retorno de conjunto. Ela retorna uma lista de todos os caminhos de atualização possíveis para uma extensão TLE. Cada linha inclui as atualizações ou downgrades disponíveis para essa extensão TLE.
### Protótipo de função
```
pgtle.extension_update_paths(name)
```
### Função
Nenhum.
### Argumentos
`name`: o nome da extensão TLE da qual obter caminhos de atualização.
### Saída
+ `source`: a versão de origem de uma atualização.
+ `target`: a versão de destino de uma atualização.
+ `path`: o caminho de atualização usado para atualizar uma extensão TLE da versão `source` para a `target`, por exemplo, `0.1--0.2`.
### Exemplo de uso
```
SELECT * FROM pgtle.extension_update_paths('your-TLE');
```
## pgtle.install\$1extension
A função `install_extension` permite que você instale os artefatos que compõem sua extensão TLE no banco de dados, após o qual ela pode ser criada usando o comando `CREATE EXTENSION`.
### Protótipo de função
```
pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])
```
### Função
Nenhum.
### Argumentos
+ `name`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `version`: a versão da extensão TLE.
+ `description`: uma descrição detalhada da extensão TLE. Essa descrição é exibida no campo `comment` em `pgtle.available_extensions()`.
+ `ext`: o conteúdo da extensão TLE. Esse valor contém objetos, como funções.
+ `requires`: um parâmetro opcional que especifica dependências para essa extensão TLE. A extensão `pg_tle` é adicionada automaticamente como uma dependência.
Muitos desses argumentos são iguais aos incluídos em um arquivo de controle de extensão para instalar uma extensão do PostgreSQL no sistema de arquivos de uma instância do PostgreSQL. Para obter mais informações, consulte [Extension Files](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (Arquivos de extensão) em [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (Compactação de objetos relacionados em uma extensão) na documentação do PostgreSQL.
### Saída
Essa função retorna `OK` em caso de sucesso e `NULL` em caso de erro.
+ `OK`: a extensão TLE foi instalada com êxito no banco de dados.
+ `NULL`: a extensão TLE não foi instalada com êxito no banco de dados.
### Exemplo 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
A função `install_update_path` fornece um caminho de atualização entre duas versões diferentes de uma extensão TLE. Essa função permite que os usuários de sua extensão TLE atualizem sua versão usando a sintaxe `ALTER EXTENSION ... UPDATE`.
### Protótipo de função
```
pgtle.install_update_path(name text, fromvers text, tovers text, ext text)
```
### Função
`pgtle_admin`
### Argumentos
+ `name`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `fromvers`: a versão de origem da extensão TLE para a atualização.
+ `tovers`: a versão de destino da extensão TLE para a atualização.
+ `ext`: o conteúdo da atualização. Esse valor contém objetos, como funções.
### Saída
Nenhum.
### Exemplo 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
A função `register_feature` adiciona o recurso interno especificado do PostgreSQL à tabela `pgtle.feature_info`. Os ganchos do PostgreSQL são um exemplo de um recurso interno do PostgreSQL. O kit de desenvolvimento Trusted Language Extensions é compatível com o uso de ganchos do PostgreSQL. Atualmente, essa função é compatível com o recurso a seguir.
+ `passcheck`: registra o gancho de verificação de senha com seu procedimento ou função que personaliza o comportamento de verificação de senha do PostgreSQL.
### Protótipo de função
```
pgtle.register_feature(proc regproc, feature pg_tle_feature)
```
### Função
`pgtle_admin`
### Argumentos
+ `proc`: o nome de uma função ou um procedimento armazenado a ser usado para o recurso.
+ `feature`: o nome do recurso `pg_tle` (como`passcheck`) a ser registrado na função.
### Saída
Nenhum.
### Exemplo de uso
```
SELECT pgtle.register_feature('pw_hook', 'passcheck');
```
## pgtle.register\$1feature\$1if\$1not\$1exists
A função `pgtle.register_feature_if_not_exists` adiciona o recurso do PostgreSQL especificado à tabela `pgtle.feature_info` e identifica a extensão TLE ou outro procedimento ou função que usa o recurso. Para obter mais informações sobre ganchos e Trusted Language Extensions, consulte[Usar ganchos do PostgreSQL com suas extensões TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md).
### Protótipo de função
```
pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)
```
### Função
`pgtle_admin`
### Argumentos
+ `proc`: o nome de uma função ou um procedimento armazenado que contém a lógica (código) a ser usada como um recurso para sua extensão TLE. Por exemplo, o código `pw_hook`.
+ `feature`: o nome do recurso do PostgreSQL a ser registrado na função TLE. Atualmente, o único recurso disponível é o gancho `passcheck`. Para ter mais informações, consulte [Gancho de verificação de senha (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook).
### Saída
Retorna `true` após registrar o recurso para a extensão especificada. Retorna `false` se o recurso já estiver registrado.
### Exemplo de uso
```
SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck');
```
## pgtle.set\$1default\$1version
A função `set_default_version` permite que você especifique uma `default_version` para sua extensão TLE. Você pode usar essa função para definir um caminho de atualização e designar a versão como padrão para sua extensão TLE. Quando os usuários do banco de dados especificam sua extensão TLE nos comandos `CREATE EXTENSION` e `ALTER EXTENSION ... UPDATE`, essa versão da extensão TLE é criada no banco de dados para esse usuário.
Essa função retorna `true` em caso de êxito. Se a extensão TLE especificada no argumento `name` não existir, a função retornará um erro. Da mesma forma, se a `version` da extensão TLE não existir, ela retornará um erro.
### Protótipo de função
```
pgtle.set_default_version(name text, version text)
```
### Função
`pgtle_admin`
### Argumentos
+ `name`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `version`: a versão da extensão TLE para definir o padrão.
### Saída
+ `true`: quando a configuração da versão padrão é bem-sucedida, a função retorna `true`.
+ `ERROR`: retornará uma mensagem de erro se uma extensão TLE com o nome ou versão especificados não existir.
### Exemplo de uso
```
SELECT * FROM pgtle.set_default_version('my-extension', '1.1');
```
## pgtle.uninstall\$1extension (nome)
A função `uninstall_extension` remove todas as versões de uma extensão TLE de um banco de dados. Essa função impede que futuras chamadas de `CREATE EXTENSION` instalem a extensão TLE. Se a extensão TLE não existir no banco de dados, um erro será gerado.
A função `uninstall_extension` não descartará uma extensão TLE se ela estiver atualmente ativa no banco de dados. Para remover uma extensão TLE que está ativa no momento, você precisa chamar explicitamente `DROP EXTENSION` para removê-la.
### Protótipo de função
```
pgtle.uninstall_extension(extname text)
```
### Função
`pgtle_admin`
### Argumentos
+ `extname`: o nome da extensão TLE a ser desinstalada. Esse nome é o mesmo usado com `CREATE EXTENSION` para carregar a extensão TLE para uso em determinado banco de dados.
### Saída
Nenhum.
### Exemplo de uso
```
SELECT * FROM pgtle.uninstall_extension('pg_tle_test');
```
## pgtle.uninstall\$1extension (nome, versão)
A função `uninstall_extension(name, version)` remove a versão especificada da extensão TLE do banco de dados. Essa função impede que `CREATE EXTENSION` e `ALTER EXTENSION` instalem ou atualizem uma extensão TLE para a versão especificada. Essa função também remove todos os caminhos de atualização para a versão especificada da extensão TLE. Essa função não desinstalará a extensão TLE se ela estiver atualmente ativa no banco de dados. Você deve chamar explicitamente `DROP EXTENSION` para remover a extensão TLE. Para desinstalar todas as versões de uma extensão TLE, consulte[pgtle.uninstall\$1extension (nome)](#pgtle.uninstall_extension-name).
### Protótipo de função
```
pgtle.uninstall_extension(extname text, version text)
```
### Função
`pgtle_admin`
### Argumentos
+ `extname`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `version`: a versão da extensão TLE a ser desinstalada do banco de dados.
### Saída
Nenhum.
### Exemplo de uso
```
SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2');
```
## pgtle.uninstall\$1extension\$1if\$1exists
A função `uninstall_extension_if_exists` remove todas as versões de uma extensão TLE de determinado banco de dados. Se a extensão TLE não existir, a função retornará silenciosamente (nenhuma mensagem de erro será gerada). Se a extensão especificada estiver atualmente ativa em um banco de dados, essa função não a descartará. Você deve chamar explicitamente `DROP EXTENSION` para remover a extensão TLE antes de usar essa função para desinstalar seus artefatos.
### Protótipo de função
```
pgtle.uninstall_extension_if_exists(extname text)
```
### Função
`pgtle_admin`
### Argumentos
+ `extname`: o nome da extensão TLE. Esse valor é usado ao chamar `CREATE EXTENSION`.
### Saída
A função `uninstall_extension_if_exists` retorna `true` após a desinstalação da extensão especificada. Se a extensão especificada não existir, a função retornará `false`.
+ `true`: retorna `true` após a desinstalação da extensão TLE.
+ `false`: retorna `false` quando a extensão TLE não existe no banco de dados.
### Exemplo de uso
```
SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test');
```
## pgtle.uninstall\$1update\$1path
A função `uninstall_update_path` remove o caminho de atualização especificado de uma extensão TLE. Isso impede `ALTER EXTENSION ... UPDATE TO` de usar isso como um caminho de atualização.
Se a extensão TLE estiver sendo usada atualmente por uma das versões desse caminho de atualização, ela permanecerá no banco de dados.
Se o caminho de atualização especificado não existir, essa função gerará um erro.
### Protótipo de função
```
pgtle.uninstall_update_path(extname text, fromvers text, tovers text)
```
### Função
`pgtle_admin`
### Argumentos
+ `extname`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `fromvers`: a versão de origem da extensão TLE usada no caminho de atualização.
+ `tovers`: a versão de destino da extensão TLE usada no caminho de atualização.
### Saída
Nenhum.
### Exemplo de uso
```
SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2');
```
## pgtle.uninstall\$1update\$1path\$1if\$1exists
A função `uninstall_update_path_if_exists` é semelhante a `uninstall_update_path` no sentido de remover o caminho de atualização especificado de uma extensão TLE. No entanto, se o caminho de atualização não existir, essa função não gerará uma mensagem de erro. Em vez disso, a função retornará `false`.
### Protótipo de função
```
pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text)
```
### Função
`pgtle_admin`
### Argumentos
+ `extname`: o nome da extensão TLE. Esse valor é usado ao chamar`CREATE EXTENSION`.
+ `fromvers`: a versão de origem da extensão TLE usada no caminho de atualização.
+ `tovers`: a versão de destino da extensão TLE usada no caminho de atualização.
### Saída
+ `true`: a função atualizou com êxito o caminho da extensão TLE.
+ `false`: a função não conseguiu atualizar o caminho da extensão TLE.
### Exemplo de uso
```
SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2');
```
## pgtle.unregister\$1feature
A função `unregister_feature` fornece uma maneira de remover funções que foram registradas para usar recursos `pg_tle`, como ganchos. Para obter informações sobre como registrar uma recurso, consulte [pgtle.register\$1feature](#pgtle.register_feature).
### Protótipo de função
```
pgtle.unregister_feature(proc regproc, feature pg_tle_features)
```
### Função
`pgtle_admin`
### Argumentos
+ `proc`: o nome de uma função armazenada a ser registrada em um recurso `pg_tle`.
+ `feature`: o nome do recurso `pg_tle` a ser registrado na função. Por exemplo, `passcheck` é um recurso que pode ser registrado para uso pelas extensões de linguagem confiáveis desenvolvidas por você. Para ter mais informações, consulte [Gancho de verificação de senha (passcheck)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook).
### Saída
Nenhum.
### Exemplo de uso
```
SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');
```
## pgtle.unregister\$1feature\$1if\$1exists
A função `unregister_feature` fornece uma maneira de remover funções que foram registradas para usar recursos `pg_tle`, como ganchos. Para ter mais informações, consulte [Usar ganchos do PostgreSQL com suas extensões TLE](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). Retorna `true` após cancelar o registro do recurso com êxito. Retorna `false` se o recurso não foi registrado.
Para obter informações sobre como registrar recursos `pg_tle` para suas extensões TLE, consulte [pgtle.register\$1feature](#pgtle.register_feature).
### Protótipo de função
```
pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')
```
### Função
`pgtle_admin`
### Argumentos
+ `proc`: o nome da função armazenada que foi registrada para incluir um recurso `pg_tle`.
+ `feature`: o nome do recurso `pg_tle` que foi registrado com a extensão de linguagem confiável.
### Saída
Retorna `true` ou `false` da maneira a seguir.
+ `true`: a função cancelou com êxito o registro do recurso da extensão.
+ `false`: a função não conseguiu cancelar o registro do recurso da extensão TLE.
### Exemplo de uso
```
SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck');
```
# Referência de ganchos para Trusted Language Extensions para PostgreSQL
O Trusted Language Extensions para PostgreSQL é compatível com ganchos do PostgreSQL. Um *gancho* é um mecanismo interno de retorno de chamada disponível para que os desenvolvedores estendam a funcionalidade principal do PostgreSQL. Usando ganchos, os desenvolvedores podem implementar suas próprias funções ou procedimentos para uso durante várias operações de banco de dados, modificando assim o comportamento do PostgreSQL de alguma forma. Por exemplo, você pode usar um gancho `passcheck` para personalizar a forma como o PostgreSQL manipula as senhas fornecidas ao criar ou alterar senhas para usuários (funções).
Veja a documentação a seguir para saber mais sobre o hook passcheck disponível para as extensões TLE. Para saber mais sobre os hooks disponíveis, incluindo o hook de autenticação do cliente, consulte [Trusted Language Extensions hooks](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md).
## Gancho de verificação de senha (passcheck)
O gancho `passcheck` é usado para personalizar o comportamento do PostgreSQL durante o processo de verificação de senha para os comandos SQL e o metacomando `psql` a seguir.
+ `CREATE ROLE username ...PASSWORD`: para obter mais informações, consulte [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) na documentação do PostgreSQL.
+ `ALTER ROLE username...PASSWORD`: para obter mais informações, consulte [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html) na documentação do PostgreSQL.
+ `\password username`: esse metacomando interativo `psql` altera com segurança a senha do usuário especificado usando o hash da senha antes de usar a sintaxe `ALTER ROLE ... PASSWORD` de forma transparente. O metacomando é um invólucro seguro para o comando `ALTER ROLE ... PASSWORD`, portanto, o gancho se aplica ao comportamento do metacomando `psql`.
Para ver um exemplo, consulte [Lista de códigos do gancho de verificação de senha](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing).
**Contents**
+ [Protótipo de função](#passcheck_hook-prototype)
+ [Argumentos](#passcheck_hook-arguments)
+ [Configuração](#passcheck_hook-configuration)
+ [Observações de uso](#passcheck_hook-usage)
### Protótipo de função
```
passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
```
### Argumentos
A função de gancho `passcheck` usa os seguintes argumentos:
+ `username`: o nome (como texto) da função (nome de usuário) que está definindo uma senha.
+ `password`: o texto simples ou a senha com hash. A senha digitada deve corresponder ao tipo especificado em `password_type`.
+ `password_type`: especifique o formato `pgtle.password_type` da senha. Esse formato pode ser uma das opções a seguir.
+ `PASSWORD_TYPE_PLAINTEXT`: uma senha de texto simples.
+ `PASSWORD_TYPE_MD5`: uma senha que foi criptografada usando o algoritmo MD5 (resumo de mensagens 5).
+ `PASSWORD_TYPE_SCRAM_SHA_256`: uma senha que foi criptografada usando o algoritmo SCRAM-SHA-256.
+ `valid_until`: especifique a hora em que a senha se torna inválida. Esse argumento é opcional. Se você usar esse argumento, especifique a hora como um valor `timestamptz`.
+ `valid_null`: se esse valor booliano estiver definido como `true`, a opção `valid_until` será definida como `NULL`.
### Configuração
A função `pgtle.enable_password_check` controla se o gancho passcheck está ativo. O gancho passcheck tem três configurações possíveis.
+ `off`: desativa o gancho de verificação de senha `passcheck`. Este é o valor padrão.
+ `on`: ativa o gancho de verificação de senha `passcode` para que as senhas sejam conferidas na tabela.
+ `require`: requer que um gancho de verificação de senha seja definido.
### Observações de uso
Para ativar ou desativar o gancho `passcheck`, você precisa modificar o grupo de parâmetros de banco de dados personalizado para a instância de banco de dados do RDS para PostgreSQL.
Para Linux, macOS ou 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"
```