# 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'); ```