Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Utilizzo di Trusted Language Extensions per PostgreSQL
Trusted Language Extensions per PostgreSQL è un kit di sviluppo open source per la creazione di estensioni di PostgreSQL. Ti consente di creare estensioni di PostgreSQL ad alte prestazioni ed eseguirle in sicurezza sull'istanza database RDS per PostgreSQL. Con Trusted Language Extensions (TLE) per PostgreSQL, puoi creare estensioni di PostgreSQL che seguono l'approccio documentato per estendere le funzionalità di PostgreSQL. Per ulteriori informazioni, consulta [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (Creazione di pacchetti di oggetti correlati in un'estensione) nella documentazione PostgreSQL.
Uno dei principali vantaggi di TLE è che è possibile utilizzarlo in ambienti che non forniscono accesso al file system alla base dell'istanza PostgreSQL. In precedenza, l'installazione di una nuova estensione richiedeva l'accesso al file system. TLE rimuove questo vincolo. Fornisce un ambiente di sviluppo per creare nuove estensioni per qualsiasi database PostgreSQL, compresi quelli in esecuzione sulle istanze database RDS per PostgreSQL.
TLE è progettato per impedire l'accesso a risorse non sicure per le estensioni create utilizzando TLE. Il suo ambiente di esecuzione limita l'impatto di qualsiasi difetto dell'estensione a una singola connessione al database. TLE inoltre offre agli amministratori di database un controllo dettagliato su chi può installare le estensioni e fornisce un modello di autorizzazioni per eseguirle.
TLE è supportato sulle seguenti versioni di RDS per PostgreSQL:
+ Versione 18.1 e successive 18 versioni
+ Versione 17.1 e versioni successive alla 17
+ Versione 16.1 e versioni successive alla 16
+ Versione 15.2 e versioni successive alla 15
+ Versione 14.5 e versioni successive alla 14
+ Versione 13.12 e versioni successive alla 13
L'ambiente di sviluppo e il runtime di Trusted Language Extensions sono compressi come estensione `pg_tle` di PostgreSQL versione 1.0.1. Supporta la creazione di estensioni in Perl JavaScript, Tcl, PL/pgSQL e SQL. L'estensione `pg_tle` si installa nell'istanza database RDS per PostgreSQL nello stesso modo in cui si installano altre estensioni di PostgreSQL. Dopo l'impostazione di `pg_tle`, gli sviluppatori possono utilizzarlo per creare nuove estensioni di PostgreSQL, note come *estensioni TLE*.
Negli argomenti seguenti sono disponibili informazioni su come impostare Trusted Language Extensions e come iniziare a creare le proprie estensioni TLE.
**Topics**
+ [
# Terminology
](PostgreSQL_trusted_language_extension-terminology.md)
+ [
# Requisiti per l'utilizzo di Trusted Language Extensions per PostgreSQL
](PostgreSQL_trusted_language_extension-requirements.md)
+ [
# Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL
](PostgreSQL_trusted_language_extension-setting-up.md)
+ [
# Panoramica di Trusted Language Extensions per PostgreSQL
](PostgreSQL_trusted_language_extension.overview.md)
+ [
# Creazione di estensioni TLE per RDS per PostgreSQL
](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md)
+ [
# Eliminazione delle estensioni TLE da un database
](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md)
+ [
# Disinstallazione di Trusted Language Extensions per PostgreSQL
](PostgreSQL_trusted_language_extension-uninstalling-pg_tle-devkit.md)
+ [
# Utilizzo di hook PostgreSQL con le estensioni TLE
](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)
+ [
# Utilizzo dei tipi di dati personalizzati in TLE
](PostgreSQL_trusted_language_extension-custom-data-type.md)
+ [
# Riferimento sulle funzioni per Trusted Language Extensions per PostgreSQL
](PostgreSQL_trusted_language_extension-functions-reference.md)
+ [
# Riferimento sugli hook per Trusted Language Extensions per PostgreSQL
](PostgreSQL_trusted_language_extension-hooks-reference.md)
# Terminology
Per comprendere meglio Trusted Language Extensions, consulta il seguente glossario dei termini usati in questo argomento.
**Trusted Language Extensions per PostgreSQL**
*Trusted Language Extensions per PostgreSQL* è il nome ufficiale del kit di sviluppo open source fornito come estensione `pg_tle`. È disponibile per l'uso su qualsiasi sistema PostgreSQL. Per ulteriori informazioni, consulta [aws/pg\$1tle](https://github.com/aws/pg_tle) su GitHub.
**Trusted Language Extensions**
*Trusted Language Extensions* è il nome abbreviato di Trusted Language Extensions per PostgreSQL. Questo nome abbreviato e la sua abbreviazione (TLE) vengono utilizzati anche in questa documentazione.
**linguaggio attendibile**
Un *linguaggio attendibile* è un linguaggio di programmazione o di script con attributi di sicurezza specifici. Ad esempio, i linguaggi attendibili in genere limitano l'accesso al file system e l'uso di proprietà di rete specificate. Il kit di sviluppo TLE è progettato per supportare linguaggi attendibili. PostgreSQL supporta diversi linguaggi utilizzati per creare estensioni attendibili o non attendibili. Per un esempio, vedi [Trusted and Untrusted PL/Perl](https://www.postgresql.org/docs/current/plperl-trusted.html) (PL/Perl attendibile e non attendibile) nella documentazione di PostgreSQL. Quando crei un'estensione utilizzando Trusted Language Extensions, l'estensione utilizza intrinsecamente meccanismi di linguaggio attendibile.
**Estensione TLE**
Un'*estensione TLE* è un'estensione di PostgreSQL creata utilizzando il kit di sviluppo Trusted Language Extensions (TLE).
# Requisiti per l'utilizzo di Trusted Language Extensions per PostgreSQL
I seguenti sono i requisiti per l'impostazione e l'utilizzo del kit di sviluppo TLE.
+ ** Versioni RDS per PostgreSQL** – Trusted Language Extensions supportate su RDS per PostgreSQL versioni 13,12 e versioni 13 successive, 14,5 e versioni 14 successive e 15,2 e solo versioni successive.
+ Per aggiornare l'istanza RDS per PostgreSQL, consulta [Aggiornamenti del motore di database RDS per PostgreSQL](USER_UpgradeDBInstance.PostgreSQL.md).
+ Se non disponi ancora di un'istanza database Amazon RDS che esegue PostgreSQL, puoi eseguirne la creazione. Per ulteriori informazioni, consulta un'istanza database RDS per PostgreSQL, consulta [Creazione e connessione di un'istanza database PostgreSQL](CHAP_GettingStarted.CreatingConnecting.PostgreSQL.md).
+ **Richiede i privilegi `rds_superuser`**: per impostare e configurare l'estensione `pg_tle`, il ruolo utente del database deve disporre delle autorizzazioni del ruolo `rds_superuser`. Per impostazione predefinita, questo ruolo viene concesso all'utente `postgres` che crea l’istanza database RDS per PostgreSQL.
+ **Richiede un gruppo di parametri database personalizzato**: è necessario configurare l'istanza database RDS per PostgreSQL con un gruppo di parametri database personalizzato.
+ Se non si configura l'istanza database RDS per PostgreSQL con un gruppo di parametri database personalizzato, è necessario crearne uno e associarlo all'istanza database RDS per PostgreSQL. Per un breve riepilogo dei passaggi, consulta [Creazione e applicazione di un gruppo di parametri database personalizzato](#PostgreSQL_trusted_language_extension-requirements-create-custom-params).
+ Se è già stata eseguita la configurazione dell'istanza database RDS per PostgreSQL utilizzando un gruppo di parametri database personalizzato, puoi impostare Trusted Language Extensions. Per informazioni dettagliate, vedi [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
## Creazione e applicazione di un gruppo di parametri database personalizzato
Utilizza i seguenti passaggi per creare un gruppo di parametri database personalizzato e configurare l'istanza database RDS per PostgreSQL per utilizzarlo.
### Console
**Per creare un gruppo di parametri DB personalizzato e utilizzarlo con l'istanza DB del**
1. Accedi a Console di gestione AWS e apri la console Amazon RDS all'indirizzo [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. Nel menu di Amazon RDS scegli Parameter groups (Gruppi di parametri).
1. Scegli **Create parameter group** (Crea gruppo di parametri).
1. Nella pagina **Parameter group details** (Dettagli del gruppo di parametri) immetti le seguenti informazioni.
+ Per **Parameter group family** (Famiglia del gruppo di parametri), scegli postgres14.
+ Per **Type** (Tipo), scegli il gruppo di parametri database.
+ Per **Group name** (Nome gruppo), assegna al gruppo di parametri un nome significativo nel contesto delle operazioni.
+ In **Description** (Descrizione), immetti una descrizione utile in modo che gli altri membri del team possano trovarla facilmente.
1. Scegli **Create** (Crea). Il gruppo di parametri database personalizzato viene creato nella Regione AWS. Ora puoi modificare l'istanza database RDS per PostgreSQL che sarà possibile utilizzare seguendo i prossimi passaggi.
1. Scegli **Databases** (Database) dal menu Amazon RDS.
1. Scegli l'istanza database RDS per PostgreSQL che desideri utilizzare con TLE tra le opzioni elencate, quindi scegli **Modify** (Modifica).
1. Nella pagina Modify DB instance settings (Modifica le impostazioni dell'istanza database), trova **Database options** (Opzioni del database) nella sezione Additional configuration (Configurazione aggiuntiva) e scegli il gruppo di parametri database personalizzato con il selettore.
1. Per salvare la modifica seleziona **Continua** (Continua).
1. Scegli **Apply immediately** (Applica immediatamente) in modo da poter continuare a impostare l'istanza database RDS per PostgreSQL per utilizzare TLE.
Per continuare a impostare il sistema per Trusted Language Extensions, consulta [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Per ulteriori informazioni sull'utilizzo di gruppi di parametri database, consulta [Gruppi di parametri database per istanze database Amazon RDS](USER_WorkingWithDBInstanceParamGroups.md).
### AWS CLI
Puoi evitare di specificare l'argomento `--region` quando usi i comandi dell'interfaccia della linea di comando configurando AWS CLI con la Regione AWS predefinita. Per ulteriori informazioni, consulta [Nozioni di base sulla configurazione](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) nella *Guida per l'utente di AWS Command Line Interface *.
**Per creare un gruppo di parametri DB personalizzato e utilizzarlo con l'istanza DB del**
1. Regione AWS
Per Linux, macOS o Unix:
```
aws rds create-db-parameter-group \
--region aws-region \
--db-parameter-group-name custom-params-for-pg-tle \
--db-parameter-group-family postgres14 \
--description "My custom DB parameter group for Trusted Language Extensions"
```
Per Windows:
```
aws rds create-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name custom-params-for-pg-tle ^
--db-parameter-group-family postgres14 ^
--description "My custom DB parameter group for Trusted Language Extensions"
```
Il gruppo di parametri database personalizzato è disponibile nella Regione AWS, in modo che puoi modificare l'istanza database RDS per PostgreSQL per utilizzarlo.
1. Usa il [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) AWS CLI comando per applicare il gruppo di parametri DB personalizzato DB. la tua istanza DB RDS per PostgreSQL. Questo comando riavvia immediatamente l'istanza attiva.
Per Linux, macOS o Unix:
```
aws rds modify-db-instance \
--region aws-region \
--db-instance-identifier your-instance-name \
--db-parameter-group-name custom-params-for-pg-tle \
--apply-immediately
```
Per Windows:
```
aws rds modify-db-instance ^
--region aws-region ^
--db-instance-identifier your-instance-name ^
--db-parameter-group-name custom-params-for-pg-tle ^
--apply-immediately
```
Per continuare a impostare il sistema per Trusted Language Extensions, consulta [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
Per ulteriori informazioni, consulta [Gruppi di parametri per Amazon RDS](USER_WorkingWithParamGroups.md).
# Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL
I passaggi seguenti si basano sull'ipotesi che l'istanza database RDS per PostgreSQL sia associata a un gruppo di parametri personalizzato del database. Puoi usare la Console di gestione AWS o la AWS CLI per questi passaggi.
Quando imposti Trusted Language Extensions nell'istanza database RDS per PostgreSQL, lo installi in un database specifico che deve essere utilizzato dagli utenti del database che dispongono delle relative autorizzazioni.
## Console
**Per impostare Trusted Language Extensions**
Esegui i seguenti passaggi utilizzando un account membro del gruppo `rds_superuser` (ruolo).
1. Accedi alla Console di gestione AWS e apri la console Amazon RDS all'indirizzo [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. Nel riquadro di navigazione, scegli l' istanza database RDS per PostgreSQL.
1. Apri la scheda **Configurazione** per l' l'istanza database RDS per PostgreSQL. Tra i dettagli dell'istanza, individua il collegamento **Parameter group** (Gruppo di parametri).
1. Scegli il collegamento per aprire i parametri personalizzati associati l'istanza database RDS per PostgreSQL.
1. Nel campo di ricerca **Parametri**, digita `shared_pre` per trovare il parametro `shared_preload_libraries`.
1. Scegli **Edit parameters** (Modifica parametri) per accedere ai valori delle proprietà.
1. Aggiungi `pg_tle` all'elenco nel campo **Values** (Valori). Utilizza una virgola per separare gli elementi nell'elenco di valori.
![\[Immagine del parametro shared_preload_libraries con pg_tle aggiunto.\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/UserGuide/images/apg_rpg_shared_preload_pg_tle.png)
1. Riavvia l'istanza database RDS per PostgreSQL in modo che la modifica al parametro `shared_preload_libraries` diventi effettiva.
1. Quando l'istanza è disponibile, verifica che `pg_tle` sia stato inizializzato. Utilizza `psql` per connetterti all'istanza database RDS per PostgreSQL, quindi esegui il comando seguente.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
1. Con `pg_tle` inizializzato, puoi ora creare l'estensione.
```
CREATE EXTENSION pg_tle;
```
Per verificare che l'estensione sia installata, puoi usare il seguente metacomando `psql`.
```
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
```
1. Assegna il ruolo `pgtle_admin` al nome utente principale che hai creato per l'istanza database RDS per PostgreSQL al momento dell'impostazione. Se hai accettato l'impostazione predefinita, il valore è `postgres`.
```
labdb=> GRANT pgtle_admin TO postgres;
GRANT ROLE
```
Per verificare se la concessione è avvenuta, utilizza il metacomando `psql` come illustrato nell'esempio seguente. Nell'output vengono visualizzati solo i ruoli `pgtle_admin` e `postgres`. Per ulteriori informazioni, consulta [Comprendere il ruolo rds\$1superuser](Appendix.PostgreSQL.CommonDBATasks.Roles.rds_superuser.md).
```
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 |...
```
1. Chiudi la sessione `psql` usando il metacomando `\q`.
```
\q
```
Per iniziare a creare le estensioni TLE, consulta [Esempio: creazione di un'estensione Trusted Language Extensions utilizzando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
## AWS CLI
Puoi evitare di specificare l'argomento `--region` quando usi i comandi CLI configurando AWS CLI con la Regione AWS predefinita. Per ulteriori informazioni, consulta [Nozioni di base sulla configurazione](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) nella *Guida per l'utente di AWS Command Line Interface*.
**Per impostare Trusted Language Extensions**
1. Usa il comando AWS CLI [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) per aggiungere `pg_tle` al parametro `shared_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" \
--region aws-region
```
1. Usa il comando AWS CLI [reboot-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/reboot-db-instance) per riavviare l'istanza database RDS per PostgreSQL e inizializzare la libreria `pg_tle`.
```
aws rds reboot-db-instance \
--db-instance-identifier your-instance \
--region aws-region
```
1. Quando l'istanza è disponibile, verifica che `pg_tle` sia stato inizializzato. Utilizza `psql` per connetterti all'istanza database RDS per PostgreSQL, quindi esegui il comando seguente.
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
Con `pg_tle` inizializzato, puoi ora creare l'estensione.
```
CREATE EXTENSION pg_tle;
```
1. Assegna il ruolo `pgtle_admin` al nome utente principale che hai creato per l'istanza database RDS per PostgreSQL al momento dell'impostazione. Se hai accettato l'impostazione predefinita, il valore è `postgres`.
```
GRANT pgtle_admin TO postgres;
GRANT ROLE
```
1. Chiudi la sessione `psql` come indicato di seguito.
```
labdb=> \q
```
Per iniziare a creare le estensioni TLE, consulta [Esempio: creazione di un'estensione Trusted Language Extensions utilizzando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example).
# Panoramica di Trusted Language Extensions per PostgreSQL
Trusted Language Extensions per PostgreSQL è un'estensione di PostgreSQL che si installa nell'istanza database RDS per PostgreSQL nello stesso modo in cui si impostano le altre estensioni di PostgreSQL. Nell'immagine seguente di un database di esempio nello strumento client pgAdmin, è possibile vedere alcuni dei componenti che compongono l'estensione `pg_tle`.
![\[Immagine che mostra alcuni componenti che costituiscono il kit di sviluppo TLE.\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/UserGuide/images/apg-pg_tle-installed-view-in-pgAdmin.png)
È possibile vedere i dettagli riportati di seguito.
1. Il kit di sviluppo Trusted Language Extensions (TLE) per PostgreSQL è fornito nel pacchetto come estensione `pg_tle`. Pertanto, `pg_tle` viene aggiunto alle estensioni disponibili per il database in cui è installato.
1. TLE ha un proprio schema, `pgtle`. Questo schema contiene funzioni helper (3) per l'installazione e la gestione delle estensioni create.
1. TLE offre oltre una dozzina di funzioni helper per l'installazione, la registrazione e la gestione delle estensioni. Per ulteriori informazioni su queste funzioni, consulta [Riferimento sulle funzioni per Trusted Language Extensions per PostgreSQL](PostgreSQL_trusted_language_extension-functions-reference.md).
Altri componenti dell'estensione `pg_tle` sono:
+ **Il ruolo `pgtle_admin`**: il ruolo `pgtle_admin` viene creato quando viene installata l'estensione `pg_tle`. Questo ruolo include privilegi e deve essere trattato come tale. Ti consigliamo vivamente di seguire il principio del *privilegio minimo* quando concedi il ruolo `pgtle_admin` agli utenti del database. In altre parole, concedi il ruolo `pgtle_admin` solo agli utenti del database autorizzati a creare, installare e gestire nuove estensioni TLE, ad esempio `postgres`.
+ **La tabella `pgtle.feature_info`**: la tabella `pgtle.feature_info` è una tabella protetta che contiene informazioni sulle estensioni TLE, sugli hook e sulle stored procedure e funzioni personalizzate che utilizzano. Se disponi di privilegi `pgtle_admin`, usa le seguenti funzioni Trusted Language Extensions per aggiungere e aggiornare le informazioni nella tabella.
+ [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.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)
# Creazione di estensioni TLE per RDS per PostgreSQL
È possibile installare qualsiasi estensione creata con TLE in qualsiasi istanza database RDS per PostgreSQL in cui è installata l'estensione `pg_tle`. L'estensione `pg_tle` si riferisce al database PostgreSQL in cui è installata. Le estensioni create utilizzando TLE si riferiscono allo stesso database.
Usa le varie funzioni `pgtle` per installare il codice che costituisce la tua estensione TLE. Le seguenti funzioni di Trusted Language Extensions richiedono tutte il ruolo `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(name)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension(name, version)](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)
## Esempio: creazione di un'estensione Trusted Language Extensions utilizzando SQL
L'esempio seguente mostra come creare un'estensione TLE denominata `pg_distance` che contiene alcune funzioni SQL per il calcolo delle distanze utilizzando formule diverse. Nell'elenco, puoi trovare la funzione per il calcolo della distanza di Manhattan e la funzione per il calcolo della distanza euclidea. Per ulteriori informazioni sulla differenza tra queste formule, consulta [Taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry) (Geometria del taxi) e [Euclidean geometry](https://en.wikipedia.org/wiki/Euclidean_geometry) (Geometria euclidea) in Wikipedia.
È possibile utilizzare questo esempio nell'istanza database RDS per PostgreSQL se l'estensione `pg_tle` è impostata come descritto in dettaglio in [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**Nota**
È necessario disporre dei privilegi del ruolo `pgtle_admin` per seguire questa procedura.
**Per creare l'estensione TLE di esempio**
I passaggi seguenti utilizzano un database di esempio denominato `labdb`. Questo database è di proprietà dell'utente `postgres` principale. Il ruolo `postgres` dispone anche delle autorizzazioni del ruolo `pgtle_admin`.
1. Utilizza `psql` per connetterti l’istanza database RDS per PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Crea un'estensione TLE denominata `pg_distance` copiando il seguente codice e incollandolo nella console della sessione `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_$
);
```
Viene visualizzato l'output riportato di seguito.
```
install_extension
---------------
t
(1 row)
```
Gli artefatti che costituiscono l'estensione `pg_distance` sono ora installati nel database. Questi artefatti includono il file di controllo e il codice dell'estensione, che devono essere presenti in modo che l'estensione possa essere creata utilizzando il comando `CREATE EXTENSION`. In altre parole, è comunque necessario creare l'estensione per rendere le funzioni disponibili agli utenti del database.
1. Per creare l'estensione, usa il comando `CREATE EXTENSION` come per qualsiasi altra estensione. Come per altre estensioni, l'utente del database deve disporre delle autorizzazioni `CREATE` nel database.
```
CREATE EXTENSION pg_distance;
```
1. Per testare l'estensione TLE `pg_distance`, puoi usarla per calcolare la [distanza di Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry) tra quattro punti.
```
labdb=> SELECT manhattan_dist(1, 1, 5, 5);
8
```
Per calcolare la [distanza euclidea](https://en.wikipedia.org/wiki/Euclidean_geometry) tra lo stesso set di punti, puoi usare quanto segue.
```
labdb=> SELECT euclidean_dist(1, 1, 5, 5);
5.656854249492381
```
L'estensione `pg_distance` carica le funzioni nel database e le rende disponibili a tutti gli utenti con le autorizzazioni per il database.
## Modifica dell'estensione TLE
Per migliorare le prestazioni delle query per le funzioni contenute nell'estensione TLE, aggiungi i seguenti due attributi PostgreSQL alle specifiche.
+ `IMMUTABLE`: l'attributo `IMMUTABLE` garantisce che l'ottimizzatore di query possa utilizzare le ottimizzazioni per migliorare i tempi di risposta delle query. Per ulteriori informazioni, consulta [Function Volatility Categories](https://www.postgresql.org/docs/current/xfunc-volatility.html) (Categorie della volatilità delle funzioni) nella documentazione di PostgreSQL.
+ `PARALLEL SAFE`: l'attributo `PARALLEL SAFE` è un altro attributo che consente a PostgreSQL di eseguire la funzione in modalità parallela. Per ulteriori informazioni, consulta [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html) nella documentazione di PostgreSQL.
Nell'esempio seguente, puoi vedere come viene utilizzata la funzione `pgtle.install_update_path` per aggiungere questi attributi a ogni funzione per creare la versione `0.2` dell'estensione TLE `pg_distance`. Per ulteriori informazioni su questa funzione, consulta [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path). È necessario avere il ruolo `pgtle_admin` necessario per eseguire questa operazione.
**Per aggiornare un'estensione TLE esistente e specificare la versione predefinita**
1. Esegui la connessione all'istanza database RDS per PostgreSQL utilizzando `psql` o un altro strumento client, ad esempio pgAdmin.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Modifica l'estensione TLE esistente copiando il seguente codice e incollandolo nella console della sessione `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_$
);
```
Viene visualizzata una risposta simile alla seguente.
```
install_update_path
---------------------
t
(1 row)
```
È possibile impostare questa versione dell'estensione come versione predefinita, in modo che gli utenti del database non debbano specificare una versione quando creano o aggiornano l'estensione nel database.
1. Per specificare che la versione modificata (versione 0.2) dell'estensione TLE è la versione predefinita, usa la funzione `pgtle.set_default_version` come mostrato nell'esempio seguente.
```
SELECT pgtle.set_default_version('pg_distance', '0.2');
```
Per ulteriori informazioni su questa funzione, consulta [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version).
1. Una volta inserito il codice, puoi aggiornare l'estensione TLE installata nel modo consueto, usando il comando `ALTER EXTENSION ... UPDATE`, come mostrato di seguito:
```
ALTER EXTENSION pg_distance UPDATE;
```
# Eliminazione delle estensioni TLE da un database
Puoi eliminare le estensioni TLE usando il comando `DROP EXTENSION` nello stesso modo che impieghi per le altre estensioni di PostgreSQL. L'eliminazione dell'estensione non rimuove i file di installazione che costituiscono l'estensione, il che consente agli utenti di ricrearla. Per rimuovere l'estensione e i relativi file di installazione, esegui la seguente procedura in due passaggi.
**Per eliminare l'estensione TLE e rimuovere i file di installazione**
1. Utilizza `psql` o un altro strumento cliente per connetterti all'istanza database RDS per PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Elimina l'estensione come faresti per qualsiasi estensione di PostgreSQL.
```
DROP EXTENSION your-TLE-extension
```
Ad esempio, se crei l'estensione `pg_distance` come descritto in [Esempio: creazione di un'estensione Trusted Language Extensions utilizzando SQL](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example), puoi eliminarla come segue.
```
DROP EXTENSION pg_distance;
```
Viene visualizzato l'output che conferma che l'estensione è stata eliminata, come segue.
```
DROP EXTENSION
```
A questo punto, l'estensione non è più attiva nel database. Tuttavia, i file di installazione e il file di controllo sono ancora disponibili nel database, quindi gli utenti del database possono creare nuovamente l'estensione, se lo desiderano.
+ Se vuoi lasciare intatti i file delle estensioni in modo che gli utenti del database possano creare l'estensione TLE, puoi fermarti qui.
+ Se desideri rimuovere tutti i file che costituiscono l'estensione, continua con il passaggio successivo.
1. Per rimuovere tutti i file di installazione per l'estensione, usa la funzione `pgtle.uninstall_extension`. Questa funzione rimuove tutto il codice e i file di controllo dell'estensione.
```
SELECT pgtle.uninstall_extension('your-tle-extension-name');
```
Ad esempio, per rimuovere tutti i file di installazione `pg_distance`, utilizza il comando seguente.
```
SELECT pgtle.uninstall_extension('pg_distance');
uninstall_extension
---------------------
t
(1 row)
```
# Disinstallazione di Trusted Language Extensions per PostgreSQL
Se non desideri più creare le estensioni TLE utilizzando TLE, puoi eliminare l'estensione `pg_tle` e rimuovere tutti gli artefatti. Questa azione include l'eliminazione di qualsiasi estensione TLE nel database e l'eliminazione dello schema `pgtle`.
**Per eliminare l'estensione `pg_tle` e il relativo schema da un database**
1. Utilizza `psql` o un altro strumento cliente per connetterti all'istanza database RDS per PostgreSQL.
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. Elimina l'estensione `pg_tle` dal database. Se il database ha le estensioni TLE ancora in esecuzione nel database, devi eliminare anche quelle estensioni. A questo scopo, puoi utilizzare la parola chiave `CASCADE`, come illustrato di seguito.
```
DROP EXTENSION pg_tle CASCADE;
```
Se l'estensione `pg_tle` non è ancora attiva nel database, non è necessario utilizzare la parola chiave `CASCADE`.
1. Elimina lo schema `pgtle`. Questa azione rimuove tutte le funzioni di gestione dal database.
```
DROP SCHEMA pgtle CASCADE;
```
Il comando restituisce quanto segue al termine del processo.
```
DROP SCHEMA
```
L'estensione `pg_tle`, il relativo schema, le funzioni e tutti gli artefatti vengono rimossi. Per creare nuove estensioni utilizzando TLE, ripeti il processo di impostazione. Per ulteriori informazioni, consulta [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
# Utilizzo di hook PostgreSQL con le estensioni TLE
Un *hook* è un meccanismo di callback disponibile in PostgreSQL che consente agli sviluppatori di chiamare funzioni personalizzate o altre routine durante le normali operazioni del database. Il kit di sviluppo TLE supporta gli hook PostgreSQL per poter integrare le funzioni personalizzate con il comportamento di PostgreSQL in fase di esecuzione. Ad esempio, puoi utilizzare un hook per associare il processo di autenticazione al codice personalizzato o per modificare il processo di pianificazione ed esecuzione delle query in base alle tue esigenze specifiche.
Le estensioni TLE possono utilizzare gli hook. Se l'ambito dell'hook è globale, si applica a tutti i database. Pertanto, se l'estensione TLE utilizza un hook globale, è necessario crearla in tutti i database a cui gli utenti possono accedere.
Quando usi `pg_tle` per creare le estensioni Trusted Language Extensions, puoi utilizzare gli hook disponibili da un'API SQL per creare le funzioni della tua estensione. È necessario registrare gli hook con `pg_tle`. Per alcuni hook, potrebbe essere necessario impostare anche vari parametri di configurazione. Ad esempio, l'hook di controllo `passcode` può essere impostato su attivo, disattivo oppure obbligatorio. Per ulteriori informazioni sui requisiti specifici per gli hook `pg_tle` disponibili, consulta [Riferimento sugli hook per Trusted Language Extensions per PostgreSQL](PostgreSQL_trusted_language_extension-hooks-reference.md).
## Esempio: creazione di un'estensione che utilizza un hook PostgreSQL
L'esempio discusso in questa sezione utilizza un hook PostgreSQL per controllare la password fornita durante specifiche operazioni SQL e impedisce agli utenti del database di impostare le proprie password su una qualsiasi di quelle contenute nella tabella `password_check.bad_passwords`. La tabella contiene le prime dieci opzioni di password più utilizzate, ma facilmente violabili.
Per configurare questo esempio nell'istanza database RDS per PostgreSQL, devi aver già installato Trusted Language Extensions. Per informazioni dettagliate, consultare [Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL](PostgreSQL_trusted_language_extension-setting-up.md).
**Per configurare l'esempio dell'hook di controllo della password**
1. Utilizza `psql` per connetterti l'istanza database RDS per PostgreSQL.
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. Copia il codice da [Codice di hook di controllo della password](#PostgreSQL_trusted_language_extension-example-hook_code_listing) e incollalo nel database.
```
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 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 l'estensione è stata caricata nel database, viene visualizzato un output come il seguente.
```
install_extension
-------------------
t
(1 row)
```
1. Mentre sei ancora connesso al database, puoi creare l'estensione.
```
CREATE EXTENSION my_password_check_rules;
```
1. È possibile confermare che l'estensione è stata creata nel database utilizzando il seguente metacomando `psql`.
```
\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)
```
1. Apri un'altra sessione di terminale per utilizzare AWS CLI. È necessario modificare il gruppo di parametri database personalizzato per attivare l'hook di controllo della password. Per fare ciò, utilizza il comando dell'interfaccia della linea di comando [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html), come indicato nell'esempio seguente.
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
Quando il parametro viene attivato correttamente, viene visualizzato un output come il seguente.
```
(
"DBParameterGroupName": "docs-lab-parameters-for-tle"
}
```
Per rendere effettive le modifiche all'impostazione del gruppo di parametri possono essere necessari alcuni minuti. Tuttavia, questo parametro è dinamico, quindi non è necessario riavviare l'istanza database RDS per PostgreSQL perché l'impostazione diventi effettiva.
1. Apri la sessione `psql` ed esegui una query sul database per verificare che l'hook di controllo della password sia stato attivato.
```
labdb=> SHOW pgtle.enable_password_check;
pgtle.enable_password_check
-----------------------------
on
(1 row)
```
L'hook di controllo della password è ora attivo. Puoi testarlo creando un nuovo ruolo e utilizzando una delle password errate, come illustrato nell'esempio seguente.
```
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)"
```
L'output è stato formattato per ragioni di leggibilità.
L'esempio seguente mostra che il comportamento `\password` del metacomando interattivo `pgsql` è influenzato anche dall'hook di controllo della password.
```
postgres=> SET password_encryption TO 'md5';
SET
postgres=> \password
Enter 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)"
```
Puoi eliminare questa estensione TLE e disinstallare i file di origine, se lo desideri. Per ulteriori informazioni, consulta [Eliminazione delle estensioni TLE da un databaseEliminazione delle estensioni TLE da un database](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md).
### Codice di hook di controllo della password
Il codice di esempio mostrato qui definisce le specifiche per l'estensione TLE `my_password_check_rules`. Quando copi questo codice e lo incolli nel database, il codice dell'estensione `my_password_check_rules` viene caricato nel database e l'hook `password_check` viene registrato per essere utilizzato dall'estensione.
```
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 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_$
);
```
# Utilizzo dei tipi di dati personalizzati in TLE
PostgreSQL supporta comandi per registrare nuovi tipi di base (noti anche come tipi scalari) per gestire in modo efficiente strutture di dati complesse nel database. Un tipo di base consente di personalizzare il modo in cui i dati vengono archiviati internamente e come convertirli da e verso una rappresentazione testuale esterna. Questi tipi di dati personalizzati sono utili per estendere il supporto di PostgreSQL ai domini funzionali in cui un tipo integrato come numero o testo non può fornire una semantica di ricerca sufficiente.
RDS per PostgreSQL consente di creare tipi di dati personalizzati in Trusted Language Extensions e di definire funzioni che supportano le operazioni SQL e di indicizzazione per questi nuovi tipi di dati. I tipi di dati personalizzati sono disponibili per le seguenti versioni:
+ RDS per PostgreSQL 15.4 e versioni successive alla 15
+ RDS per PostgreSQL 14.9 e versioni successive alla 14
+ RDS per PostgreSQL 13.12 e versioni successive alla 13
Per ulteriori informazioni, consulta la pagina [Trusted Language Base types](https://github.com/aws/pg_tle/blob/main/docs/09_datatypes.md).
# 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.
**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(name)
](#pgtle.uninstall_extension-name)
+ [
## pgtle.uninstall\$1extension(name, version)
](#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
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\$1extension\$1versions
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](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (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\$1update\$1paths
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 esempio`0.1--0.2`.
### Esempio di utilizzo
```
SELECT * FROM pgtle.extension_update_paths('your-TLE');
```
## pgtle.install\$1extension
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](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11) (File di estensione) in [Packaging Related Objects into an Extension](https://www.postgresql.org/docs/current/extend-extensions.html) (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\$1update\$1path
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\$1feature
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\$1feature\$1if\$1not\$1exists
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](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md).
### 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)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook).
### 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\$1default\$1version
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\$1extension(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\$1extension(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\$1extension(name)](#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\$1extension\$1if\$1exists
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\$1update\$1path
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\$1update\$1path\$1if\$1exists
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\$1feature
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\$1feature](#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)](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook).
### Output
Nessuna.
### Esempio di utilizzo
```
SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');
```
## pgtle.unregister\$1feature\$1if\$1exists
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](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md). 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\$1feature](#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');
```
# Riferimento sugli hook per Trusted Language Extensions per PostgreSQL
Trusted Language Extensions per PostgreSQL supporta gli hook PostgreSQL. Un *hook* è un meccanismo di callback interno che gli sviluppatori possono usare per estendere le funzionalità di base di PostgreSQL. Utilizzando gli hook, gli sviluppatori possono implementare le proprie funzioni o procedure da utilizzare durante varie operazioni del database, modificando così il comportamento di PostgreSQL in qualche modo. Ad esempio, puoi usare un hook `passcheck` per personalizzare il modo in cui PostgreSQL gestisce le password fornite durante la creazione o la modifica delle password per gli utenti (ruoli).
Consultare la seguente documentazione per informazioni sull’hook passcheck disponibile per le estensioni TLE. Per ulteriori informazioni sugli hook disponibili, incluso l’hook di autenticazione del client, consulta [Trusted Language Extensions hooks](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md).
## Hook di verifica della password (passcheck)
L'hook `passcheck` viene utilizzato per personalizzare il comportamento di PostgreSQL durante il processo di verifica della password per i seguenti comandi SQL e il metacomando `psql`.
+ `CREATE ROLE username ...PASSWORD`: per ulteriori informazioni, consulta [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) nella documentazione di PostgreSQL.
+ `ALTER ROLE username...PASSWORD`: per ulteriori informazioni, consulta [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html) nella documentazione di PostgreSQL.
+ `\password username`: questo metacomando `psql` interattivo modifica in modo sicuro la password per l'utente specificato eseguendo l'hashing della password prima di utilizzare in modo trasparente la sintassi `ALTER ROLE ... PASSWORD`. Il metacomando è un wrapper sicuro per il comando `ALTER ROLE ... PASSWORD`, quindi l'hook si applica al comportamento del metacomando `psql`.
Per vedere un esempio, consulta [Codice di hook di controllo della password](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing).
**Contents**
+ [
### Prototipo di funzione
](#passcheck_hook-prototype)
+ [
### Arguments (Argomenti)
](#passcheck_hook-arguments)
+ [
### Configurazione
](#passcheck_hook-configuration)
+ [
### Note per l'utilizzo
](#passcheck_hook-usage)
### Prototipo di funzione
```
passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
```
### Arguments (Argomenti)
La funzione dell'hook `passcheck` accetta i seguenti argomenti:
+ `username`: il nome (come testo) del ruolo (nome utente) che imposta una password.
+ `password`: la password in chiaro o con hash. La password immessa deve corrispondere al tipo specificato in `password_type`.
+ `password_type`: specifica il formato `pgtle.password_type` della password, che può essere costituito da una delle seguenti opzioni.
+ `PASSWORD_TYPE_PLAINTEXT`: una password in testo semplice.
+ `PASSWORD_TYPE_MD5`— Una password che è stata sottoposta a hash utilizzando l' MD5 algoritmo (message digest 5).
+ `PASSWORD_TYPE_SCRAM_SHA_256`: una password che è stata sottoposta a hash utilizzando l'algoritmo SCRAM-SHA-256.
+ `valid_until`: specifica l'ora in cui la password diventa non valida. Questo argomento è facoltativo. Se utilizzi questo argomento, specifica l'ora come valore `timestamptz`.
+ `valid_null`: se questo booleano è impostato su `true`, l'opzione `valid_until` è impostata su `NULL`.
### Configurazione
La funzione `pgtle.enable_password_check` controlla se l'hook passcheck è attivo. L'hook passcheck ha tre possibili impostazioni.
+ `off`: disattiva l'hook `passcheck` di verifica della password. Si tratta del valore di default.
+ `on`: attiva l'hook `passcode` di verifica della password in modo che le password vengano confrontate con la tabella.
+ `require`: richiede la definizione di un hook di verifica della password.
### Note per l'utilizzo
Per attivare o disattivare l'hook `passcheck`, è necessario modificare il gruppo di parametri database personalizzato per l'istanza database RDS per PostgreSQL.
Per Linux, macOS o Unix:
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
Per Windows:
```
aws rds modify-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name your-custom-parameter-group ^
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```