Riferimento sulle funzioni per Trusted Language Extensions per PostgreSQL - Amazon Relational Database Service
pgtle.available_extensionspgtle.available_extension_versionspgtle.extension_update_pathspgtle.install_extensionpgtle.install_update_pathpgtle.register_featurepgtle.register_feature_if_not_existspgtle.set_default_versionpgtle.uninstall_extensionpgtle.uninstall_extensionpgtle.uninstall_extension_if_existspgtle.uninstall_update_pathpgtle.uninstall_update_path_if_existspgtle.unregister_featurepgtle.unregister_feature_if_exists

Riferimento sulle funzioni per Trusted Language Extensions per PostgreSQL

Esamina la seguente documentazione di riferimento sulle funzioni disponibili in Trusted Language Extensions per PostgreSQL. Usa queste funzioni per installare, registrare, aggiornare e gestire le tue estensioni TLE, ovvero le estensioni di PostgreSQL che sviluppi utilizzando il kit di sviluppo Trusted Language Extensions.

pgtle.available_extensions

La funzione pgtle.available_extensions è progettata per restituire un set. Restituisce tutte le estensioni TLE disponibili nel database. Ogni riga restituita contiene informazioni su una singola estensione TLE.

Prototipo di funzione

pgtle.available_extensions()

Ruolo

Nessuna.

Argomenti

Nessuna.

Output

  • name: il nome dell'estensione TLE.

  • default_version: la versione dell'estensione TLE da usare quando la funzione CREATE EXTENSION viene chiamata senza una versione specifica.

  • description: una descrizione più dettagliata dell'estensione TLE.

Esempio di utilizzo

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

La funzione available_extension_versions è progettata per restituire un set. Restituisce l'elenco di tutte le estensioni TLE disponibili e le relative versioni. Ogni riga contiene informazioni su una versione specifica dell'estensione TLE indicata, incluso se è richiesto un ruolo specifico.

Prototipo di funzione

pgtle.available_extension_versions()

Ruolo

Nessuna.

Argomenti

Nessuna.

Output

  • name: il nome dell'estensione TLE.

  • version: la versione dell'estensione TLE.

  • superuser: questo valore è sempre false per le estensioni TLE. Le autorizzazioni necessarie per creare o aggiornare l'estensione TLE sono uguali a quelle per creare altri oggetti nel database specificato.

  • trusted: questo valore è sempre false per un'estensione TLE.

  • relocatable: questo valore è sempre false per un'estensione TLE.

  • schema: specifica il nome dello schema in cui è installata l'estensione TLE.

  • requires: un array contenente i nomi di altre estensioni necessarie a questa estensione TLE.

  • description: una descrizione dettagliata dell'estensione TLE.

Per ulteriori informazioni sulle estensioni di PostgreSQL, consulta Packaging Related Objects into an Extension > Extension Files (Creazione di pacchetti di oggetti correlati in un'estensione > File di estensione) nella documentazione PostgreSQL.

Esempio di utilizzo

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

La funzione extension_update_paths è progettata per restituire un set. Restituisce l'elenco di tutti i possibili percorsi di aggiornamento per un'estensione TLE. Ogni riga include gli aggiornamenti o i downgrade disponibili per l'estensione TLE.

Prototipo di funzione

pgtle.extension_update_paths(name)

Ruolo

Nessuna.

Argomenti

name: il nome dell'estensione TLE da cui ottenere i percorsi di aggiornamento.

Output

  • source: la versione di origine di un aggiornamento.

  • target: la versione di destinazione di un aggiornamento.

  • path: il percorso di aggiornamento utilizzato per aggiornare un'estensione TLE dalla versione source alla versione target, ad esempio0.1--0.2.

Esempio di utilizzo

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

pgtle.install_extension

La funzione install_extension consente di installare gli artefatti che costituiscono l'estensione TLE nel database, dopodiché può essere creata utilizzando il comando CREATE EXTENSION.

Prototipo di funzione

pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])

Ruolo

Nessuna.

Argomenti

  • name: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • version: la versione dell'estensione TLE.

  • description: una descrizione dettagliata dell'estensione TLE. Questa descrizione viene visualizzata nel campo comment in pgtle.available_extensions().

  • ext: il contenuto dell'estensione TLE. Questo valore include gli oggetti, come le funzioni.

  • requires: un parametro facoltativo che specifica le dipendenze per l'estensione TLE. L'estensione pg_tle viene aggiunta automaticamente come dipendenza.

Molti di questi argomenti sono uguali a quelli inclusi in un file di controllo delle estensioni per l'installazione di un'estensione di PostgreSQL nel file system di un'istanza PostgreSQL. Per ulteriori informazioni, consulta Extension Files (File di estensione) in Packaging Related Objects into an Extension (Creazione di pacchetti di oggetti correlati in un'estensione) nella documentazione PostgreSQL.

Output

Questa funzione restituisce OK in caso di esito positivo e NULL in caso di errore.

  • OK: l'estensione TLE è stata installata correttamente nel database.

  • NULL: l'estensione TLE non è stata installata correttamente nel database.

Esempio di utilizzo

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

La funzione install_update_path fornisce il percorso di aggiornamento tra due diverse versioni di un'estensione TLE. Questa funzione consente agli utenti dell'estensione TLE di aggiornarne la versione utilizzando la sintassi ALTER EXTENSION ... UPDATE.

Prototipo di funzione

pgtle.install_update_path(name text, fromvers text, tovers text, ext text)

Ruolo

pgtle_admin

Argomenti

  • name: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • fromvers: la versione di origine dell'estensione TLE per l'aggiornamento.

  • tovers: la versione di destinazione dell'estensione TLE per l'aggiornamento.

  • ext: i contenuti dell'aggiornamento. Questo valore include gli oggetti, come le funzioni.

Output

Nessuna.

Esempio di utilizzo

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

La funzione register_feature aggiunge la funzionalità PostgreSQL interna specificata alla tabella pgtle.feature_info. Gli hook PostgreSQL sono un esempio di funzionalità interna di PostgreSQL. Il kit di sviluppo Trusted Language Extensions supporta l'uso degli hook PostgreSQL. Attualmente, questa funzione supporta la seguente funzionalità.

  • passcheck: registra l'hook di verifica della password con la procedura o la funzione che personalizza il comportamento di verifica della password di PostgreSQL.

Prototipo di funzione

pgtle.register_feature(proc regproc, feature pg_tle_feature)

Ruolo

pgtle_admin

Argomenti

  • proc: il nome di una procedura o funzione memorizzata da utilizzare per la funzionalità.

  • feature: il nome della funzionalità pg_tle (ad esempio passcheck) da registrare con la funzione.

Output

Nessuna.

Esempio di utilizzo

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

pgtle.register_feature_if_not_exists

La funzione pgtle.register_feature_if_not_exists aggiunge la funzionalità PostgreSQL specificata alla tabella pgtle.feature_info e identifica l'estensione TLE o un'altra procedura o funzione che utilizza la funzionalità. Per ulteriori informazioni sugli hook e su Trusted Language Extensions, consulta Utilizzo di hook PostgreSQL con le estensioni TLE.

Prototipo di funzione

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

Ruolo

pgtle_admin

Argomenti

  • proc: il nome di una stored procedure o una funzione che contiene la logica (codice) da utilizzare come funzionalità dell'estensione TLE. Ad esempio, il codice pw_hook.

  • feature: il nome della funzionalità PostgreSQL da registrare per la funzione TLE. Attualmente, l'unica funzionalità disponibile è l'hook passcheck. Per ulteriori informazioni, consulta Hook di verifica della password (passcheck).

Output

Restituisce true dopo aver registrato la funzionalità per l'estensione specificata. Restituisce false se la funzionalità è già registrata.

Esempio di utilizzo

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

pgtle.set_default_version

La funzione set_default_version ti consente di specificare una default_version per la tua estensione TLE. È possibile utilizzare questa funzione per definire un percorso di aggiornamento e designare la versione come predefinita per l'estensione TLE. Quando gli utenti del database specificano l'estensione TLE nei comandi CREATE EXTENSION e ALTER EXTENSION ... UPDATE, la versione specificata dell'estensione TLE viene creata nel database per tali utenti.

Questa funzione restituisce true in caso di esito positivo. Se l'estensione TLE specificata nell'argomento name non esiste, la funzione restituisce un errore. Analogamente, se la version dell'estensione TLE non esiste, la funzione restituisce un errore.

Prototipo di funzione

pgtle.set_default_version(name text, version text)

Ruolo

pgtle_admin

Argomenti

  • name: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • version: la versione dell'estensione TLE da impostare come predefinita.

Output

  • true: quando l'impostazione della versione predefinita ha esito positivo, la funzione restituisce true.

  • ERROR: restituisce un messaggio di errore se non esiste un'estensione TLE con il nome o la versione specificati.

Esempio di utilizzo

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

pgtle.uninstall_extension(name)

La funzione uninstall_extension rimuove tutte le versioni di un'estensione TLE da un database. Questa funzione impedisce alle future chiamate CREATE EXTENSION di installare l'estensione TLE. Se l'estensione TLE non esiste nel database, viene generato un errore.

La funzione uninstall_extension non elimina un'estensione TLE attualmente attiva nel database. Per rimuovere un'estensione TLE attualmente attiva, è necessario chiamare esplicitamente DROP EXTENSION per rimuoverla.

Prototipo di funzione

pgtle.uninstall_extension(extname text)

Ruolo

pgtle_admin

Argomenti

  • extname: il nome dell'estensione TLE da disinstallare. Questo nome è quello utilizzato con CREATE EXTENSION per caricare l'estensione TLE da usare in un determinato database.

Output

Nessuna.

Esempio di utilizzo

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

pgtle.uninstall_extension(name, version)

La funzione uninstall_extension(name, version) rimuove la versione specificata dell'estensione TLE dal database. Questa funzione impedisce alle chiamate CREATE EXTENSION e ALTER EXTENSION di installare o aggiornare un'estensione TLE alla versione specificata. Questa funzione rimuove anche tutti i percorsi di aggiornamento per la versione specificata dell'estensione TLE. La funzione non disinstalla l'estensione TLE se è attualmente attiva nel database. È necessario chiamare esplicitamente DROP EXTENSION per rimuovere l'estensione TLE. Per disinstallare tutte le versioni di un'estensione TLE, consulta pgtle.uninstall_extension(name).

Prototipo di funzione

pgtle.uninstall_extension(extname text, version text)

Ruolo

pgtle_admin

Argomenti

  • extname: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • version: la versione dell'estensione TLE da disinstallare dal database.

Output

Nessuna.

Esempio di utilizzo

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

pgtle.uninstall_extension_if_exists

La funzione uninstall_extension_if_exists rimuove tutte le versioni di un'estensione TLE da un determinato database. Se l'estensione TLE non esiste, la funzione non restituisce alcun avviso (non viene generato alcun messaggio di errore). Se l'estensione specificata è attualmente attiva in un database, non viene eliminata dalla funzione. È necessario chiamare esplicitamente DROP EXTENSION per rimuovere l'estensione TLE prima di utilizzare questa funzione per disinstallarne gli artefatti.

Prototipo di funzione

pgtle.uninstall_extension_if_exists(extname text)

Ruolo

pgtle_admin

Argomenti

  • extname: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

Output

La funzione uninstall_extension_if_exists restituisce true dopo aver disinstallato l'estensione specificata. Se l'estensione specificata non esiste, la funzione restituisce false.

  • true: restituisce true dopo aver disinstallato l'estensione TLE.

  • false: restituisce false quando l'estensione TLE non esiste nel database.

Esempio di utilizzo

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

pgtle.uninstall_update_path

La funzione uninstall_update_path rimuove il percorso di aggiornamento specificato da un'estensione TLE. In tal modo ALTER EXTENSION ... UPDATE TO non può utilizzarlo come percorso di aggiornamento.

Se l'estensione TLE è attualmente utilizzata da una delle versioni di questo percorso di aggiornamento, rimane nel database.

Se il percorso di aggiornamento specificato non esiste, la funzione genera un errore.

Prototipo di funzione

pgtle.uninstall_update_path(extname text, fromvers text, tovers text)

Ruolo

pgtle_admin

Argomenti

  • extname: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • fromvers: la versione di origine dell'estensione TLE utilizzata nel percorso di aggiornamento.

  • tovers: la versione di destinazione dell'estensione TLE utilizzata nel percorso di aggiornamento.

Output

Nessuna.

Esempio di utilizzo

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

pgtle.uninstall_update_path_if_exists

La funzione uninstall_update_path_if_exists è simile a uninstall_update_path in quanto rimuove il percorso di aggiornamento specificato da un'estensione TLE. Tuttavia, se il percorso di aggiornamento non esiste, questa funzione non genera un messaggio di errore e restituisce false.

Prototipo di funzione

pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text)

Ruolo

pgtle_admin

Argomenti

  • extname: il nome dell'estensione TLE. Questo valore viene utilizzato per la chiamata CREATE EXTENSION.

  • fromvers: la versione di origine dell'estensione TLE utilizzata nel percorso di aggiornamento.

  • tovers: la versione di destinazione dell'estensione TLE utilizzata nel percorso di aggiornamento.

Output

  • true: la funzione ha aggiornato correttamente il percorso dell'estensione TLE.

  • false: la funzione non è stata in grado di aggiornare il percorso dell'estensione TLE.

Esempio di utilizzo

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

pgtle.unregister_feature

La funzione unregister_feature fornisce un modo per rimuovere le funzioni registrate per utilizzare la funzionalità pg_tle, ad esempio gli hook. Per ulteriori informazioni sulla registrazione di una funzionalità, consulta pgtle.register_feature.

Prototipo di funzione

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

Ruolo

pgtle_admin

Argomenti

  • proc: il nome di una funzione memorizzata da registrare con una funzionalità pg_tle.

  • feature: il nome della funzionalità pg_tle da registrare con la funzione. Ad esempio, passcheck è una funzionalità che può essere registrata per essere utilizzata dalle estensioni Trusted Language Extensions sviluppate. Per ulteriori informazioni, consulta Hook di verifica della password (passcheck).

Output

Nessuna.

Esempio di utilizzo

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

pgtle.unregister_feature_if_exists

La funzione unregister_feature fornisce un modo per rimuovere le funzioni registrate per utilizzare la funzionalità pg_tle, ad esempio gli hook. Per ulteriori informazioni, consulta Utilizzo di hook PostgreSQL con le estensioni TLE. Restituisce true dopo aver completato l'annullamento della registrazione della funzionalità. Restituisce false se la funzionalità non è stata registrata.

Per informazioni sulla registrazione delle funzionalità pg_tle per le estensioni TLE, consulta pgtle.register_feature.

Prototipo di funzione

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

Ruolo

pgtle_admin

Argomenti

  • proc: il nome della funzione memorizzata che è stata registrata per includere una funzionalità pg_tle.

  • feature: il nome della funzionalità pg_tle registrata con l'estensione Trusted Language Extensions.

Output

Restituisce true o false, come indicato di seguito.

  • true: la funzione ha completato l'annullamento della registrazione della funzionalità dall'estensione.

  • false: la funzione non è stata in grado di annullare la registrazione della funzionalità dall'estensione TLE.

Esempio di utilizzo

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