npgsql

Aurora DSQL with Npgsql

Overview

This code example demonstrates how to use Npgsql with Amazon Aurora DSQL. The example shows you how to connect to an Aurora DSQL cluster and perform basic database operations.

Aurora DSQL is a distributed SQL database service that provides high availability and scalability for your PostgreSQL-compatible applications. Npgsql is a popular PostgreSQL adapter for .NET that allows you to interact with PostgreSQL databases using C# code.

About the code example

This example uses the Aurora DSQL Npgsql Connector which automatically handles IAM token generation for authentication.

The preferred example (src/ExamplePreferred.cs) uses AuroraDsql.CreateDataSourceAsync() with automatic token management, connection pooling, and OCC retry.

Alternative approaches are available in src/alternatives/:

• SingleConnection (src/alternatives/SingleConnection/) — Uses AuroraDsql.ConnectAsync() for a single unpooled connection, suitable for scripts or simple use cases.
• ManualToken (src/alternatives/ManualToken/) — Uses the raw Npgsql driver with AWSSDK.DSQL to generate tokens directly, useful for custom authentication flows or finer-grained control.

⚠️ Important

• Running this code might result in charges to your AWS account.
• We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see Grant least privilege.
• This code is not tested in every AWS Region. For more information, see AWS Regional Services.

Run the example

Prerequisites

• You must have an AWS account, and have your default credentials and AWS Region configured as described in the Globally configuring AWS SDKs and tools guide.
• .NET 9.0 SDK or later.
• You must have an Aurora DSQL cluster. For information about creating an Aurora DSQL cluster, see the Getting started with Aurora DSQL guide.
• If connecting as a non-admin user (manual token alternative), ensure the user is linked to an IAM role and is granted access to the myschema schema. See the Using database roles with IAM roles guide.

Run the code

The example demonstrates the following operations:

• Opening a connection pool to an Aurora DSQL cluster
• Creating a table
• Inserting data with transactional writes and OCC retry
• Running concurrent queries using the pool

Note: Running the example will use actual resources in your AWS account and may incur charges.

Set environment variables for your cluster details:

# e.g. "foo0bar1baz2quux3quuux4.dsql.us-east-1.on.aws"
export CLUSTER_ENDPOINT="<your cluster endpoint>"

Run the tests:

dotnet test

To run the manual token alternative (requires additional environment variables):

export REGION="<your cluster region>"
export CLUSTER_USER="<your cluster user>"

dotnet test --filter "ManualTokenExampleTest"

Note: The connector automatically extracts the region from the cluster endpoint and defaults to the postgres database.

Additional resources

• Amazon Aurora DSQL Documentation
• Aurora DSQL Npgsql Connector
• Npgsql Documentation

---

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

SPDX-License-Identifier: MIT-0