# Criar extensões TLE para RDS para PostgreSQL
<a name="PostgreSQL_trusted_language_extension-creating-TLE-extensions"></a>

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
<a name="PostgreSQL_trusted_language_extension-simple-example"></a>

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
<a name="PostgreSQL_trusted_language_extension-simple-example.modify"></a>

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;
   ```