Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Konnektoren für Aurora DSQL
Aurora DSQL bietet spezielle Konnektoren, die bestehende Datenbanktreiber erweitern, um eine nahtlose IAM-Authentifizierung und Integration mit AWS Diensten zu ermöglichen. Diese Konnektoren sind für Kompatibilität mit gängigen Programmiersprachen und Frameworks konzipiert und gewährleisten auch die Kompatibilität mit vorhandenen PostgreSQL-Workflows.
Zusätzliche Konnektoren sind für future Versionen geplant. Aktuelle Informationen zur Konnektorenverfügbarkeit finden Sie im [Aurora DSQL-Beispielrepository](https://github.com/aws-samples/aurora-dsql-samples).
# Verbindung zu Aurora DSQL-Clustern mit einem JDBC-Konnektor herstellen
Der [Aurora DSQL Connector für JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) ist als Authentifizierungs-Plugin konzipiert, das die Funktionalität des PostgreSQL-JDBC-Treibers erweitert, sodass Anwendungen mithilfe von IAM-Anmeldeinformationen bei Aurora DSQL authentifizieren können. Der Konnektor stellt keine direkte Verbindung zur Datenbank her, bietet jedoch eine nahtlose IAM-Authentifizierung zusätzlich zu dem in PostgreSQL zugrunde liegenden JDBC-Treiber.
Der Aurora DSQL Connector für JDBC wurde für die Zusammenarbeit mit dem [PostgreSQL JDBC-Treiber entwickelt und bietet eine nahtlose Integration mit den IAM-Authentifizierungsanforderungen](https://github.com/pgjdbc/pgjdbc) von Aurora DSQL.
In Verbindung mit dem PostgreSQL JDBC-Treiber ermöglicht der Aurora DSQL Connector for JDBC die IAM-basierte Authentifizierung für Aurora DSQL. Er ermöglicht eine tiefe Integration mit Authentifizierungsdiensten wie (IAM). AWS [AWS Identity and Access Management](https://aws.amazon.com/iam/)
## Über den Konnektor
Aurora DSQL ist ein verteilter SQL-Datenbankservice, der hohe Verfügbarkeit und Skalierbarkeit für PostgreSQL-kompatible Anwendungen bietet. Aurora DSQL erfordert eine IAM-basierte Authentifizierung mit zeitlich begrenzten Tokens, die vorhandene JDBC-Treiber nicht nativ unterstützen.
Die Hauptidee hinter dem Aurora DSQL Connector for JDBC besteht darin, dem PostgreSQL-JDBC-Treiber eine Authentifizierungsebene hinzuzufügen, die die IAM-Token-Generierung übernimmt, sodass Benutzer eine Verbindung zu Aurora DSQL herstellen können, ohne ihre bestehenden JDBC-Workflows zu ändern.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung: Authentifizierungstoken** werden mithilfe von Anmeldeinformationen generiert und haben eine konfigurierbare Lebensdauer AWS
Der Aurora DSQL Connector für JDBC wurde entwickelt, um diese Anforderungen zu verstehen und beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken zu generieren.
### Vorteile des Aurora DSQL Connectors für JDBC
Aurora DSQL bietet zwar eine PostgreSQL-kompatible Schnittstelle, jedoch unterstützen vorhandene PostgreSQL-Treiber derzeit nicht die IAM-Authentifizierungsanforderungen von Aurora DSQL. Der Aurora DSQL Connector für JDBC ermöglicht es Kunden, ihre bestehenden PostgreSQL-Workflows weiterhin zu verwenden und gleichzeitig die IAM-Authentifizierung zu aktivieren durch:
+ **Automatische Token-Generierung: IAM-Token** werden automatisch mithilfe von Anmeldeinformationen generiert AWS
+ **Nahtlose Integration**: kompatibel mit vorhandenen JDBC-Verbindungsmustern
+ **AWS Support für Anmeldeinformationen**: Unterstützt verschiedene Anbieter von AWS Anmeldeinformationen (Standard, profilbasiert usw.)
### Verwenden des Aurora DSQL Connectors für JDBC mit Verbindungspooling
Der Aurora DSQL Connector für JDBC funktioniert mit Connection Pooling-Bibliotheken wie HikariCP. Der Konnektor übernimmt die Generierung von IAM-Tokens während des Verbindungsaufbaus, sodass die Verbindungspools normal funktionieren können.
## Schlüssel-Features
Automatische Tokengenerierung
IAM-Token werden automatisch mithilfe von Anmeldeinformationen generiert. AWS
Nahtlose Integration
Funktioniert mit vorhandenen JDBC-Verbindungsmustern, ohne dass Änderungen im Workflow erforderlich werden.
AWS Support von Anmeldedaten
Unterstützt verschiedene Anbieter von AWS Anmeldeinformationen (standardmäßig, profilbasiert usw.).
Kompatibilität für Verbindungspooling
Nahtlos kompatibel mit Verbindungspooling-Bibliotheken wie HikarICP.
## Voraussetzungen
Prüfen Sie bevor Sie beginnen ob die folgenden Voraussetzungen erfüllt sind:
+ [In Aurora DSQL wurde ein Cluster erstellt](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html).
+ Die Java Development Kits (JDK) wurden installiert. Stellen Sie sicher, dass Sie Version 17 oder höher verwenden.
+ Richten Sie die entsprechenden IAM-Berechtigungen ein, damit Ihre Anwendung eine Verbindung zu Aurora DSQL herstellen kann.
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI Umgebungsvariablen oder IAM-Rollen).
## Verwenden des Aurora DSQL Connectors für JDBC
Gehen Sie wie folgt vor, um den Aurora DSQL Connector für JDBC in Ihrer Java-Anwendung zu verwenden:
1. Fügen Sie Ihrem Projekt die folgenden Abhängigkeiten in Ihrem Maven-Projekt hinzu:
```
software.amazon.dsql
aurora-dsql-jdbc-connector
1.0.0
```
Fügen Sie für Gradle-Projekte diese Abhängigkeit hinzu:
```
implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
```
1. Erstellen Sie eine grundlegende Verbindung zu Ihrem Aurora DSQL-Cluster mithilfe des AWS DSQL PostgreSQL-Connector-Formats:
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class DsqlJdbcConnectorExample {
public static void main(String[] args) {
// Using AWS DSQL PostgreSQL Connector prefix
String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
// Use the connection
try (Statement statement = connection.createStatement()) {
// Create a table
statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
// Insert data
statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
// Query data
try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
while (resultSet.next()) {
System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
}
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}
```
### Konfigurationseigenschaften
Der Aurora DSQL Connector für JDBC unterstützt die folgenden Verbindungseigenschaften:
user
Ermittelt den Benutzer für die Verbindung und die verwendete Methode zur Tokengenerierung. Beispiel: `admin`
token-duration-secs
Gültigkeitsdauer des Tokens in Sekunden. Weitere Informationen zu Token-Limits finden Sie unter [Generieren eines Authentifizierungstokens in Amazon Aurora DSQL](SECTION_authentication-token.md).
Profil
Wird für die Instanziierung einer ProfileCredentialsProvider For-Token-Generierung mit dem angegebenen Profilnamen verwendet.
Region
AWS Region für Aurora DSQL-Verbindungen. Es ist optional. Falls angegeben, überschreibt dies die aus der URL extrahierte Region.
Datenbank
Der Name der Datenbank, mit der eine Verbindung hergestellt werden soll. Der Standardwert ist `postgres`.
### Protokollierung
Aktivieren Sie die Protokollierung, um Probleme zu beheben, die bei der Verwendung des JDBC-Konnektors für Aurora DSQL auftreten könnten.
Der Konnektor verwendet das integrierte Java-Protokollierungssystem (java.util.logging). Sie können die Protokollierungsebenen konfigurieren, indem Sie eine `logging.properties`-Datei erstellen:
```
# Set root logger level to INFO for clean output
.level = INFO
# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE
# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```
### Beispiele
Umfassendere Beispiele und Anwendungsfälle finden Sie im [Aurora DSQL Connector for JDBC-Repository](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)
# Aurora DSQL-Konnektor für Python
Der [Aurora DSQL Connector für Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) integriert die IAM-Authentifizierung für die Verbindung von Python-Anwendungen mit Amazon Aurora DSQL-Clustern. [Intern verwendet er die Clientbibliotheken [psycopg, [psycopg2](https://github.com/psycopg/psycopg2) und asyncpg](https://github.com/psycopg/psycopg).](https://github.com/MagicStack/asyncpg)
Der Aurora DSQL Connector für Python ist als Authentifizierungs-Plugin konzipiert, das die Funktionalität der Clientbibliotheken psycopg, psycopg2 und asyncpg erweitert, sodass Anwendungen sich mit Amazon Aurora DSQL mithilfe von IAM-Anmeldeinformationen authentifizieren können. Der Connector stellt keine direkte Verbindung zur Datenbank her, sondern bietet zusätzlich zu den zugrunde liegenden Client-Bibliotheken eine nahtlose IAM-Authentifizierung.
## Über den Connector
Amazon Aurora DSQL ist ein verteilter SQL-Datenbankservice, der hohe Verfügbarkeit und Skalierbarkeit für PostgreSQL-kompatible Anwendungen bietet. Aurora DSQL erfordert eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token, die bestehende Python-Bibliotheken nicht nativ unterstützen.
Die Idee hinter dem Aurora DSQL Connector für Python besteht darin, zusätzlich zu den Clientbibliotheken psycopg, psycopg2 und asyncpg eine Authentifizierungsebene hinzuzufügen, die die IAM-Token-Generierung übernimmt und es Benutzern ermöglicht, sich mit Aurora DSQL zu verbinden, ohne ihre bestehenden Workflows zu ändern.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die Authentifizierung:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung:** Authentifizierungstoken werden mithilfe von AWS-Anmeldeinformationen generiert und haben konfigurierbare Lebensdauern
Der Aurora DSQL Connector für Python wurde entwickelt, um diese Anforderungen zu verstehen und beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken zu generieren.
### Features
+ **Automatische IAM-Authentifizierung** — IAM-Token werden automatisch mithilfe von AWS-Anmeldeinformationen generiert
+ **Basiert auf psycopg, psycopg2 und asyncpg — nutzt die Clientbibliotheken psycopg, psycopg2 und asyncpg**
+ **Nahtlose Integration** — Funktioniert mit bestehenden Verbindungsmustern von psycopg, psycopg2 und asyncpg, ohne dass Änderungen am Arbeitsablauf erforderlich sind
+ **Automatische Erkennung der Region** — Extrahiert die AWS-Region aus dem DSQL-Cluster-Hostnamen
+ **Support für AWS-Anmeldeinformationen** — Unterstützt verschiedene AWS-Anmeldeinformationsanbieter (Standard, profilbasiert, benutzerdefiniert)
+ **Kompatibilität mit Verbindungspooling** — Funktioniert mit dem integrierten Verbindungspooling von psycopg, psycopg2 und asyncpg
## Schnellstart-Anleitung
### Voraussetzungen
+ Python 3.10 oder höher
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Richten Sie die entsprechenden IAM-Berechtigungen ein, damit Ihre Anwendung eine Verbindung zu Aurora DSQL herstellen kann.
+ AWS-Anmeldeinformationen konfiguriert (über AWS-CLI, Umgebungsvariablen oder IAM-Rollen)
### Installation
```
pip install aurora-dsql-python-connector
```
#### Installieren Sie psycopg oder psycopg2 oder asyncpg separat
Das Aurora DSQL Connector for Python-Installationsprogramm installiert die zugrunde liegenden Bibliotheken nicht. Sie müssen separat installiert werden, z. B.:
```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```
```
# Install psycopg2
pip install psycopg2-binary
```
```
# Install asyncpg
pip install asyncpg
```
**Hinweis:**
Nur die Bibliothek, die benötigt wird, muss installiert werden. Wenn der Client psycopg verwenden möchte, muss daher nur psycopg installiert werden. Wenn der Client psycopg2 verwenden soll, muss nur psycopg2 installiert werden. Wenn der Client asyncpg verwenden soll, muss nur asyncpg installiert werden.
Wenn der Client mehr als eine benötigt, müssen alle benötigten Bibliotheken installiert werden.
### Grundlegende Verwendung
#### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
#### Benutze nur den Host
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
#### Nur Cluster-ID verwenden
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster")
```
**Hinweis:**
Im Szenario „Nur Cluster-ID verwenden“ wird die Region verwendet, die zuvor auf dem Computer festgelegt wurde, z. B.:
```
aws configure set region us-east-1
```
Wenn die Region nicht festgelegt wurde oder sich die angegebene Cluster-ID in einer anderen Region befindet, schlägt die Verbindung fehl. Damit es funktioniert, geben Sie Region als Parameter an, wie im folgenden Beispiel:
##### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
"region": "us-east-1",
}
conn = await dsql.connect("your-cluster", **config)
```
### Verbindungszeichenfolge
#### Psychopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
### Erweiterte Konfiguration
#### Psychopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
### Konfigurationsoptionen
| Option | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| host | string | Ja | Hostname oder Cluster-ID des DSQL-Clusters |
| user | string | Nein | DSQL-Benutzername. Standard: admin |
| dbname | string | Nein | Datenbankname. Standard: Postgres |
| region | string | Nein | AWS-Region (automatisch anhand des Hostnamens erkannt, falls nicht angegeben) |
| port | int | Nein | Die Standardeinstellung ist 5432 |
| custom\$1credentials\$1provider | CredentialProvider | Nein | Anbieter für benutzerdefinierte AWS-Anmeldeinformationen |
| profile | string | Nein | Der Name des IAM-Profils. Standard: Standard. |
| token\$1duration\$1secs | int | Nein | Ablaufzeit des Tokens in Sekunden |
**Alle Standardverbindungsoptionen der zugrunde liegenden Bibliotheken psycopg, psycopg2 und asyncpg werden ebenfalls unterstützt, mit Ausnahme der asyncpg-Parameter **krbsrvname** und gsslib, die von DSQL nicht unterstützt werden.**
### Verwenden des Aurora DSQL-Konnektors für Python mit Verbindungspooling
Der Aurora DSQL Connector für Python funktioniert mit dem integrierten Verbindungspooling von psycopg, psycopg2 und asyncpg. Der Konnektor übernimmt die Generierung von IAM-Tokens während des Verbindungsaufbaus, sodass die Verbindungspools normal funktionieren können.
#### psycopg
Für psycopg implementiert der Konnektor eine Verbindungsklasse namens DSQLConnection , die direkt an den psycopg\$1pool übergeben werden kann. ConnectionPool Konstruktor. Für asynchrone Operationen gibt es auch eine asynchrone Version der Klasse namens Connection. DSQLAsync
```
from psycopg_pool import ConnectionPool as PsycopgPool
...
pool = PsycopgPool(
"",
connection_class=dsql.DSQLConnection,
kwargs=conn_params,
min_size=2,
max_size=8,
max_lifetime=3300
)
```
**Hinweis: Max\$1Lifetime-Konfiguration der Verbindung**
Der Parameter max\$1lifetime sollte auf weniger als 3600 Sekunden (eine Stunde) gesetzt werden, da dies die maximale Verbindungsdauer ist, die von der Aurora DSQL-Datenbank zulässig ist. Wenn Sie einen niedrigeren Wert für max\$1lifetime festlegen, kann der Verbindungspool die Wiederverwendung von Verbindungen proaktiv verwalten. Dies ist effizienter als die Behandlung von Verbindungs-Timeout-Fehlern in der Datenbank.
#### psycopg2
Für psycopg2 stellt der Konnektor eine Klasse namens Aurora bereit, die von DSQLThreaded ConnectionPool psycopg2.pool erbt. ThreadedConnectionPool. Die DSQLThreaded ConnectionPool Aurora-Klasse überschreibt nur die interne \$1connect-Methode. Der Rest der Implementierung wird von psycopg2.pool bereitgestellt. ThreadedConnectionPool unverändert.
```
import aurora_dsql_psycopg2 as dsql
pool = dsql.AuroraDSQLThreadedConnectionPool(
minconn=2,
maxconn=8,
**conn_params,
)
```
#### asyncpg
Für asyncpg stellt der Konnektor eine create\$1pool-Funktion bereit, die eine Instanz von asyncPG.Pool zurückgibt.
```
import asyncio
import os
import aurora_dsql_asyncpg as dsql
pool_params = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'user': "admin",
"min_size": 2,
"max_size": 5,
}
pool = await dsql.create_pool(**pool_params)
```
## Authentifizierung
Der Connector verarbeitet die DSQL-Authentifizierung automatisch, indem er mithilfe des DSQL-Client-Token-Generators Token generiert. Wenn die AWS-Region nicht angegeben wird, wird sie automatisch anhand des angegebenen Hostnamens analysiert.
Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie im [Benutzerhandbuch](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin im Vergleich zu regulären Benutzern
+ Benannte Benutzer verwenden `"admin"` automatisch Administratorauthentifizierungstoken
+ Alle anderen Benutzer verwenden Authentifizierungstoken, die keine Administratorrechte haben
+ Token werden dynamisch für jede Verbindung generiert
## Beispiele
Den vollständigen Beispielcode finden Sie in den Beispielen, die in den folgenden Abschnitten angegeben sind. Anweisungen zur Ausführung der Beispiele finden Sie in den READMDE-Beispieldateien.
### psycopg
[Beispiele README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md)
| Description | Beispiele |
| --- | --- |
| Verwenden des Aurora DSQL Connectors für Python für grundlegende Verbindungen | [Beispiel für eine grundlegende Verbindung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Verwenden des Aurora DSQL Connectors für Python für grundlegende asynchrone Verbindungen | [Grundlegendes Beispiel für eine asynchrone Verbindung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/no_connection_pool/example_async_with_no_connection_pool.py) |
| Verwenden des Aurora DSQL Connectors für Python mit Verbindungspool | [Einfaches Verbindungsbeispiel mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Beispiel für gleichzeitige Verbindungen mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Verwenden des Aurora DSQL Connectors für Python mit asynchronem Verbindungspool | [Einfaches Verbindungsbeispiel mit asynchronem Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py) |
### psycopg2
[Beispiele README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md)
| Description | Beispiele |
| --- | --- |
| Verwenden des Aurora DSQL Connectors für Python für grundlegende Verbindungen | [Beispiel für eine grundlegende Verbindung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
| Verwenden des Aurora DSQL Connectors für Python mit Verbindungspool | [Einfaches Verbindungsbeispiel mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Beispiel für gleichzeitige Verbindungen mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
### asyncpg
[Beispiele README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md)
| Description | Beispiele |
| --- | --- |
| Verwenden des Aurora DSQL Connectors für Python für grundlegende Verbindungen | [Beispiel für eine grundlegende Verbindung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
| Verwenden des Aurora DSQL Connectors für Python mit Verbindungspool | [Einfaches Verbindungsbeispiel mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Beispiel für gleichzeitige Verbindungen mit Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
# Verbindung zu Aurora DSQL-Clustern mit einem Go-Connector herstellen
Der [Aurora DSQL Connector for Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) umschließt [PGX](https://github.com/jackc/pgx) mit automatischer IAM-Authentifizierung. Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungsmanagement, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.
## Über den Konnektor
Aurora DSQL erfordert eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token, die bestehende Go PostgreSQL-Treiber nicht nativ unterstützen. Der Aurora DSQL Connector for Go fügt dem pgx-Treiber eine Authentifizierungsebene hinzu, die die IAM-Token-Generierung übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden pgx-Workflows zu ändern.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer
Der Aurora DSQL Connector for Go wurde entwickelt, um diese Anforderungen zu verstehen und beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken zu generieren.
### Vorteile des Aurora DSQL Connector for Go
Mit dem Aurora DSQL Connector for Go können Sie Ihre bestehenden PGX-Workflows weiterhin verwenden und gleichzeitig die IAM-Authentifizierung aktivieren über:
+ **Automatische Token-Generierung**: Der Connector generiert automatisch IAM-Token für jede Verbindung
+ **Verbindungspooling**: Integrierte Unterstützung für die `pgxpool` automatische Token-Generierung pro Verbindung
+ **Flexible Konfiguration**: Support für vollständige Endgeräte oder Cluster IDs mit automatischer Regionserkennung
+ **AWS Support für Anmeldeinformationen**: Unterstützt AWS Profile und Anbieter von benutzerdefinierten Anmeldeinformationen
## Schlüssel-Features
Automatische Tokenverwaltung
Der Connector generiert automatisch IAM-Token für jede neue Verbindung unter Verwendung vorab aufgelöster Anmeldeinformationen.
Verbindungspooling
Verbindungspooling über `pgxpool` mit automatischer Token-Generierung pro Verbindung.
Flexible Host-Konfiguration
Unterstützt sowohl vollständige Cluster-Endpunkte als auch Cluster IDs mit automatischer Regionserkennung.
SSL-Sicherheit
SSL ist im Modus „Verify-Full“ und direkter TLS-Aushandlung immer aktiviert.
## Voraussetzungen
+ Go 1.24 oder höher
+ AWS Anmeldeinformationen konfiguriert
+ Ein Aurora DSQL-Cluster
Der Connector verwendet die [standardmäßige Anmeldeinformationskette des AWS SDK for Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), die Anmeldeinformationen in der folgenden Reihenfolge auflöst:
1. Umgebungsvariablen (AWS\$1ACCESS\$1KEY\$1ID, \$1ACCESS\$1KEY) AWS\$1SECRET
1. Datei mit gemeinsam genutzten Anmeldeinformationen (\$1/.aws/credentials)
1. Gemeinsam genutzte Konfigurationsdatei (\$1/.aws/config)
1. IAM-Rolle für Amazon EC2/ECS/Lambda
## Installation
Installieren Sie den Connector mithilfe von Go-Modulen:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```
## Schnellstart
Das folgende Beispiel zeigt, wie Sie einen Verbindungspool erstellen und eine Abfrage ausführen:
```
package main
import (
"context"
"log"
"github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
)
func main() {
ctx := context.Background()
// Create a connection pool
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer pool.Close()
// Execute a query
var greeting string
err = pool.QueryRow(ctx, "SELECT 'Hello, DSQL!'").Scan(&greeting)
if err != nil {
log.Fatal(err)
}
log.Println(greeting)
}
```
## Konfigurationsoptionen
Der Connector unterstützt die folgenden Konfigurationsoptionen:
| Feld | Typ | Standard | Description |
| --- | --- | --- | --- |
| Host | Zeichenfolge | (erforderlich) | Cluster-Endpunkt oder Cluster-ID |
| Region | Zeichenfolge | (automatisch erkannt) | AWS Region; erforderlich, wenn Host eine Cluster-ID ist |
| Benutzer | Zeichenfolge | „Administrator“ | Datenbankbenutzer |
| Datenbank | Zeichenfolge | „Postgres“ | Datenbankname |
| Port | int | 5432 | Datenbankport |
| Profil | Zeichenfolge | "" | AWS Profilname für Anmeldeinformationen |
| TokenDurationSecs | int | 900 (15 Minuten) | Gültigkeitsdauer des Tokens in Sekunden (maximal zulässig: 1 Woche, Standard: 15 Minuten) |
| MaxConns | int32 | 0 | Maximale Anzahl an Pool-Verbindungen (0 = pgxpool-Standard) |
| MinConns | int32 | 0 | Minimale Anzahl an Poolverbindungen (0 = pgxpool-Standard) |
| MaxConnLifetime | Zeit.Dauer | 55 Minuten | Maximale Verbindungslebensdauer |
## Format der Verbindungszeichenfolge
Der Connector unterstützt PostgreSQL- und DSQL-Verbindungszeichenfolgenformate:
```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```
Unterstützte Abfrageparameter:
+ `region`- AWS Region
+ `profile`- AWS Profilname
+ `tokenDurationSecs`- Gültigkeitsdauer des Tokens in Sekunden
Beispiele:
```
// Full endpoint (region auto-detected)
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres")
// Using dsql:// scheme (also supported)
pool, _ := dsql.NewPool(ctx, "dsql://admin@cluster.dsql.us-east-1.on.aws/postgres")
// With explicit region
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/mydb?region=us-east-1")
// With AWS profile
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev")
```
## Fortgeschrittene Nutzung
### Host-Konfiguration
Der Connector unterstützt zwei Host-Formate:
**Vollständiger Endpunkt** (Region automatisch erkannt):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
```
**Cluster-ID** (Region erforderlich):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster-id",
Region: "us-east-1",
})
```
### Optimierung der Poolkonfiguration
Konfigurieren Sie den Verbindungspool für Ihren Workload:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
MaxConns: 20,
MinConns: 5,
MaxConnLifetime: time.Hour,
MaxConnIdleTime: 30 * time.Minute,
HealthCheckPeriod: time.Minute,
})
```
### Nutzung einer einzelnen Verbindung
Für einfache Skripte oder wenn kein Verbindungspooling benötigt wird:
```
conn, err := dsql.Connect(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer conn.Close(ctx)
// Use the connection
rows, err := conn.Query(ctx, "SELECT * FROM users")
```
### Profile verwenden AWS
Geben Sie ein AWS Profil für Anmeldeinformationen an:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
Profile: "production",
})
```
## OCC-Wiederholung
Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.
Das `occretry` Paket bietet Hilfsprogramme für automatische Wiederholungen bei exponentiellem Backoff und Jitter. Installiere es mit:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```
`WithRetry`Für transaktionale Schreibvorgänge verwenden:
```
err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error {
_, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
if err != nil {
return err
}
_, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
return err
})
```
Verwenden Sie für DDL- oder Einzelanweisungen: `ExecWithRetry`
```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
"CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```
**Wichtig**
`WithRetry`verwaltet`BEGIN`/`COMMIT`/`ROLLBACK`intern. Ihr Callback empfängt eine Transaktion und sollte nur Datenbankoperationen enthalten und sicher sein, es erneut zu versuchen.
## Beispiele
Umfassendere Beispiele und Anwendungsfälle finden Sie in den [Aurora DSQL Connector for Go-Beispielen](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).
| Beispiel | Description |
| --- | --- |
| [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go) | Empfohlen: Verbindungspool mit gleichzeitigen Abfragen |
| [Transaktion](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction) | Transaktionsabwicklung mit BEGIN/COMMIT/ROLLBACK |
| [occ\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry) | Umgang mit OCC-Konflikten mit exponentiellem Backoff |
| [Verbindungszeichenfolge](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string) | Verbindungszeichenfolgen für die Konfiguration verwenden |
# Aurora DSQL-Konnektoren für Node.js
Der Aurora DSQL Connector für node-postgres und der Aurora DSQL Connector für Postgres.js sind Authentifizierungs-Plugins, die die Funktionalität der Clients node-postgres und Postgres.js erweitern, sodass Anwendungen sich mit Aurora DSQL mithilfe von IAM-Anmeldeinformationen authentifizieren können.
# Aurora DSQL-Konnektor für Node-Postgres
Der [Aurora DSQL Connector für Node-Postgres ist ein Node.js Connector, der auf [Node-Postgres](https://node-postgres.com/)](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) basiert und die IAM-Authentifizierung für die Verbindung von Anwendungen mit Amazon Aurora DSQL-Clustern integriert. JavaScript/TypeScript
Der Aurora DSQL Connector ist als Authentifizierungs-Plugin konzipiert, das die Funktionalität des Clients und Pools von Node-Postgres erweitert, sodass Anwendungen sich mit Amazon Aurora DSQL mithilfe von IAM-Anmeldeinformationen authentifizieren können.
## Über den Connector
Amazon Aurora DSQL ist eine Cloud-native verteilte Datenbank mit PostgreSQL-Kompatibilität. Sie erfordert zwar IAM-Authentifizierung und zeitgebundene Token, aber bei herkömmlichen Node.js Datenbanktreibern fehlt diese integrierte Unterstützung.
Der Aurora DSQL Connector für Node-Postgres schließt diese Lücke, indem er eine Authentifizierungs-Middleware implementiert, die nahtlos mit Node-Postgres zusammenarbeitet. Dieser Ansatz ermöglicht es Entwicklern, ihren bestehenden Node-Postgres-Code beizubehalten und gleichzeitig durch automatisiertes Token-Management sicheren IAM-basierten Zugriff auf Aurora DSQL-Cluster zu erhalten.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die Authentifizierung:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung:** Authentifizierungstoken werden mithilfe von AWS-Anmeldeinformationen generiert und haben eine konfigurierbare Lebensdauer
Der Aurora DSQL Connector für Node-Postgres wurde entwickelt, um diese Anforderungen zu verstehen und beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken zu generieren.
### Features
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von DSQL-Tokens
+ **Basiert auf Node-Postgres** — Nutzt den beliebten PostgreSQL-Client für Node.js
+ **Nahtlose Integration** — Funktioniert mit bestehenden Node-Postgres-Verbindungsmustern
+ **Automatische Erkennung der Region** — Extrahiert die AWS-Region aus dem DSQL-Cluster-Hostnamen
+ ** TypeScript Umfassender Support** — bietet volle Typsicherheit
+ **Support für AWS-Anmeldeinformationen** — Unterstützt verschiedene AWS-Anmeldeinformationsanbieter (Standard, profilbasiert, benutzerdefiniert)
+ **Kompatibilität mit Verbindungspooling** — Funktioniert problemlos mit dem integrierten Verbindungspooling
## Beispielanwendung
Im [Beispiel](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example) ist eine Beispielanwendung enthalten, die zeigt, wie Aurora DSQL Connector für Node-Postgres verwendet wird. [Um das mitgelieferte Beispiel auszuführen, lesen Sie bitte die README-Beispieldatei.](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)
## Schnellstartanleitung
### Voraussetzungen
+ Node.js 20\$1
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Richten Sie die entsprechenden IAM-Berechtigungen ein, damit Ihre Anwendung eine Verbindung zu Aurora DSQL herstellen kann.
+ AWS-Anmeldeinformationen konfiguriert (über AWS-CLI, Umgebungsvariablen oder IAM-Rollen)
## Installation
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Abhängigkeiten von Kollegen
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Usage
### Client-Verbindung
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### Pool-Verbindung
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### Erweiterte Nutzung
```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "example.dsql.us-east-1.on.aws",
user: "admin",
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
## Konfigurationsoptionen
| Option | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| host | string | Ja | Hostname des DSQL-Clusters |
| username | string | Ja | DSQL-Benutzername |
| database | string | Nein | Datenbankname |
| region | string | Nein | AWS-Region (automatisch anhand des Hostnamens erkannt, falls nicht angegeben) |
| port | number | Nein | Die Standardeinstellung ist 5432 |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | Nein | Anbieter für benutzerdefinierte AWS-Anmeldeinformationen |
| profile | string | Nein | Der IAM-Profilname. Die Standardeinstellung ist „Standard“ |
| tokenDurationSecs | number | Nein | Ablaufzeit des Tokens in Sekunden |
Alle anderen Parameter von [Client](https://node-postgres.com/apis/client) [/Pool](https://node-postgres.com/apis/pool) werden unterstützt.
## Authentifizierung
Der Connector verarbeitet die DSQL-Authentifizierung automatisch, indem er mithilfe des DSQL-Client-Token-Generators Token generiert. Wenn die AWS-Region nicht angegeben wird, wird sie automatisch anhand des angegebenen Hostnamens analysiert.
Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie im [Benutzerhandbuch](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin im Vergleich zu regulären Benutzern
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Token werden dynamisch für jede Verbindung generiert
# Aurora DSQL-Konnektor für Postgres.js
Der [Aurora DSQL Connector for Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) ist ein Node.js Connector, der auf [Postgres.js](https://github.com/porsager/postgres) basiert und die IAM-Authentifizierung für die Verbindung von JavaScript Anwendungen mit Amazon Aurora DSQL-Clustern integriert.
Der Aurora DSQL Connector für Postgres.js ist als Authentifizierungs-Plugin konzipiert, das die Funktionalität des Postgres.js -Clients erweitert, sodass Anwendungen sich mit Amazon Aurora DSQL mithilfe von IAM-Anmeldeinformationen authentifizieren können. Der Connector stellt keine direkte Verbindung zur Datenbank her, sondern bietet zusätzlich zum zugrunde liegenden Postgres.js -Treiber eine nahtlose IAM-Authentifizierung.
## Über den Connector
Amazon Aurora DSQL ist ein verteilter SQL-Datenbankservice, der hohe Verfügbarkeit und Skalierbarkeit für PostgreSQL-kompatible Anwendungen bietet. Aurora DSQL erfordert eine IAM-basierte Authentifizierung mit zeitlich begrenzten Tokens, die vorhandene Node.js -Treiber nicht nativ unterstützen.
Die Idee hinter dem Aurora DSQL Connector for Postgres.js besteht darin, dem Client Postgres.js eine Authentifizierungsebene hinzuzufügen, die die Generierung von IAM-Tokens übernimmt, sodass Benutzer eine Verbindung zu Aurora DSQL herstellen können, ohne ihre bestehenden Postgres.js -Workflows zu ändern.
Der Aurora DSQL Connector für Postgres.js funktioniert mit den meisten Versionen von Postgres.js. Benutzer stellen ihre eigene Version bereit, indem sie Postgres.js direkt installieren.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die Authentifizierung:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung:** Authentifizierungstoken werden mithilfe von AWS-Anmeldeinformationen generiert und haben konfigurierbare Lebensdauern
Der Aurora DSQL Connector für Postgres.js wurde entwickelt, um diese Anforderungen zu verstehen und beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken zu generieren.
### Features
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von DSQL-Tokens
+ **Basiert auf Postgres.js** — Nutzt den schnellen PostgreSQL-Client für Node.js
+ **Nahtlose Integration** — Funktioniert mit vorhandenen Postgres.js Verbindungsmustern
+ **Automatische Erkennung der Region** — Extrahiert die AWS-Region aus dem DSQL-Cluster-Hostnamen
+ ** TypeScript Umfassender Support** — bietet volle Typsicherheit
+ **Support für AWS-Anmeldeinformationen** — Unterstützt verschiedene AWS-Anmeldeinformationsanbieter (Standard, profilbasiert, benutzerdefiniert)
+ **Kompatibilität mit Verbindungspooling** — Funktioniert nahtlos mit dem integrierten Verbindungspooling von Postgres.js
## Schnellstart-Anleitung
### Voraussetzungen
+ Node.js 20\$1
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Richten Sie die entsprechenden IAM-Berechtigungen ein, damit Ihre Anwendung eine Verbindung zu Aurora DSQL herstellen kann.
+ AWS-Anmeldeinformationen konfiguriert (über AWS-CLI, Umgebungsvariablen oder IAM-Rollen)
### Installation
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### Grundlegende Verwendung
```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';
const sql = auroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
username: 'admin',
});
// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);
// Clean up
await sql.end();
```
#### Cluster-ID anstelle von Host verwenden
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### Verbindungszeichenfolge
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### Erweiterte Konfiguration
```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
const sql = AuroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
database: 'postgres',
username: 'admin',
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
tokenDurationSecs: 3600, // Token expiration (seconds)
// Standard Postgres.js options
max: 20, // Connection pool size
ssl: { rejectUnauthorized: false } // SSL configuration
});
```
## Konfigurationsoptionen
| Option | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| host | string | Ja | Hostname oder Cluster-ID des DSQL-Clusters |
| database | string? | Nein | Datenbankname |
| username | string? | Nein | Datenbank-Benutzername (verwendet admin, falls nicht angegeben) |
| region | string? | Nein | AWS-Region (automatisch anhand des Hostnamens erkannt, falls nicht angegeben) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | Nein | Anbieter für benutzerdefinierte AWS-Anmeldeinformationen |
| tokenDurationSecs | number? | Nein | Ablaufzeit des Tokens in Sekunden |
Alle [Standardoptionen von Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) werden ebenfalls unterstützt.
## Authentifizierung
Der Connector verarbeitet die DSQL-Authentifizierung automatisch, indem er mithilfe des DSQL-Client-Token-Generators Token generiert. Wenn die AWS-Region nicht angegeben wird, wird sie automatisch anhand des angegebenen Hostnamens analysiert.
Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie im [Benutzerhandbuch](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin im Vergleich zu regulären Benutzern
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Tokens werden dynamisch für jede Verbindung generiert
## Beispiel für die Verwendung
JavaScript Beispiele, die den Aurora DSQL Connector für Postgres.js verwenden, finden Sie unter GitHub. Anweisungen zur Ausführung der Beispiele finden Sie im [Beispielverzeichnis](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example).
| Description | Beispiel |
| --- | --- |
| Verbindungspooling mit gleichzeitigen Abfragen, einschließlich Tabellenerstellung, Einfügungen und Lesevorgängen für mehrere Worker | [Beispiel für einen Verbindungspool (bevorzugt)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| CRUD-Operationen (Tabelle erstellen, einfügen, auswählen, löschen) ohne Verbindungspooling | [Beispiel ohne Verbindungspool](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |
# Verbindung zu Aurora DSQL-Clustern mit einem Ruby-Konnektor herstellen
Der [Aurora DSQL Connector für Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) ist ein auf [pg](https://github.com/ged/ruby-pg) basierender Ruby-Connector, der die IAM-Authentifizierung für die Verbindung von Ruby-Anwendungen mit Amazon Aurora DSQL-Clustern integriert.
Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungspooling, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.
## Über den Konnektor
Amazon Aurora DSQL erfordert eine IAM-Authentifizierung mit zeitlich begrenzten Token, die von vorhandenen Ruby PostgreSQL-Treibern nicht nativ unterstützt werden. Der Aurora DSQL Connector für Ruby fügt dem PG-Gem eine Authentifizierungsebene hinzu, die die IAM-Token-Generierung übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden pg-Workflows zu ändern.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer
Der Aurora DSQL Connector for Ruby versteht diese Anforderungen und generiert beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken.
### Features
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von Aurora DSQL-Tokens
+ **Built on pg** — Umschließt das beliebte PostgreSQL-Gem für Ruby
+ **Nahtlose Integration** — Funktioniert mit bestehenden PG-Gem-Workflows
+ **Verbindungspooling** — Integrierte Unterstützung über das `connection_pool` Gem mit max\$1lifetime-Durchsetzung
+ **Automatische Erkennung von Regionen** — Extrahiert die AWS Region aus dem Hostnamen des Aurora DSQL-Clusters
+ **AWS Unterstützung für Anmeldeinformationen** — Unterstützt AWS Profile und Anbieter von benutzerdefinierten Anmeldeinformationen
+ **OCC-Wiederholung** — Opt-In für optimistische Parallelitätssteuerung mit exponentiellem Backoff
## Beispiel
[Ein vollständiges Beispiel finden Sie in der Beispielanwendung unter.](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) GitHub
## Schnellstart-Anleitung
### Voraussetzungen
+ Ruby 3.1 oder höher
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI, Umgebungsvariablen oder IAM-Rollen)
## Installation
Fügen Sie zu Ihrem Gemfile hinzu:
```
gem "aurora-dsql-ruby-pg"
```
Oder direkt installieren:
```
gem install aurora-dsql-ruby-pg
```
## Usage
### Verbindung zum Pool
```
require "aurora_dsql_pg"
# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
# Read
pool.with do |conn|
result = conn.exec("SELECT 'Hello, DSQL!'")
puts result[0]["?column?"]
end
# Write — you must wrap writes in a transaction
pool.with do |conn|
conn.transaction do
conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
end
end
pool.shutdown
```
### Einzelne -Verbindung
Für einfache Skripte oder wenn kein Verbindungspooling benötigt wird:
```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```
### Fortgeschrittene Nutzung
**Host-Konfiguration**
Der Connector unterstützt sowohl vollständige Cluster-Endpunkte (Region automatisch erkannt) als auch Cluster IDs (Region erforderlich):
```
# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws"
)
# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster-id",
region: "us-east-1"
)
```
**AWS Profile**
Geben Sie ein AWS Profil für Anmeldeinformationen an:
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
profile: "production"
)
```
**Format der Verbindungszeichenfolge**
Der Konnektor unterstützt PostgreSQL-Verbindungszeichenfolgenformate:
```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```
Unterstützte Abfrageparameter:`region`,,`profile`. `tokenDurationSecs`
```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
"postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```
**OCC-Wiederholung**
Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.
Die OCC-Wiederholung ist optional. `occ_max_retries`Wird bei der Erstellung des Pools so eingestellt, dass automatische Wiederholungen mit exponentiellem Backoff und aktiviertem Jitter aktiviert sind: `pool.with`
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
pool.with do |conn|
conn.transaction do
conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
end
end
```
**Warnung**
`pool.with`wickelt Ihren Block NICHT automatisch in eine Transaktion ein. Für Schreiboperationen müssen Sie `conn.transaction` sich selbst anrufen. Bei einem OCC-Konflikt führt der Konnektor den gesamten Block erneut aus, sodass er nur Datenbankoperationen enthalten sollte und ein erneuter Versuch sicher sein sollte.
Um den Wiederholungsversuch bei einzelnen Aufrufen zu überspringen, übergeben Sie: `retry_occ: false`
```
pool.with(retry_occ: false) do |conn|
conn.exec("SELECT 1")
end
```
## Konfigurationsoptionen
| Feld | Typ | Standard | Description |
| --- | --- | --- | --- |
| Host | Zeichenfolge | (erforderlich) | Cluster-Endpunkt oder Cluster-ID |
| Region | Zeichenfolge | (automatisch erkannt) | AWS Region; erforderlich, wenn es sich bei dem Host um eine Cluster-ID handelt |
| user | Zeichenfolge | „Administrator“ | Datenbankbenutzer |
| Datenbank | Zeichenfolge | „Postgres“ | Datenbankname |
| port | Ganzzahl | 5432 | Datenbankport |
| Profil | Zeichenfolge | Null | AWS Profilname für Anmeldeinformationen |
| token\$1duration | Ganzzahl | 900 (15 Minuten) | Gültigkeitsdauer des Tokens in Sekunden (maximal zulässig: 1 Woche, Standard: 15 Minuten) |
| credentials\$1provider | Aws:: Anmeldeinformationen | Null | Anbieter für benutzerdefinierte Anmeldeinformationen |
| max\$1lifetime | Ganzzahl | 3300 (55 Minuten) | Maximale Verbindungslebensdauer in Sekunden |
| application\$1name | Zeichenfolge | Null | ORM-Präfix für application\$1name |
| Logger | Logger | Null | Logger für OCC-Wiederholungswarnungen |
| occ\$1max\$1retries | Ganzzahl | nil (deaktiviert) | Max. OCC-Wiederholungsversuche aktiviertpool.with; aktiviert Wiederholungsversuche, wenn diese Einstellung gesetzt ist |
`create_pool`akzeptiert auch ein `pool:` Schlüsselwort mit einem Hash von Optionen, an die Sie direkt übergeben werden. `ConnectionPool.new` Wenn Sie es weglassen`pool:`, ist der Connector standardmäßig auf. `{size: 5, timeout: 5}` Schlüssel, die Sie angeben, haben nur Vorrang vor diesen spezifischen Standardwerten.
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
pool: { size: 10, timeout: 10 }
)
```
## Authentifizierung
Der Connector verarbeitet automatisch die Aurora-DSQL-Authentifizierung, indem er mithilfe von AWS Anmeldeinformationen Token generiert. Wenn Sie die AWS Region nicht angeben, analysiert der Connector sie anhand des Hostnamens.
Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie unter[Authentifizierung und Autorisierung für Aurora DSQL](authentication-authorization.md).
### Admin im Vergleich zu normalen Benutzern
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Der Connector generiert dynamisch Token für jede Verbindung
# Herstellen einer Verbindung zu Aurora DSQL-Clustern mit einem .NET-Connector
Der [Amazon Aurora DSQL Connector for .NET ist ein auf [Npgsql](https://www.npgsql.org/)](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) basierender .NET-Connector, der die IAM-Authentifizierung für die Verbindung von.NET-Anwendungen mit Amazon Aurora DSQL-Clustern integriert.
Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungspooling, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.
## Über den Konnektor
Amazon Aurora DSQL erfordert eine IAM-Authentifizierung mit zeitlich begrenzten Token, die vorhandene.NET-PostgreSQL-Treiber nicht nativ unterstützen. Der Aurora DSQL Connector for .NET fügt zusätzlich zu Npgsql eine Authentifizierungsebene hinzu, die die IAM-Token-Generierung übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden Npgsql-Workflows zu ändern.
### Was ist Aurora DSQL-Authentifizierung?
In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer
Der Aurora DSQL Connector for .NET versteht diese Anforderungen und generiert beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken.
### Features
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von Aurora DSQL-Tokens
+ **Basiert auf Npgsql** — Umschließt den beliebten PostgreSQL-Treiber für.NET
+ **Nahtlose Integration** — Funktioniert mit bestehenden Npgsql-Workflows
+ **Verbindungspooling** — Integrierte Unterstützung `NpgsqlDataSource` mit maximaler Nutzungsdauer
+ **Automatische Erkennung von Regionen** — Extrahiert die AWS Region aus dem Hostnamen des Aurora DSQL-Clusters
+ **AWS Unterstützung für Anmeldeinformationen** — Unterstützt AWS Profile und Anbieter von benutzerdefinierten Anmeldeinformationen
+ **OCC-Wiederholung** — Opt-In für optimistische Parallelitätssteuerung mit exponentiellem Backoff
+ **SSL-Durchsetzung** — Verwendet immer SSL mit Modus und direkter TLS-Aushandlung `verify-full`
## Beispiel
Ein vollständiges Beispiel finden Sie in der [Beispielanwendung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) unter GitHub.
## Schnellstart-Anleitung
### Voraussetzungen
+ .NET 8.0 oder höher
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI, Umgebungsvariablen oder IAM-Rollen)
## Installation
Fügen Sie das Paket zu Ihrem Projekt hinzu:
```
dotnet add package Amazon.AuroraDsql.Npgsql
```
## Usage
### Verbindung zum Pool
```
using Amazon.AuroraDsql.Npgsql;
// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws",
OccMaxRetries = 3
});
// Read
await using (var conn = await ds.OpenConnectionAsync())
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT 'Hello, DSQL!'";
var greeting = await cmd.ExecuteScalarAsync();
Console.WriteLine(greeting);
}
// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
cmd.Parameters.AddWithValue("name", "Alice");
await cmd.ExecuteNonQueryAsync();
});
```
### Einzelne -Verbindung
Für einfache Skripte oder wenn Sie kein Verbindungspooling benötigen:
```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws"
});
await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```
### OCC-Versuch wiederholen
Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.
Die OCC-Wiederholung ist optional. `OccMaxRetries`In der Konfiguration so eingestellt, dass automatische Wiederholungen mit exponentiellem Backoff und Jitter aktiviert werden. Für transaktionale Schreibvorgänge verwenden: `WithTransactionRetryAsync`
```
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
cmd.Parameters.AddWithValue("from", fromId);
await cmd.ExecuteNonQueryAsync();
cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("to", toId);
await cmd.ExecuteNonQueryAsync();
});
```
Verwenden Sie für DDL- oder Einzelanweisungen: `ExecWithRetryAsync`
```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```
**Wichtig**
`WithTransactionRetryAsync`verwaltet`BEGIN`/`COMMIT`/`ROLLBACK`intern und öffnet für jeden Versuch eine neue Verbindung. Ihr Rückruf sollte nur Datenbankoperationen enthalten und sicher sein, dass Sie es erneut versuchen können.
## Konfigurationsoptionen
Der Konnektor akzeptiert auch `postgresql://` Verbindungszeichenfolgen mit `postgres://` `region` und `profile` Abfrageparametern.
| Feld | Typ | Standard | Description |
| --- | --- | --- | --- |
| Host | string | (erforderlich) | Cluster-Endpunkt oder Cluster-ID mit 26 Zeichen |
| Region | string? | (automatisch erkannt) | AWS Region; erforderlich, wenn Host es sich um eine Cluster-ID handelt |
| User | string | "admin" | Datenbankbenutzer |
| Database | string | "postgres" | Datenbankname |
| Port | int | 5432 | Datenbankport |
| Profile | string? | null | AWS Profilname für Anmeldeinformationen |
| CustomCredentialsProvider | AWSCredentials? | null | Anbieter AWS für benutzerdefinierte Anmeldeinformationen |
| TokenDurationSecs | int? | null(SDK-Standard, 900s) | Gültigkeitsdauer des Tokens in Sekunden |
| OccMaxRetries | int? | null(deaktiviert) | Standardmäßige maximale Anzahl an OCC-Wiederholungen für Wiederholungsmethoden in der Datenquelle |
| OrmPrefix | string? | null | ORM-Präfix wird vorangestellt application\$1name |
| LoggerFactory | ILoggerFactory? | null | Logger-Fabrik für Wiederholungswarnungen und Diagnosen |
| ConfigureConnectionString | Action? | null | Callback, um Pool-Einstellungen zu überschreiben oder zusätzliche Eigenschaften der Npgsql-Verbindungszeichenfolge festzulegen. SSL und Enlist sind Sicherheitsinvarianten und können nicht außer Kraft gesetzt werden. |
## Authentifizierung
Der Connector verarbeitet automatisch die Aurora-DSQL-Authentifizierung, indem er mithilfe von AWS Anmeldeinformationen Token generiert. Wenn Sie die AWS Region nicht angeben, analysiert der Connector sie anhand des Hostnamens.
Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie unter[Authentifizierung und Autorisierung für Aurora DSQL](authentication-authorization.md).
### Admin im Vergleich zu normalen Benutzern
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Der Connector generiert dynamisch Token für jede Verbindung