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.

pgtle.available_extensions

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

Exemplo de uso

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

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

Para obter mais informações sobre valores de saída, consulte Packaging Related Objects into an Extension > Extension Files (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_update_paths

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

Exemplo de uso

SELECT * FROM pgtle.extension_update_paths('your-TLE');

pgtle.install_extension

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

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 (Arquivos de extensão) em Packaging Related Objects into an Extension (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.

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_update_path

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

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_feature

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.

Protótipo de função

pgtle.register_feature(proc regproc, feature pg_tle_feature)

Função

pgtle_admin

Argumentos

Saída

Nenhum.

Exemplo de uso

SELECT pgtle.register_feature('pw_hook', 'passcheck');

pgtle.register_feature_if_not_exists

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, consulteUsar ganchos do PostgreSQL com suas extensões TLE.

Protótipo de função

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

Função

pgtle_admin

Argumentos

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_default_version

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

Saída

Exemplo de uso

SELECT * FROM pgtle.set_default_version('my-extension', '1.1');

pgtle.uninstall_extension (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

Saída

Nenhum.

Exemplo de uso

SELECT * FROM pgtle.uninstall_extension('pg_tle_test');

pgtle.uninstall_extension (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, consultepgtle.uninstall_extension (nome).

Protótipo de função

pgtle.uninstall_extension(extname text, version text)

Função

pgtle_admin

Argumentos

Saída

Nenhum.

Exemplo de uso

SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2');

pgtle.uninstall_extension_if_exists

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

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.

Exemplo de uso

SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test');

pgtle.uninstall_update_path

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

Saída

Nenhum.

Exemplo de uso

SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2');

pgtle.uninstall_update_path_if_exists

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

Saída

Exemplo de uso

SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2');

pgtle.unregister_feature

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_feature.

Protótipo de função

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

Função

pgtle_admin

Argumentos

Saída

Nenhum.

Exemplo de uso

SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');

pgtle.unregister_feature_if_exists

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. 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_feature.

Protótipo de função

pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')

Função

pgtle_admin

Argumentos

Saída

Retorna true ou false da maneira a seguir.

Exemplo de uso

SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck');