Terminologia Requisiti per l'utilizzo di Trusted Language Extensions Impostazione di Trusted Language Extensions Panoramica di Trusted Language Extensions Creazione di estensioni TLE Eliminazione delle estensioni TLE da un database Disinstallazione di Trusted Language Extensions Utilizzo di hook PostgreSQL con le estensioni TLE Utilizzo dei tipi di dati personalizzati in Trusted Language Extensions

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 (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 16.1 e successive 16 versioni
Versione 15.2 e successive 15 versioni
Versione 14.5 e successive 14 versioni
Versione 13.12 e successive 13 versioni

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.

Argomenti

Terminology
Requisiti per l'utilizzo di Trusted Language Extensions per PostgreSQL
Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL
Panoramica di Trusted Language Extensions per PostgreSQL
Creazione di estensioni TLE per RDS per PostgreSQL
Eliminazione delle estensioni TLE da un database
Disinstallazione di Trusted Language Extensions per PostgreSQL
Utilizzo di hook PostgreSQL con le estensioni TLE
Utilizzo dei tipi di dati personalizzati in TLE
Riferimento per le funzioni per Trusted Language Extensions per PostgreSQL
Riferimento per gli hook per Trusted Language Extensions per PostgreSQL

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_tle on. 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 (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 Aggiornamento del motore del database PostgreSQL per Amazon RDS.
- 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.
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.
- 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.

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.

Per creare un gruppo di parametri database personalizzato e utilizzarlo con l'istanza database RDS per PostgreSQL

Accedi AWS Management Console e apri la console Amazon RDS all'indirizzo https://console.aws.amazon.com/rds/.
Nel menu di Amazon RDS scegli Parameter groups (Gruppi di parametri).
Scegli Create parameter group (Crea gruppo di parametri).
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.
Scegli 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.
Scegli Databases (Database) dal menu Amazon RDS.
Scegli l'istanza database RDS per PostgreSQL che desideri utilizzare con TLE tra le opzioni elencate, quindi scegli Modify (Modifica).
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.
Per salvare la modifica seleziona Continua (Continua).
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.

Per ulteriori informazioni sull'utilizzo di gruppi di parametri database, consulta Utilizzo di gruppi di parametri DB in un'istanza DB.

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 nella Guida per l'utente di AWS Command Line Interface .

Per creare un gruppo di parametri database personalizzato e utilizzarlo con l'istanza database RDS per PostgreSQL

Usa il create-db-parameter-group AWS CLI comando per creare un gruppo di parametri DB personalizzato basato su per il tuo. Regione AWS

macOSUnixPer, o: Linux


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.

Usa il modify-db-instance 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.

PerLinux, o: macOS 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.

Per ulteriori informazioni, consulta Utilizzo di gruppi di parametri.

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. È possibile utilizzare AWS Management Console o 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.

Per impostare Trusted Language Extensions

Esegui i seguenti passaggi utilizzando un account membro del gruppo rds_superuser (ruolo).

Accedi AWS Management Console e apri la console Amazon RDS all'indirizzo https://console.aws.amazon.com/rds/.
Nel riquadro di navigazione, scegli l' istanza database RDS per PostgreSQL.
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).
Scegli il collegamento per aprire i parametri personalizzati associati l'istanza database RDS per PostgreSQL.
Nel campo di ricerca Parametri, digita shared_pre per trovare il parametro shared_preload_libraries.
Scegli Edit parameters (Modifica parametri) per accedere ai valori delle proprietà.
Aggiungi pg_tle all'elenco nel campo Values (Valori). Utilizza una virgola per separare gli elementi nell'elenco di valori.
Riavvia l'istanza database RDS per PostgreSQL in modo che la modifica al parametro shared_preload_libraries diventi effettiva.
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;

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

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


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

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.

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 nella Guida per l'utente di AWS Command Line Interface .

Per impostare Trusted Language Extensions

Usa il modify-db-parameter-group AWS CLI comando per aggiungere pg_tle al shared_preload_libraries parametro.


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

Usa il reboot-db-instance AWS CLI comando per riavviare l' e inizializzare la libreria. pg_tle


aws rds reboot-db-instance \
    --db-instance-identifier your-instance \
    --region aws-region

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

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.

È possibile vedere i dettagli riportati di seguito.

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.
TLE ha un proprio schema, pgtle. Questo schema contiene funzioni helper (3) per l'installazione e la gestione delle estensioni create.
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 per le funzioni per Trusted Language Extensions per PostgreSQL.

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.

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.

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 (Geometria del taxi) e 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.

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.

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

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.

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;
```
Per testare l'estensione TLE pg_distance, puoi usarla per calcolare la distanza di Manhattan tra quattro punti.
```
labdb=> SELECT manhattan_dist(1, 1, 5, 5);
8
```
Per calcolare la distanza euclidea 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 (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, consultare CREATE FUNCTION 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_update_path. È necessario avere il ruolo pgtle_admin necessario per eseguire questa operazione.

Per aggiornare un'estensione TLE esistente e specificare la versione predefinita

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

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.

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

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

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

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

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

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 per gli hook per Trusted Language Extensions per PostgreSQL.

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, vedi Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL.

Per configurare l'esempio dell'hook di controllo della password

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

Copia il codice da Codice di hook di controllo della password 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 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)

Mentre sei ancora connesso al database, puoi creare l'estensione.
```
CREATE EXTENSION my_password_check_rules;
```

È 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)

Apri un' AWS CLI altra sessione di terminale per lavorare con. È necessario modificare il gruppo di parametri database personalizzato per attivare l'hook di controllo della password. A tale scopo, utilizzate il comando modify-db-parameter-groupCLI come illustrato 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.
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 database.

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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Wrapper di dati esterni supportati

Riferimento per le funzioni per Trusted Language Extensions

Utilizzo di Trusted Language Extensions per PostgreSQL

Argomenti

Terminology

Requisiti per l'utilizzo di Trusted Language Extensions per PostgreSQL

Creazione e applicazione di un gruppo di parametri database personalizzato

Per creare un gruppo di parametri database personalizzato e utilizzarlo con l'istanza database RDS per PostgreSQL

Per creare un gruppo di parametri database personalizzato e utilizzarlo con l'istanza database RDS per PostgreSQL

Impostazione di Trusted Language Extensions nell'istanza database RDS per PostgreSQL

Per impostare Trusted Language Extensions

Per impostare Trusted Language Extensions

Panoramica di Trusted Language Extensions per PostgreSQL

Creazione di estensioni TLE per RDS per PostgreSQL

Esempio: creazione di un'estensione Trusted Language Extensions utilizzando SQL

Nota

Per creare l'estensione TLE di esempio

Modifica dell'estensione TLE

Per aggiornare un'estensione TLE esistente e specificare la versione predefinita

Eliminazione delle estensioni TLE da un database

Per eliminare l'estensione TLE e rimuovere i file di installazione

Disinstallazione di Trusted Language Extensions per PostgreSQL

Per eliminare l'estensione pg_tle e il relativo schema da un database

Utilizzo di hook PostgreSQL con le estensioni TLE

Esempio: creazione di un'estensione che utilizza un hook PostgreSQL

Per configurare l'esempio dell'hook di controllo della password

Codice di hook di controllo della password

Utilizzo dei tipi di dati personalizzati in TLE

Per eliminare l'estensione `pg_tle` e il relativo schema da un database