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
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 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.
Tópicos
- Terminologia
- Requisitos para usar Trusted Language Extensions para PostgreSQL
- Configurar o Trusted Language Extensions em sua instância de banco de dados do RDS para PostgreSQL
- Visão geral do Trusted Language Extensions para PostgreSQL
- Criar extensões TLE para RDS para PostgreSQL
- Descartar suas extensões TLE de um banco de dados
- Desinstalar o Trusted Language Extensions para PostgreSQL
- Usar ganchos do PostgreSQL com suas extensões TLE
- Usar tipos de dados personalizados no TLE
- Referência de funções para Trusted Language Extensions para PostgreSQL
- Referência de ganchos para Trusted Language Extensions para PostgreSQL
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_tleno 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
(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 Atualizar o mecanismo de banco de dados PostgreSQL para Amazon RDS.
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.
Requer privilégios
rds_superuser
: para instalar e configurar a extensãopg_tle
, sua função de usuário do banco de dados deve ter as permissões da funçãords_superuser
. Por padrão, essa função é concedida ao usuáriopostgres
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.
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.
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.
Como criar um grupo de parâmetros de banco de dados personalizado e usá-lo com sua instância de banco de dados do RDS para PostgreSQL
Faça login no AWS Management Console e abra o console do Amazon RDS em https://console.aws.amazon.com/rds/
. Selecione Parameter groups (Grupos de parâmetros) no menu do Amazon RDS
Escolha Create parameter group (Criar grupo de parâmetros).
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.
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.
Selecione Databases (Bancos de dados) no menu do Amazon RDS.
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).
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.
Selecione Continue (Continuar) para salvar a alteração.
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.
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.
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 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 sua instância de banco de dados do RDS para PostgreSQL
Use o comando create-db-parameter-group 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-namecustom-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-namecustom-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.
Use o comando modify-db-instance 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-identifieryour-instance-name
\ --db-parameter-group-namecustom-params-for-pg-tle
\ --apply-immediatelyPara Windows:
aws rds modify-db-instance ^ --region
aws-region
^ --db-instance-identifieryour-instance-name
^ --db-parameter-group-namecustom-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.
Para obter mais informações, consulte Grupos de parâmetros para Amazon RDS.
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 AWS Management Console 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.
Como configurar o Trusted Language Extensions
Execute as etapas a seguir usando uma conta que seja membro do grupo rds_superuser
(função).
Faça login no AWS Management Console e abra o console do Amazon RDS em https://console.aws.amazon.com/rds/
. -
No painel de navegação, selecione sua instância de banco de dados do RDS para PostgreSQL.
-
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).
-
Clique no link para abrir os parâmetros personalizados associados ao seu Instância de banco de dados do RDS para PostgreSQL.
-
No campo Parameters (Parâmetros), digite
shared_pre
para encontrar o parâmetroshared_preload_libraries
. -
Selecione Edit parameters (Editar parâmetros) para acessar os valores das propriedades.
-
Adicione
pg_tle
à lista no campo Values (Valores). Use uma vírgula para separar itens na lista de valores. 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.Quando a instância estiver disponível, verifique se
pg_tle
foi inicializado. Usepsql
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 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
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çõespgtle_admin
epostgres
são mostradas na saída. Para ter mais informações, consulte Noções básicas sobre o perfil rds_superuser.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 |...
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.
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 no Guia do usuário do AWS Command Line Interface.
Como configurar o Trusted Language Extensions
Utilize o comando modify-db-parameter-group AWS CLI para adicionar
pg_tle
ao parâmetroshared_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" \ --regionaws-region
-
Utilize o comando 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
\ --regionaws-region
Quando a instância estiver disponível, verifique se a
pg_tle
foi inicializada. Usepsql
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;
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
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.
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.](images/apg-pg_tle-installed-view-in-pgAdmin.png)
É possível ver os detalhes a seguir.
-
O kit de desenvolvimento Trusted Language Extensions para PostgreSQL é embalado como a extensão
pg_tle
. Assim, opg_tle
é adicionado às extensões disponíveis para o banco de dados no qual está instalado. O TLE tem seu próprio esquema,
pgtle
. Esse esquema contém funções auxiliares (3) para instalar e gerenciar as extensões criadas.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.
São outros componentes da extensão pg_tle
:
A função
pgtle_admin
: a funçãopgtle_admin
é criada quando a extensãopg_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çãopgtle_admin
a usuários de banco de dados. Em outras palavras, conceda a funçãopgtle_admin
somente aos usuários do banco de dados que tenham permissão para criar, instalar e gerenciar novas extensões TLE, comopostgres
.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égiospgtle_admin
, use as funções de Trusted Language Extensions a seguir para adicionar e atualizar essas informações na tabela.
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
.
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
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.
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
.
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=labdbCrie uma extensão TLE denominada
pg_distance
copiando o código a seguir e colando-o no console da sessãopsql
.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 comandoCREATE EXTENSION
. Em outras palavras, você ainda precisa criar a extensão para disponibilizar suas funções aos usuários do banco de dados.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õesCREATE
no banco de dados.CREATE EXTENSION pg_distance;
Para testar a extensão TLE
pg_distance
, você pode usá-la para calcular a distância de Manhattanentre quatro pontos. labdb=>
SELECT manhattan_dist(1, 1, 5, 5);
8
Para calcular a distância euclidiana
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 atributoIMMUTABLE
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(Categorias de volatilidade de funções) na documentação do PostgreSQL. PARALLEL SAFE
: o atributoPARALLEL SAFE
é outro atributo que permite que o PostgreSQL execute a função no modo paralelo. Para obter mais informações, consulte CREATE FUNCTIONna 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_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
Conecte-se à instância de banco de dados do RDS para PostgreSQL usando
psql
ou outra ferramenta de cliente, como o pgAdminpsql --host=
db-instance-123456789012
.aws-region
.rds.amazonaws.com --port=5432
--username=postgres
--password --dbname=labdbModifique 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.
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_default_version.
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
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
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, 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.
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
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
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-chaveCASCADE
, 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-chaveCASCADE
.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.
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.
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.
Como configurar o exemplo de gancho de verificação de senha
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
Copie o código do Lista de códigos do gancho de verificação de senha 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 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)
Enquanto ainda estiver conectado ao banco de dados, agora você poderá criar a extensão.
CREATE EXTENSION my_password_check_rules;
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)
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 da CLI, conforme mostrado no exemplo a seguir.
aws rds modify-db-parameter-group \ --region
aws-region
\ --db-parameter-group-nameyour-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.
Abra a sessão
psql
e consulte o banco de dados para verificar se o gancho password_check 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_check.
postgres=>
SET password_encryption TO 'md5';SET
postgres=>
\passwordEnter 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 ter mais informações, consulte Descartar suas extensões TLE de um banco de dados.
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 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