Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Aurora DSQL Connector for .NET Npgsql

The Aurora DSQL Connector for .NET is a .NET connector built on Npgsql that integrates IAM authentication for connecting .NET applications to Amazon Aurora DSQL clusters.

The connector handles token generation, SSL configuration, and connection pooling so you can focus on your application logic.

About the connector

Amazon Aurora DSQL requires IAM authentication with time-limited tokens that existing .NET PostgreSQL drivers do not natively support. The Aurora DSQL Connector for .NET adds an authentication layer on top of Npgsql that handles IAM token generation, allowing you to connect to Aurora DSQL without changing your existing Npgsql workflows.

What is Aurora DSQL authentication?

In Aurora DSQL, authentication involves:

The Aurora DSQL Connector for .NET understands these requirements and automatically generates IAM authentication tokens when establishing connections.

Features

Example application

For a complete example, see the example application on GitHub.

Quick start guide

Requirements

Installation

Add the package to your project:

dotnet add package Amazon.AuroraDsql.Npgsql

Usage

Pool connection

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();
});

Single connection

For simple scripts or when you do not need connection pooling:

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 retry

Aurora DSQL uses optimistic concurrency control (OCC). When two transactions modify the same data, the first to commit wins and the second receives an OCC error.

OCC retry is opt-in. Set OccMaxRetries in the config to enable automatic retry with exponential backoff and jitter. Use WithTransactionRetryAsync for transactional writes:

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();
});

For DDL or single statements, use ExecWithRetryAsync:

await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");

Configuration options

The connector also accepts postgres:// and postgresql:// connection strings with region and profile query parameters.

Authentication

The connector automatically handles Aurora DSQL authentication by generating tokens using AWS credentials. If you do not provide the AWS region, the connector parses it from the hostname.

For more information on authentication in Aurora DSQL, see Authentication and authorization for Aurora DSQL.

Admin vs regular users