Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Connecteurs pour Aurora DSQL
Aurora DSQL fournit des connecteurs spécialisés qui étendent les pilotes de base de données existants afin de permettre une authentification IAM fluide et une intégration aux AWS services. Ces connecteurs sont conçus pour fonctionner avec les langages de programmation et les frameworks les plus courants tout en maintenant la compatibilité avec les flux de travail PostgreSQL existants.
Des connecteurs supplémentaires sont prévus pour les prochaines versions. Pour obtenir les informations les plus récentes sur la disponibilité des connecteurs, consultez le [référentiel d’exemples Aurora DSQL](https://github.com/aws-samples/aurora-dsql-samples).
# Connexion aux clusters Aurora DSQL à l’aide d’un connecteur JDBC
Le [connecteur Aurora DSQL pour JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) est conçu comme un plug-in d'authentification qui étend les fonctionnalités du pilote JDBC PostgreSQL afin de permettre aux applications de s'authentifier auprès d'Aurora DSQL à l'aide des informations d'identification IAM. Le connecteur ne se connecte pas directement à la base de données, mais fournit une authentification IAM fluide en plus du pilote JDBC PostgreSQL sous-jacent.
Le connecteur Aurora DSQL pour JDBC est conçu pour fonctionner avec le [pilote JDBC PostgreSQL et assure une intégration parfaite avec les exigences d'authentification](https://github.com/pgjdbc/pgjdbc) IAM d'Aurora DSQL.
Associé au pilote JDBC PostgreSQL, le connecteur Aurora DSQL pour JDBC permet l'authentification basée sur IAM pour Aurora DSQL. Il introduit une intégration approfondie avec les services AWS d'authentification tels que [Gestion des identités et des accès AWS](https://aws.amazon.com/iam/)(IAM).
## À propos du connecteur
Aurora DSQL est un service de base de données SQL distribué qui fournit une disponibilité et une capacité de mise à l’échelle élevées aux applications compatibles avec PostgreSQL. Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les pilotes JDBC existants ne prennent pas en charge de manière native.
L'idée principale du connecteur Aurora DSQL pour JDBC est d'ajouter une couche d'authentification au-dessus du pilote JDBC PostgreSQL qui gère la génération de jetons IAM, permettant aux utilisateurs de se connecter à Aurora DSQL sans modifier leurs flux de travail JDBC existants.
### Qu’est-ce que l’authentification Aurora DSQL ?
Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : les jetons d'authentification sont générés à l'aide AWS d'informations d'identification et ont une durée de vie configurable
Le connecteur Aurora DSQL pour JDBC est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Avantages du connecteur Aurora DSQL pour JDBC
Bien qu’Aurora DSQL fournisse une interface compatible avec PostgreSQL, les pilotes PostgreSQL existants ne prennent actuellement pas en charge les exigences d’authentification IAM d’Aurora DSQL. Le connecteur Aurora DSQL pour JDBC permet aux clients de continuer à utiliser leurs flux de travail PostgreSQL existants tout en activant l'authentification IAM via :
+ **Génération automatique de jetons** : les jetons IAM sont générés automatiquement à l'aide d'informations d'identification AWS
+ **Intégration fluide** : compatible avec les modèles de connexion JDBC existants
+ **AWS Support des informations d'identification** : prend en charge différents fournisseurs AWS d'informations d'identification (par défaut, basé sur le profil, etc.)
### Utilisation du connecteur SQL Aurora pour JDBC avec regroupement de connexions
Le connecteur Aurora DSQL pour JDBC fonctionne avec des bibliothèques de regroupement de connexions telles que HikariCP. Le connecteur gère la génération de jetons IAM lors de l’établissement de la connexion, ce qui permet aux groupes de connexions de fonctionner normalement.
## Fonctions principales
Génération automatique de jetons
Les jetons IAM sont générés automatiquement à l'aide des AWS informations d'identification.
Intégration transparente
Compatible avec les modèles de connexion JDBC existants sans nécessiter de modifications du flux de travail.
AWS Support des informations d'identification
Prend en charge différents fournisseurs AWS d'identifiants (par défaut, basés sur le profil, etc.).
Compatibilité avec le regroupement de connexions
Parfaitement compatible avec les bibliothèques de regroupement de connexions telles que HikariCP.
## Conditions préalables
Avant de commencer, assurez-vous de remplir les prérequis suivants :
+ [Création d’un cluster dans Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html).
+ Installation du kit de développement Java (JDK). Assurez-vous qu’une version 17 ou supérieure est disponible.
+ Configuration des autorisations IAM appropriées pour permettre à votre application de se connecter à Aurora DSQL.
+ AWS informations d'identification configurées (via AWS CLI des variables d'environnement ou des rôles IAM).
## Utilisation du connecteur SQL Aurora pour JDBC
Pour utiliser le connecteur Aurora DSQL pour JDBC dans votre application Java, procédez comme suit :
1. Ajoutez les dépendances suivantes à votre projet Maven :
```
software.amazon.dsql
aurora-dsql-jdbc-connector
1.0.0
```
Pour les projets Gradle, ajoutez cette dépendance :
```
implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
```
1. Créez une connexion de base à votre cluster Aurora DSQL à l'aide du format du connecteur AWS DSQL PostgreSQL :
```
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();
}
}
}
```
### Propriétés de configuration
Le connecteur Aurora DSQL pour JDBC prend en charge les propriétés de connexion suivantes :
user
Détermine l’utilisateur pour la connexion et la méthode de génération de jetons utilisée. Exemple : `admin`
token-duration-secs
Durée de validité du jeton en secondes. Pour plus d’informations sur les limites des jetons, consultez [Génération d’un jeton d’authentification dans Amazon Aurora DSQL](SECTION_authentication-token.md).
profile
Utilisé pour instancier une génération ProfileCredentialsProvider de jetons avec le nom de profil fourni.
region
AWS région pour les connexions SQL Aurora. Elle est facultative. Lorsqu’elle est fournie, elle remplace la région extraite de l’URL.
database
Le nom de la base de données à laquelle se connecter. La valeur par défaut est `postgres`.
### Logging
Activez la journalisation pour résoudre tout problème que vous pourriez rencontrer lors de l’utilisation du connecteur JDBC Aurora DSQL.
Le connecteur utilise le système de journalisation intégré (java.util.logging) de Java. Vous pouvez configurer les niveaux de journalisation en créant un fichier `logging.properties` :
```
# 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
```
### Exemples
Pour des exemples et des cas d'utilisation plus complets, reportez-vous au [connecteur Aurora DSQL pour le référentiel JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)
# Connecteur SQL Aurora pour Python
Le [connecteur SQL Aurora pour Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) intègre l'authentification IAM pour connecter les applications Python aux clusters Amazon Aurora DSQL. [En interne, il utilise les bibliothèques clientes [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) et asyncpg.](https://github.com/MagicStack/asyncpg)
Le connecteur SQL Aurora pour Python est conçu comme un plug-in d'authentification qui étend les fonctionnalités des bibliothèques clientes psycopg, psycopg2 et asyncpg afin de permettre aux applications de s'authentifier auprès d'Amazon Aurora DSQL à l'aide des informations d'identification IAM. Le connecteur ne se connecte pas directement à la base de données mais fournit une authentification IAM fluide en plus des bibliothèques clientes sous-jacentes.
## À propos du connecteur
Amazon Aurora DSQL est un service de base de données SQL distribué qui fournit une disponibilité et une évolutivité élevées aux applications compatibles avec PostgreSQL. Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les bibliothèques Python existantes ne prennent pas en charge de manière native.
L'idée du connecteur Aurora DSQL pour Python est d'ajouter une couche d'authentification au-dessus des bibliothèques clientes psycopg, psycopg2 et asyncpg qui gère la génération de jetons IAM, permettant aux utilisateurs de se connecter à Aurora DSQL sans modifier leurs flux de travail existants.
### Qu’est-ce que l’authentification Aurora DSQL ?
Dans Aurora DSQL, l’authentification implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons :** les jetons d'authentification sont générés à l'aide des informations d'identification AWS et ont une durée de vie configurable
Le connecteur Aurora DSQL pour Python est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Caractéristiques
+ **Authentification IAM automatique** : les jetons IAM sont générés automatiquement à l'aide des informations d'identification AWS
+ **Construit sur psycopg, psycopg2 et asyncpg : exploite les bibliothèques clientes psycopg, psycopg2 et asyncpg**
+ **Intégration fluide** : fonctionne avec les modèles de connexion psycopg, psycopg2 et asyncpg existants sans modification du flux de travail
+ **Découverte automatique des régions** : extrait la région AWS du nom d'hôte du cluster DSQL
+ **Support des informations d'identification AWS** : prend en charge différents fournisseurs d'informations d'identification AWS (par défaut, basé sur le profil, personnalisé)
+ **Compatibilité avec le regroupement de connexions** : fonctionne avec le regroupement de connexions intégré à psycopg, psycopg2 et asyncpg
## Guide de démarrage rapide
### Exigences
+ Python 3.10 ou supérieur
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configuration des autorisations IAM appropriées pour permettre à votre application de se connecter à Aurora DSQL.
+ Informations d'identification AWS configurées (via l'interface de ligne de commande AWS, les variables d'environnement ou les rôles IAM)
### Installation
```
pip install aurora-dsql-python-connector
```
#### Installez psycopg ou psycopg2 ou asyncpg séparément
Le programme d'installation d'Aurora DSQL Connector pour Python n'installe pas les bibliothèques sous-jacentes. Ils doivent être installés séparément, par exemple :
```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```
```
# Install psycopg2
pip install psycopg2-binary
```
```
# Install asyncpg
pip install asyncpg
```
**Remarque :**
Seule la bibliothèque nécessaire doit être installée. Par conséquent, si le client doit utiliser psycopg, seul psycopg doit être installé. Si le client doit utiliser psycopg2, seul psycopg2 doit être installé. Si le client doit utiliser asyncpg, seul asyncpg doit être installé.
Si le client en a besoin de plusieurs, toutes les bibliothèques nécessaires doivent être installées.
### Utilisation de base
#### psycopie
```
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)
```
#### En utilisant uniquement l'hôte
##### psycopie
```
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")
```
#### En utilisant uniquement l'ID du cluster
##### psycopie
```
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")
```
**Remarque :**
Dans le scénario « en utilisant uniquement l'identifiant du cluster », la région précédemment définie sur la machine est utilisée, par exemple :
```
aws configure set region us-east-1
```
Si la région n'a pas été définie ou si l'ID de cluster indiqué se trouve dans une autre région, la connexion échouera. Pour que cela fonctionne, indiquez la région en tant que paramètre, comme dans l'exemple ci-dessous :
##### psycopie
```
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)
```
### Chaîne de connexion
#### psycopie
```
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")
```
### Configuration avancée
#### psycopie
```
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)
```
### Options de configuration
| Option | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| host | string | Oui | Nom d'hôte ou ID de cluster DSQL |
| user | string | Non | Nom d'utilisateur DSQL. Par défaut : admin |
| dbname | string | Non | Nom de la base de données. Par défaut : postgres |
| region | string | Non | Région AWS (détectée automatiquement à partir du nom d'hôte s'il n'est pas fourni) |
| port | int | Non | Par défaut : 5432 |
| custom\$1credentials\$1provider | CredentialProvider | Non | Fournisseur d'informations d'identification AWS personnalisées |
| profile | string | Non | Le nom du profil IAM. Par défaut : par défaut. |
| token\$1duration\$1secs | int | Non | Délai d'expiration du jeton en secondes |
**Toutes les options de connexion standard des bibliothèques psycopg, psycopg2 et asyncpg sous-jacentes sont également prises en charge, à l'exception des paramètres asyncpg **krbsrvname** et gsslib qui ne sont pas pris en charge par DSQL.**
### Utilisation du connecteur SQL Aurora pour Python avec regroupement de connexions
Le connecteur SQL Aurora pour Python fonctionne avec le regroupement de connexions intégré psycopg, psycopg2 et asyncpg. Le connecteur gère la génération de jetons IAM lors de l’établissement de la connexion, ce qui permet aux groupes de connexions de fonctionner normalement.
#### psycopie
Pour psycopg, le connecteur implémente une classe de connexion nommée DSQLConnection qui peut être transmise directement au psycopg\$1pool. ConnectionPool constructeur. Pour les opérations asynchrones, il existe également une version asynchrone de la classe nommée 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
)
```
**Remarque : Configuration max\$1lifetime de la connexion**
Le paramètre max\$1lifetime doit être défini sur moins de 3 600 secondes (une heure), car il s'agit de la durée de connexion maximale autorisée par la base de données Aurora DSQL. La définition d'une valeur max\$1lifetime inférieure permet au pool de connexions de gérer de manière proactive le recyclage des connexions, ce qui est plus efficace que la gestion des erreurs de délai de connexion provenant de la base de données.
#### psycopg2
Pour psycopg2, le connecteur fournit une classe nommée Aurora DSQLThreaded ConnectionPool qui hérite de psycopg2.pool. ThreadedConnectionPool. La DSQLThreaded ConnectionPool classe Aurora remplace uniquement la méthode interne \$1connect. Le reste de l'implémentation est fourni par psycopg2.pool. ThreadedConnectionPool inchangé.
```
import aurora_dsql_psycopg2 as dsql
pool = dsql.AuroraDSQLThreadedConnectionPool(
minconn=2,
maxconn=8,
**conn_params,
)
```
#### asyncpg
Pour asyncpg, le connecteur fournit une fonction create\$1pool qui renvoie une instance de asyncpg.pool.
```
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)
```
## Authentification
Le connecteur gère automatiquement l'authentification DSQL en générant des jetons à l'aide du générateur de jetons du client DSQL. Si la région AWS n'est pas fournie, elle sera automatiquement analysée à partir du nom d'hôte fourni.
Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez le [guide de l'utilisateur](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Administrateur et utilisateurs réguliers
+ Les utilisateurs nommés utilisent `"admin"` automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification non administrateurs
+ Les jetons sont générés dynamiquement pour chaque connexion
## Exemples
Pour un exemple de code complet, reportez-vous aux exemples indiqués dans les sections ci-dessous. Pour savoir comment exécuter les exemples, reportez-vous aux exemples de fichiers READMDE.
### psycopie
[Exemples README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md)
| Description | Exemples |
| --- | --- |
| Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base | [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Utilisation du connecteur Aurora DSQL pour Python pour les connexions asynchrones de base | [Exemple de connexion asynchrone de base](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) |
| Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions | [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Utilisation du connecteur SQL Aurora pour Python avec un pool de connexions asynchrones | [Exemple de connexion de base avec un pool de connexions asynchrones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py) |
### psycopg2
[Exemples README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md)
| Description | Exemples |
| --- | --- |
| Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base | [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
| Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions | [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
### asyncpg
[Exemples README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md)
| Description | Exemples |
| --- | --- |
| Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base | [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
| Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions | [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
# Connexion aux clusters SQL Aurora à l'aide d'un connecteur Go
Le [connecteur SQL Aurora pour Go intègre l'authentification](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) IAM automatique à [pgx](https://github.com/jackc/pgx). Le connecteur gère la génération de jetons, la configuration SSL et la gestion des connexions afin que vous puissiez vous concentrer sur la logique de votre application.
## À propos du connecteur
Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les pilotes Go PostgreSQL existants ne prennent pas en charge de manière native. Le connecteur Aurora DSQL pour Go ajoute une couche d'authentification au-dessus du pilote pgx qui gère la génération de jetons IAM, ce qui vous permet de vous connecter à Aurora DSQL sans modifier vos flux de travail pgx existants.
### Qu’est-ce que l’authentification Aurora DSQL ?
Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable
Le connecteur Aurora DSQL pour Go est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Avantages du connecteur Aurora DSQL pour Go
Le connecteur SQL Aurora pour Go vous permet de continuer à utiliser vos flux de travail pgx existants tout en activant l'authentification IAM via :
+ **Génération automatique de jetons** : le connecteur génère des jetons IAM automatiquement pour chaque connexion
+ **Regroupement de connexions** : prise en charge intégrée `pgxpool` de la génération automatique de jetons par connexion
+ **Configuration flexible** : Support pour des terminaux complets ou des clusters IDs avec détection automatique des régions
+ **AWS Support des identifiants** : prend en charge les AWS profils et les fournisseurs d'identifiants personnalisés
## Fonctions principales
Gestion automatique des jetons
Le connecteur génère automatiquement des jetons IAM pour chaque nouvelle connexion à l'aide d'informations d'identification prérésolues.
Regroupement de connexions
Regroupement des connexions via `pgxpool` génération automatique de jetons par connexion.
Configuration flexible de l'hôte
Prend en charge à la fois les points de terminaison complets du cluster et le cluster IDs avec détection automatique des régions.
Sécurité SSL
Le protocole SSL est toujours activé avec le mode de vérification complète et la négociation directe du protocole TLS.
## Conditions préalables
+ Go 1.24 ou version ultérieure
+ AWS informations d'identification configurées
+ Un cluster SQL Aurora
Le connecteur utilise la chaîne d'informations d'[identification par défaut du AWS SDK for Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), qui résout les informations d'identification dans l'ordre suivant :
1. Variables d'environnement (AWS\$1ACCESS\$1KEY\$1ID, \$1ACCESS\$1KEY) AWS\$1SECRET
1. Fichier d'informations d'identification partagé (\$1/.aws/credentials)
1. Fichier de configuration partagé (\$1/.aws/config)
1. Rôle IAM pour Amazon EC2/ECS/Lambda
## Installation
Installez le connecteur à l'aide des modules Go :
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```
## Démarrage rapide
L'exemple suivant montre comment créer un pool de connexions et exécuter une requête :
```
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)
}
```
## Options de configuration
Le connecteur prend en charge les options de configuration suivantes :
| Champ | Type | Par défaut | Description |
| --- | --- | --- | --- |
| Host (Hôte) | chaîne | (obligatoire) | Point de terminaison ou ID de cluster |
| Région | chaîne | (détecté automatiquement) | AWS région ; obligatoire si l'hôte est un identifiant de cluster |
| Utilisateur | chaîne | « administrateur » | Utilisateur de la base de donnée |
| Base de données | chaîne | « postgres » | Nom de la base de données |
| Port | int | 5432 | Port de la base de données |
| Profil | chaîne | "" | AWS nom de profil pour les informations d'identification |
| TokenDurationSecs | int | 900 (15 minutes) | Durée de validité du jeton en secondes (maximum autorisé : 1 semaine, par défaut : 15 min) |
| MaxConns | int32 | 0 | Nombre maximum de connexions au pool (0 = pgxpool par défaut) |
| MinConns | int32 | 0 | Nombre minimal de connexions au pool (0 = pgxpool par défaut) |
| MaxConnLifetime | Heure. Durée | 55 minutes | Durée de vie maximale de la connexion |
## Format de chaîne de connexion
Le connecteur prend en charge les formats de chaîne de connexion PostgreSQL et DSQL :
```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```
Paramètres de requête pris en charge :
+ `region`- AWS région
+ `profile`- nom du AWS profil
+ `tokenDurationSecs`- Durée de validité du jeton en secondes
Exemples :
```
// 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")
```
## Utilisation avancée
### Configuration de l’hôte
Le connecteur prend en charge deux formats d'hôte :
**Point de terminaison complet** (région détectée automatiquement) :
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
```
**ID du cluster** (région requise) :
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster-id",
Region: "us-east-1",
})
```
### Réglage de la configuration du pool
Configurez le pool de connexions pour votre charge de travail :
```
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,
})
```
### Utilisation d'une connexion unique
Pour les scripts simples ou lorsque le regroupement de connexions n'est pas nécessaire :
```
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")
```
### Utilisation de AWS profils
Spécifiez un AWS profil pour les informations d'identification :
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
Profile: "production",
})
```
## Réessayer OCC
Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.
Le `occretry` package fournit des aides pour une nouvelle tentative automatique avec un recul et une instabilité exponentiels. Installez-le avec :
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```
Utilisation `WithRetry` pour les écritures transactionnelles :
```
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
})
```
Pour les instructions DDL ou uniques, utilisez `ExecWithRetry` :
```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
"CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```
**Important**
`WithRetry`gère`BEGIN`/`COMMIT`/`ROLLBACK`en interne. Votre rappel reçoit une transaction et ne doit contenir que des opérations de base de données et vous pouvez réessayer en toute sécurité.
## Exemples
Pour des exemples et des cas d'utilisation plus complets, reportez-vous aux [exemples d'Aurora DSQL Connector for Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).
| Exemple | Description |
| --- | --- |
| [exemple\$1préféré](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go) | Recommandé : pool de connexions avec requêtes simultanées |
| [transaction](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction) | Gestion des transactions avec BEGIN/COMMIT/ROLLBACK |
| [occ\$1réessayer](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry) | Gérer les conflits OCC avec un recul exponentiel |
| [chaîne\$1connexion](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string) | Utilisation de chaînes de connexion pour la configuration |
# Connecteurs SQL Aurora pour Node.js
Le connecteur Aurora DSQL pour node-postgres et le connecteur Aurora DSQL pour Postgres.js sont des plug-ins d'authentification qui étendent les fonctionnalités des clients node-postgres et Postgres.js afin de permettre aux applications de s'authentifier auprès d'Aurora DSQL à l'aide des informations d'identification IAM.
# Connecteur SQL Aurora pour node-postgres
Le [connecteur Aurora DSQL pour node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) est un connecteur Node.js basé sur [node-postgres](https://node-postgres.com/) qui intègre l'authentification IAM pour connecter des applications aux clusters Amazon Aurora DSQL. JavaScript/TypeScript
Le connecteur Aurora DSQL est conçu comme un plug-in d'authentification qui étend les fonctionnalités du client et du pool de nœuds postgres afin de permettre aux applications de s'authentifier auprès d'Amazon Aurora DSQL à l'aide des informations d'identification IAM.
## À propos du connecteur
Amazon Aurora DSQL est une base de données distribuée native dans le cloud compatible avec PostgreSQL. Bien qu'il nécessite une authentification IAM et des jetons limités dans le temps, les pilotes de base de données Node.js traditionnels ne disposent pas de cette prise en charge intégrée.
Le connecteur SQL Aurora pour node-postgres comble cette lacune en implémentant un intergiciel d'authentification qui fonctionne parfaitement avec node-postgres. Cette approche permet aux développeurs de conserver leur code node-postgres existant tout en obtenant un accès sécurisé basé sur l'IAM aux clusters Aurora DSQL grâce à la gestion automatisée des jetons.
### Qu’est-ce que l’authentification Aurora DSQL ?
Dans Aurora DSQL, l’authentification implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons :** les jetons d'authentification sont générés à l'aide des informations d'identification AWS et ont une durée de vie configurable
Le connecteur Aurora DSQL pour node-postgres est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Caractéristiques
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons DSQL
+ **Construit sur node-postgres** : exploite le célèbre client PostgreSQL pour Node.js
+ **Intégration fluide** - Fonctionne avec les modèles de connexion node-postgres existants
+ **Découverte automatique des régions** : extrait la région AWS du nom d'hôte du cluster DSQL
+ ** TypeScript Support complet** - Assure une sécurité totale du type
+ **Support des informations d'identification AWS** : prend en charge différents fournisseurs d'informations d'identification AWS (par défaut, basé sur le profil, personnalisé)
+ **Compatibilité avec le regroupement de connexions** : fonctionne parfaitement grâce au regroupement de connexions intégré
## Exemple d'application
Un exemple d'application est inclus, [par exemple](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example), qui montre comment utiliser le connecteur Aurora DSQL pour node-postgres. Pour exécuter l'exemple inclus, veuillez vous référer à l'exemple [README.](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)
## Guide de démarrage rapide
### Exigences
+ Node.js 20\$1
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configuration des autorisations IAM appropriées pour permettre à votre application de se connecter à Aurora DSQL.
+ Informations d'identification AWS configurées (via l'interface de ligne de commande AWS, les variables d'environnement ou les rôles IAM)
## Installation
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Dépendances entre pairs
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Usage
### Connexion client
```
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();
```
### Connexion à la piscine
```
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()");
```
### Utilisation avancée
```
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();
```
## Options de configuration
| Option | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| host | string | Oui | Nom d'hôte du cluster SQL |
| username | string | Oui | Nom d'utilisateur DSQL |
| database | string | Non | Nom de la base de données |
| region | string | Non | Région AWS (détectée automatiquement à partir du nom d'hôte s'il n'est pas fourni) |
| port | number | Non | Par défaut : 5432 |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | Non | Fournisseur d'informations d'identification AWS personnalisées |
| profile | string | Non | Le nom du profil IAM. Par défaut, c'est « par défaut » |
| tokenDurationSecs | number | Non | Délai d'expiration du jeton en secondes |
Tous les autres paramètres du [https://node-postgres.com/apis/client](https://node-postgres.com/apis/client) sont pris en charge.
## Authentification
Le connecteur gère automatiquement l'authentification DSQL en générant des jetons à l'aide du générateur de jetons du client DSQL. Si la région AWS n'est pas fournie, elle sera automatiquement analysée à partir du nom d'hôte fourni.
Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez le [guide de l'utilisateur](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Administrateur et utilisateurs réguliers
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Les jetons sont générés dynamiquement pour chaque connexion
# Connecteur SQL Aurora pour Postgres.js
Le [connecteur Aurora DSQL pour Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) est un connecteur Node.js basé sur [Postgres.js](https://github.com/porsager/postgres) qui intègre l'authentification IAM pour connecter des JavaScript applications aux clusters Amazon Aurora DSQL.
Le connecteur Aurora DSQL pour Postgres.js est conçu comme un plug-in d'authentification qui étend les fonctionnalités du client Postgres.js afin de permettre aux applications de s'authentifier auprès d'Amazon Aurora DSQL à l'aide des informations d'identification IAM. Le connecteur ne se connecte pas directement à la base de données, mais fournit une authentification IAM fluide en plus du pilote Postgres.js sous-jacent.
## À propos du connecteur
Amazon Aurora DSQL est un service de base de données SQL distribué qui fournit une disponibilité et une évolutivité élevées aux applications compatibles avec PostgreSQL. Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les pilotes Node.js existants ne prennent pas en charge de manière native.
L'idée du connecteur Aurora DSQL pour Postgres.js est d'ajouter une couche d'authentification au-dessus du client Postgres.js qui gère la génération de jetons IAM, permettant aux utilisateurs de se connecter à Aurora DSQL sans modifier leurs flux de travail Postgres.js existants.
Le connecteur Aurora DSQL pour Postgres.js fonctionne avec la plupart des versions de Postgres.js. Les utilisateurs fournissent leur propre version en installant directement Postgres.js.
### Qu’est-ce que l’authentification Aurora DSQL ?
Dans Aurora DSQL, l’authentification implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons :** les jetons d'authentification sont générés à l'aide des informations d'identification AWS et ont une durée de vie configurable
Le connecteur Aurora DSQL pour Postgres.js est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Caractéristiques
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons DSQL
+ **Construit sur Postgres.js** : exploite le client rapide PostgreSQL pour Node.js
+ **Intégration parfaite** - Fonctionne avec les modèles de connexion Postgres.js existants
+ **Découverte automatique des régions** : extrait la région AWS du nom d'hôte du cluster DSQL
+ ** TypeScript Support complet** - Assure une sécurité totale du type
+ **Support des informations d'identification AWS** : prend en charge différents fournisseurs d'informations d'identification AWS (par défaut, basé sur le profil, personnalisé)
+ **Compatibilité avec le regroupement de connexions** - Fonctionne parfaitement avec le regroupement de connexions intégré à Postgres.js
## Guide de démarrage rapide
### Exigences
+ Node.js 20\$1
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configuration des autorisations IAM appropriées pour permettre à votre application de se connecter à Aurora DSQL.
+ Informations d'identification AWS configurées (via l'interface de ligne de commande AWS, les variables d'environnement ou les rôles IAM)
### Installation
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### Utilisation de base
```
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();
```
#### Utilisation de l'ID du cluster au lieu de l'hôte
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### Chaîne de connexion
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### Configuration avancée
```
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
});
```
## Options de configuration
| Option | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| host | string | Oui | Nom d'hôte ou ID de cluster DSQL |
| database | string? | Non | Nom de la base de données |
| username | string? | Non | Nom d'utilisateur de la base de données (utilise admin s'il n'est pas fourni) |
| region | string? | Non | Région AWS (détectée automatiquement à partir du nom d'hôte s'il n'est pas fourni) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | Non | Fournisseur d'informations d'identification AWS personnalisées |
| tokenDurationSecs | number? | Non | Délai d'expiration du jeton en secondes |
Toutes les [options standard de Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) sont également prises en charge.
## Authentification
Le connecteur gère automatiquement l'authentification DSQL en générant des jetons à l'aide du générateur de jetons du client DSQL. Si la région AWS n'est pas fournie, elle sera automatiquement analysée à partir du nom d'hôte fourni.
Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez le [guide de l'utilisateur](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Administrateur et utilisateurs réguliers
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Les jetons sont générés dynamiquement pour chaque connexion
## Utilisation de l'échantillon
JavaScript des exemples utilisant le connecteur Aurora DSQL pour Postgres.js sont disponibles sur GitHub. Pour obtenir des instructions sur la façon d'exécuter les exemples, reportez-vous au [répertoire des exemples](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example).
| Description | Exemple |
| --- | --- |
| Regroupement de connexions avec requêtes simultanées, y compris la création de tables, les insertions et les lectures entre plusieurs travailleurs | [Exemple de pool de connexions (préféré)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| Opérations CRUD (création de table, insertion, sélection, suppression) sans regroupement de connexions | [Exemple sans pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |
# Connexion aux clusters SQL Aurora à l'aide d'un connecteur Ruby
Le [connecteur Aurora DSQL pour Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) est un connecteur Ruby basé sur [pg](https://github.com/ged/ruby-pg) qui intègre l'authentification IAM pour connecter les applications Ruby aux clusters Amazon Aurora DSQL.
Le connecteur gère la génération de jetons, la configuration SSL et le regroupement des connexions afin que vous puissiez vous concentrer sur la logique de votre application.
## À propos du connecteur
Amazon Aurora DSQL nécessite une authentification IAM avec des jetons à durée limitée que les pilotes Ruby PostgreSQL existants ne prennent pas en charge de manière native. Le connecteur Aurora DSQL pour Ruby ajoute une couche d'authentification au-dessus de la gem pg qui gère la génération de jetons IAM, vous permettant de vous connecter à Aurora DSQL sans modifier vos flux de travail pg existants.
### Qu'est-ce que l'authentification SQL Aurora ?
Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable
Le connecteur Aurora DSQL pour Ruby comprend ces exigences et génère automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Caractéristiques
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons Aurora DSQL
+ **Construit sur pg** - Enveloppe la célèbre gemme PostgreSQL pour Ruby
+ **Intégration parfaite** - Fonctionne avec les flux de travail pg gem existants
+ **Regroupement de connexions** - Support intégré via le `connection_pool` gem avec max\$1lifetime enforcement
+ **Détection automatique des régions** : extrait AWS la région du nom d'hôte du cluster Aurora DSQL
+ **AWS support des identifiants** : prend en charge les AWS profils et les fournisseurs d'identifiants personnalisés
+ **Nouvelle tentative OCC - Optez pour une nouvelle** tentative de contrôle de simultanéité optimiste avec un recul exponentiel
## Exemple d'application
Pour un exemple complet, consultez l'[exemple d'application](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) sur GitHub.
## Guide de démarrage rapide
### Exigences
+ Ruby 3.1 ou version ultérieure
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS informations d'identification configurées (via la AWS CLI, les variables d'environnement ou les rôles IAM)
## Installation
Ajoutez à votre Gemfile :
```
gem "aurora-dsql-ruby-pg"
```
Ou installez directement :
```
gem install aurora-dsql-ruby-pg
```
## Usage
### Connexion à la piscine
```
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
```
### Connexion simple
Pour les scripts simples ou lorsque le regroupement de connexions n'est pas nécessaire :
```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```
### Utilisation avancée
**Configuration de l'hôte**
Le connecteur prend en charge à la fois les points de terminaison complets du cluster (région détectée automatiquement) et le cluster IDs (région requise) :
```
# 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 profils**
Spécifiez un AWS profil pour les informations d'identification :
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
profile: "production"
)
```
**Format de chaîne de connexion**
Le connecteur prend en charge les formats de chaîne de connexion PostgreSQL :
```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```
Paramètres de requête pris en charge :`region`,`profile`,`tokenDurationSecs`.
```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
"postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```
**Réessayer OCC**
Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.
Une nouvelle tentative d'OCC est facultative. Configurez `occ_max_retries` lors de la création du pool pour activer la nouvelle tentative automatique avec un recul et une instabilité exponentiels : `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
```
**Avertissement**
`pool.with`n'intègre PAS automatiquement votre bloc dans une transaction. Vous devez `conn.transaction` vous appeler pour les opérations d'écriture. En cas de conflit OCC, le connecteur réexécute l'intégralité du bloc. Il doit donc contenir uniquement les opérations de base de données et pouvoir réessayer en toute sécurité.
Pour éviter de réessayer un appel individuel, passez `retry_occ: false` :
```
pool.with(retry_occ: false) do |conn|
conn.exec("SELECT 1")
end
```
## Options de configuration
| Champ | Type | Par défaut | Description |
| --- | --- | --- | --- |
| hôte | String | (obligatoire) | Point de terminaison ou ID de cluster |
| Région | String | (détecté automatiquement) | AWS région ; obligatoire si l'hôte est un ID de cluster |
| user | String | « administrateur » | Utilisateur de la base de donnée |
| database | String | « postgres » | Nom de la base de données |
| port | Entier | 5432 | Port de la base de données |
| profile | String | néant | AWS nom de profil pour les informations d'identification |
| durée du jeton | Entier | 900 (15 minutes) | Durée de validité du jeton en secondes (maximum autorisé : 1 semaine, par défaut : 15 min) |
| credentials\$1provider | Aws : :Informations d'identification | néant | Fournisseur d'informations d'identification personnalisées |
| durée de vie maximale | Entier | 300 (55 minutes) | Durée de vie maximale de la connexion en secondes |
| application\$1name | String | néant | Préfixe ORM pour application\$1name |
| bûcheron | Logger | néant | Enregistreur pour les avertissements relatifs aux nouvelles tentatives d'OCC |
| occ\$1max\$1réessais | Entier | nil (désactivé) | Max OCC réessaie pool.with ; permet de réessayer une fois défini |
`create_pool`accepte également un `pool:` mot clé avec un hachage d'options auquel vous passez directement. `ConnectionPool.new` Si vous omettez`pool:`, le connecteur est défini par défaut sur. `{size: 5, timeout: 5}` Les clés que vous fournissez remplacent uniquement ces valeurs par défaut spécifiques.
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
pool: { size: 10, timeout: 10 }
)
```
## Authentification
Le connecteur gère automatiquement l'authentification Aurora DSQL en générant des jetons à l'aide d' AWS informations d'identification. Si vous ne fournissez pas la AWS région, le connecteur l'analyse à partir du nom d'hôte.
Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez[Authentification et autorisation pour Aurora DSQL](authentication-authorization.md).
### Administrateur et utilisateurs réguliers
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Le connecteur génère des jetons de manière dynamique pour chaque connexion
# Connexion aux clusters SQL Aurora à l'aide d'un connecteur .NET
Le [connecteur Amazon Aurora DSQL pour .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) est un connecteur .NET basé sur [Npgsql](https://www.npgsql.org/) qui intègre l'authentification IAM pour connecter les applications .NET aux clusters Amazon Aurora DSQL.
Le connecteur gère la génération de jetons, la configuration SSL et le regroupement des connexions afin que vous puissiez vous concentrer sur la logique de votre application.
## À propos du connecteur
Amazon Aurora DSQL nécessite une authentification IAM avec des jetons à durée limitée que les pilotes .NET PostgreSQL existants ne prennent pas en charge de manière native. Le connecteur Aurora DSQL pour .NET ajoute une couche d'authentification au-dessus de Npgsql qui gère la génération de jetons IAM, vous permettant de vous connecter à Aurora DSQL sans modifier vos flux de travail Npgsql existants.
### Qu'est-ce que l'authentification SQL Aurora ?
Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable
Le connecteur Aurora DSQL pour .NET comprend ces exigences et génère automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.
### Caractéristiques
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons Aurora DSQL
+ **Construit sur Npgsql : intègre** le célèbre pilote PostgreSQL pour .NET
+ **Intégration fluide** - Fonctionne avec les flux de travail Npgsql existants
+ **Regroupement de connexions** - Support intégré via `NpgsqlDataSource` avec application de la durée de vie maximale
+ **Détection automatique des régions** : extrait AWS la région du nom d'hôte du cluster Aurora DSQL
+ **AWS support des identifiants** - Supporte les AWS profils et les fournisseurs d'identifiants personnalisés
+ **Nouvelle tentative OCC - Optez pour une nouvelle** tentative de contrôle de simultanéité optimiste avec un recul exponentiel
+ **Application du protocole SSL** : utilise toujours le protocole SSL avec `verify-full` mode et négociation directe du protocole TLS
## Exemple d'application
Pour un exemple complet, consultez l'[exemple d'application](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) sur GitHub.
## Guide de démarrage rapide
### Exigences
+ .NET 8.0 ou version ultérieure
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS informations d'identification configurées (via la AWS CLI, les variables d'environnement ou les rôles IAM)
## Installation
Ajoutez le package à votre projet :
```
dotnet add package Amazon.AuroraDsql.Npgsql
```
## Usage
### Connexion à la piscine
```
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();
});
```
### Connexion simple
Pour les scripts simples ou lorsque vous n'avez pas besoin d'un regroupement de connexions :
```
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();
```
### Réessayer OCC
Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.
Une nouvelle tentative d'OCC est facultative. Définissez `OccMaxRetries` la configuration pour activer la nouvelle tentative automatique avec un recul et une instabilité exponentiels. Utilisation `WithTransactionRetryAsync` pour les écritures transactionnelles :
```
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();
});
```
Pour les instructions DDL ou uniques, utilisez `ExecWithRetryAsync` :
```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```
**Important**
`WithTransactionRetryAsync`gère`BEGIN`/`COMMIT`/`ROLLBACK`en interne et ouvre une nouvelle connexion à chaque tentative. Votre rappel ne doit contenir que des opérations de base de données et vous pouvez réessayer en toute sécurité.
## Options de configuration
Le connecteur accepte `postgres://` et `postgresql://` connecte également des chaînes avec `region` des paramètres de `profile` requête.
| Champ | Type | Par défaut | Description |
| --- | --- | --- | --- |
| Host | string | (obligatoire) | Point de terminaison du cluster ou ID de cluster à 26 caractères |
| Region | string? | (détecté automatiquement) | AWS région ; obligatoire s'il s'Hostagit d'un ID de cluster |
| User | string | "admin" | Utilisateur de la base de donnée |
| Database | string | "postgres" | Nom de la base de données |
| Port | int | 5432 | Port de la base de données |
| Profile | string? | null | AWS nom de profil pour les informations d'identification |
| CustomCredentialsProvider | AWSCredentials? | null | Fournisseur AWS d'identifiants personnalisés |
| TokenDurationSecs | int? | null(SDK par défaut, 900s) | Durée de validité du jeton en secondes |
| OccMaxRetries | int? | null(handicapé) | Nombre maximal de tentatives OCC par défaut pour les méthodes de nouvelle tentative sur la source de données |
| OrmPrefix | string? | null | préfixe ORM préfixé à application\$1name |
| LoggerFactory | ILoggerFactory? | null | Logger Factory pour les nouvelles tentatives, les avertissements et les diagnostics |
| ConfigureConnectionString | Action? | null | Rappel pour annuler les paramètres du pool ou définir des propriétés de chaîne de connexion Npgsql supplémentaires. Les protocoles SSL Enlist sont des invariants de sécurité et ne peuvent pas être remplacés. |
## Authentification
Le connecteur gère automatiquement l'authentification Aurora DSQL en générant des jetons à l'aide d' AWS informations d'identification. Si vous ne fournissez pas la AWS région, le connecteur l'analyse à partir du nom d'hôte.
Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez[Authentification et autorisation pour Aurora DSQL](authentication-authorization.md).
### Administrateur et utilisateurs réguliers
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Le connecteur génère des jetons de manière dynamique pour chaque connexion.