Connettore PostgreSQL di Amazon Athena - Amazon Athena
PrerequisitiLimitazioniTerminiParametriSupporto dei tipi di datiPartizioni e suddivisioniPrestazioniQuery passthroughRisorse aggiuntive

Connettore PostgreSQL di Amazon Athena

Il connettore PostgreSQL per Amazon Athena consente ad Amazon Athena di accedere ai database PostgreSQL.

Questo connettore può essere registrato con Catalogo dati Glue come catalogo federato. Supporta i controlli di accesso ai dati definiti in Lake Formation a livello di catalogo, database, tabella, colonna, riga e tag. Questo connettore utilizza connessioni Glue per centralizzare le proprietà di configurazione in Glue.

Prerequisiti

Limitazioni

  • Le operazioni di scrittura DDL non sono supportate.

  • In una configurazione multiplex, il bucket di spill e il prefisso sono condivisi tra tutte le istanze del database.

  • Eventuali limiti Lambda pertinenti. Per ulteriori informazioni, consulta la sezione Quote Lambda nella Guida per gli sviluppatori di AWS Lambda.

  • Come PostgreSQL, Athena considera gli spazi finali nei tipi CHAR di PostgreSQL come semanticamente insignificanti ai fini della lunghezza e del confronto. Nota che ciò si applica solo ai tipi CHAR ma non ai tipi VARCHAR. Athena ignora gli spazi finali per il tipo CHAR, ma li considera significativi per il tipo VARCHAR.

  • Quando si utilizza il tipo di dati stringa di caratteri citext senza distinzione tra maiuscole e minuscole, PostgreSQL utilizza un confronto di dati senza distinzione tra maiuscole e minuscole diverso da Athena. Questa differenza crea una discrepanza tra i dati durante le operazioni JOIN di SQL. Per risolvere questo problema, utilizzare la funzionalità query passthrough del connettore PostgreSQL. Per ulteriori informazioni, consultare la sezione relativa alle query passthrough più avanti in questo documento.

Termini

I seguenti termini si riferiscono al connettore PostgreSQL.

  • Istanza del database: qualsiasi istanza del database distribuita on-premise, su Amazon EC2 o su Amazon RDS.

  • Gestore: un gestore Lambda che accede all'istanza del database. Un gestore può gestire i metadati o i record di dati.

  • Gestore dei metadati: un gestore Lambda che recupera i metadati dall'istanza del database.

  • Gestore dei record: un gestore Lambda che recupera i record di dati dall'istanza del database.

  • Gestore composito: un gestore Lambda che recupera sia i metadati sia i record di dati dall'istanza del database.

  • Proprietà o parametro: una proprietà del database utilizzata dai gestori per estrarre le informazioni del database. Queste proprietà vengono configurate come variabili di ambiente Lambda.

  • Stringa di connessione: una stringa di testo utilizzata per stabilire una connessione a un'istanza del database.

  • Catalogo: un catalogo non di AWS Glue registrato in Athena che costituisce un prefisso obbligatorio per la proprietà connection_string.

  • Gestore multiplex: un gestore Lambda in grado di accettare e utilizzare più connessioni al database.

Parametri

Utilizzare i parametri illustrati in questa sezione per configurare il connettore PostgreSQL.

Nota

I connettori di origine dati Athena creati il 3 dicembre 2024 e le versioni successive utilizzano connessioni AWS Glue.

Si consiglia di configurare un connettore PostgreSQL utilizzando un oggetto di connessioni Glue.

Per fare ciò, impostare la variabile di ambiente glue_connection del connettore PostgreSQL Lambda sul nome della connessione Glue da utilizzare.

Utilizzare il seguente comando per ottenere lo schema dell’oggetto di una connessione Glue. Questo schema contiene tutti i parametri che è possibile usare per controllare la connessione.

aws glue describe-connection-type --connection-type POSTGRESQL

Proprietà dell'ambiente

glue_connection: specifica il nome della connessione Glue associata al connettore federato.

Nota

  • Tutti i connettori che utilizzano le connessioni Glue devono utilizzare Gestione dei segreti AWS per memorizzare le credenziali.

  • Il connettore PostgreSQL creato utilizzando le connessioni Glue non supporta l'uso di un gestore multiplexing.

  • Il connettore PostgreSQL creato utilizzando le connessioni Glue supporta solo 2 ConnectionSchemaVersion.

I nomi e le definizioni dei parametri elencati di seguito si riferiscono ai connettori di origine dati Athena creati senza una connessione Glue associata. Utilizza i seguenti parametri solo quando implementi manualmente una versione precedente di un connettore di origine dati Athena o quando la proprietà dell'ambiente glue_connection non è specificata.

Stringa di connessione

Utilizza una stringa di connessione JDBC nel formato seguente per connetterti a un'istanza del database.

postgres://${jdbc_connection_string}

Utilizzo di un gestore multiplex

Puoi utilizzare un gestore multiplex per connetterti a più istanze del database con una singola funzione Lambda. Le richieste vengono indirizzate in base al nome del catalogo. Utilizza le seguenti classi in Lambda.

Gestore Classe
Gestore composito PostGreSqlMuxCompositeHandler
Gestore dei metadati PostGreSqlMuxMetadataHandler
Gestore dei record PostGreSqlMuxRecordHandler
Parametri del gestore multiplex
Parametro Descrizione
$catalog_connection_string Obbligatorio. Una stringa di connessione di un'istanza del database. Appone alla variabile di ambiente un prefisso con il nome del catalogo utilizzato in Athena. Ad esempio, se il catalogo registrato presso Athena è mypostgrescatalog, il nome della variabile di ambiente è mypostgrescatalog_connection_string.
default Obbligatorio. La stringa di connessione predefinita. Questa stringa viene utilizzata quando il catalogo è lambda:${AWS_LAMBDA_FUNCTION_NAME}.

Le seguenti proprietà di esempio si riferiscono a una funzione Lambda PostgreSQL MUX che supporta due istanze del database: postgres1 (il valore predefinito) e postgres2.

Proprietà Valore
default postgres://jdbc:postgresql://postgres1.host:5432/default?${Test/RDS/PostGres1}
postgres_catalog1_connection_string postgres://jdbc:postgresql://postgres1.host:5432/default?${Test/RDS/PostGres1}
postgres_catalog2_connection_string postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample
Specifica delle credenziali

Per fornire un nome utente e una password per il database nella stringa di connessione JDBC, puoi utilizzare le proprietà della stringa di connessione o Gestione dei segreti AWS.

  • Stringa di connessione: puoi specificare un nome utente e una password come proprietà nella stringa di connessione JDBC.

    Importante

    Come best practice di sicurezza, non utilizzare credenziali codificate nelle variabili di ambiente o nelle stringhe di connessione. Per informazioni su come trasferire i segreti codificati in Gestione dei segreti AWS, consulta Trasferimento dei segreti codificati in Gestione dei segreti AWS nella Guida per l'utente di Gestione dei segreti AWS.

  • Gestione dei segreti AWS: per utilizzare la funzione Athena Federated Query con Gestione dei segreti AWS, il VPC collegato alla funzione Lambda deve disporre dell'accesso a Internet o di un endpoint VPC per connettersi a Secrets Manager.

    Puoi inserire il nome di un segreto in Gestione dei segreti AWS nella stringa di connessione JDBC. Il connettore sostituisce il nome del segreto con i valori username e password di Secrets Manager.

    Per le istanze del database Amazon RDS, questo supporto è strettamente integrato. Se utilizzi Amazon RDS, ti consigliamo vivamente di utilizzare Gestione dei segreti AWS e la rotazione delle credenziali. Se il tuo database non utilizza Amazon RDS, archivia le credenziali come JSON nel seguente formato:

    {"username": "${username}", "password": "${password}"}
Esempio di stringa di connessione con nome del segreto

La stringa seguente ha il nome del segreto ${Test/RDS/PostGres1}.

postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&...

Il connettore utilizza il nome del segreto per recuperare i segreti e fornire il nome utente e la password, come nell'esempio seguente.

postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&...

Attualmente, il connettore PostgreSQL riconosce le proprietà JDBC user e password.

Abilitazione SSL

Per supportare SSL nella tua connessione PostgreSQL, aggiungi alla stringa di connessione quanto segue:

&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
Esempio

La stringa di connessione dell'esempio seguente non utilizza SSL.

postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword

Per abilitare SSL, modifica la stringa come segue.

postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory

Utilizzo di un gestore a singola connessione

Puoi utilizzare i seguenti gestori di metadati e record a singola connessione per connetterti a una singola istanza PostgreSQL.

Tipo di gestore Classe
Gestore composito PostGreSqlCompositeHandler
Gestore dei metadati PostGreSqlMetadataHandler
Gestore dei record PostGreSqlRecordHandler
Parametri del gestore a singola connessione
Parametro Descrizione
default Obbligatorio. La stringa di connessione predefinita.

I gestori a singola connessione supportano una sola istanza del database e devono fornire un parametro di stringa di connessione del tipo default. Tutte le altre stringhe di connessione vengono ignorate.

La seguente proprietà di esempio si riferisce a una singola istanza PostgreSQL supportata da una funzione Lambda.

Proprietà Valore
default postgres://jdbc:postgresql://postgres1.host:5432/default?secret=${Test/RDS/PostgreSQL1}

Parametri di spill

L'SDK Lambda può riversare i dati su Amazon S3. Tutte le istanze del database a cui accede la stessa funzione Lambda riversano i dati nella stessa posizione.

Parametro Descrizione
spill_bucket Obbligatorio. Nome del bucket di spill.
spill_prefix Obbligatorio. Prefisso della chiave del bucket di spill.
spill_put_request_headers (Facoltativo) Una mappa codificata in JSON delle intestazioni e dei valori della richiesta per la richiesta putObject di Amazon S3 utilizzata per lo spill (ad esempio, {"x-amz-server-side-encryption" : "AES256"}). Per altre possibili intestazioni, consulta l'argomento relativo a PutObject nella Documentazione di riferimento dell'API di Amazon Simple Storage Service.

Supporto dei tipi di dati

Nella tabella seguente vengono illustrati i tipi di dati corrispondenti per JDBC, PostGreSQL e Arrow.

JDBC PostgreSQL Arrow
Booleano Booleano Bit
Numero intero N/D Tiny
Breve smallint Smallint
Numero intero integer Int
Long bigint Bigint
float float4 Float4
Double float8 Float8
Data date DateDay
Timestamp timestamp DateMilli
Stringa text Varchar
Byte bytes Varbinary
BigDecimal numeric(p,s) Decimale
ARRAY N/D (vedi nota) Elenco
Nota

Il tipo ARRAY è supportato per il connettore PostgreSQL con i seguenti vincoli: le matrici multidimensionali (<data_type>[][] o matrici nidificate) non sono supportate. Le colonne con tipi di dati ARRAY non supportati vengono convertite in una matrice di elementi di stringa (array<varchar>).

Partizioni e suddivisioni

Le partizioni vengono utilizzate per determinare come generare suddivisioni per il connettore. Athena costruisce una colonna sintetica di tipo varchar che rappresenta lo schema di partizionamento della tabella per aiutare il connettore a generare suddivisioni. Il connettore non modifica la definizione effettiva della tabella.

Prestazioni

PostgreSQL supporta le partizioni native. Il connettore PostgreSQL di Athena può recuperare dati da queste partizioni in parallelo. Se desideri interrogare set di dati molto grandi con una distribuzione uniforme delle partizioni, ti consigliamo vivamente il partizionamento nativo.

Il connettore Athena PostgreSQL esegue il pushdown dei predicati per ridurre i dati scansionati dalla query. Le clausole LIMIT, i predicati semplici e le espressioni complesse vengono inviati al connettore per ridurre la quantità di dati scansionati e per ridurre il tempo di esecuzione delle query. Tuttavia, la selezione di un sottoinsieme di colonne comporta un runtime di esecuzione delle query più lungo.

Clausole LIMIT

Una dichiarazione LIMIT N riduce la quantità di dati analizzati dalla query. Con il pushdown LIMIT N, il connettore restituisce solo le righe N ad Athena.

Predicati

Un predicato è un'espressione nella clausola WHERE di una query SQL che valuta a un valore booleano e filtra le righe in base a più condizioni. Il connettore PostgreSQL di Athena può combinare queste espressioni e inviarle direttamente a PostgreSQL per funzionalità avanzate e per ridurre la quantità di dati scansionati.

I seguenti operatori del connettore PostgreSQL di Athena supportano il pushdown dei predicati:

  • Booleano: AND, OR, NOT

  • Uguaglianza: EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, IS_DISTINCT_FROM, NULL_IF, IS_NULL

  • Aritmetica: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE

  • Altro: LIKE_PATTERN, IN

Esempio di pushdown combinato

Per le funzionalità di esecuzione di query avanzate, combina i tipi di pushdown, come nell'esempio seguente:

SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d))
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') 
LIMIT 10;

Query passthrough

Il connettore PostgreSQL supporta le query passthrough. Le query passthrough utilizzano una funzione di tabella per inviare l'intera query alla fonte di dati per l'esecuzione.

Per utilizzare le query passthrough con PostgreSQL, è possibile usare la seguente sintassi:

SELECT * FROM TABLE(
        system.query(
            query => 'query string'
        ))

La seguente query di esempio invia una query a un'origine dati in PostgreSQL. La query seleziona tutte le colonne della tabella customer, limitando i risultati a 10.

SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))

Risorse aggiuntive

Per informazioni sulla versione più recente del driver JDBC, consulta il file pom.xml del connettore PostgreSQL su GitHub.com.

Per ulteriori informazioni su questo connettore, visita il sito corrispondente su GitHub.com.