PostgreSQL Client integration reference

To get started with the Aspire PostgreSQL integrations, follow the Get started with PostgreSQL integrations guide.

This article covers the Aspire PostgreSQL Client integration for .NET applications. It uses the 📦 Aspire.Npgsql NuGet package to connect to and interact with PostgreSQL databases from your .NET consuming projects.

Tip

If you plan to connect to PostgreSQL by using connection information (for example, environment variables or connection strings) directly in your application code, see Connect to PostgreSQL for language-specific examples. Use this guide when you want the Aspire .NET client integration features, such as dependency injection, health checks, and telemetry, via the Aspire.Npgsql package.

Installation

To get started with the Aspire PostgreSQL client integration, install the 📦 Aspire.Npgsql NuGet package in the client-consuming project, that is, the project for the application that uses the PostgreSQL client. The PostgreSQL client integration registers an NpgsqlDataSource instance that you can use to interact with PostgreSQL.

.NET CLI

.NET CLI — Add Aspire.Npgsql package

dotnet add package Aspire.Npgsql

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Npgsql@*

PackageReference (*.csproj)

XML — Add Aspire.Npgsql package reference

<PackageReference Include="Aspire.Npgsql" Version="*" />

Add Npgsql client

In the Program.cs file of your client-consuming project, call the AddNpgsqlDataSource extension method on any IHostApplicationBuilder to register an NpgsqlDataSource for use via the dependency injection container. The method takes a connection name parameter.

C# — Program.cs

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tip

The connectionName parameter must match the name used when adding the PostgreSQL server resource in the AppHost project. For more information, see Add PostgreSQL server resource.

After adding NpgsqlDataSource to the builder, you can get the NpgsqlDataSource instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

C# — ExampleService.cs

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Add keyed Npgsql client

There might be situations where you want to register multiple NpgsqlDataSource instances with different connection names. To register keyed Npgsql clients, call the AddKeyedNpgsqlDataSource method:

C# — Program.cs

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

Then you can retrieve the NpgsqlDataSource instances using dependency injection. For example, to retrieve the connection from an example service:

C# — ExampleService.cs

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Properties of the PostgreSQL resources

For a full reference of PostgreSQL connection properties and environment variables, see Connect to PostgreSQL.

Configuration

The Aspire PostgreSQL integration provides multiple configuration approaches and options to meet the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling the AddNpgsqlDataSource method:

C# — Program.cs

builder.AddNpgsqlDataSource("postgresdb");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

JSON — appsettings.json

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

For more information, see the ConnectionString.

Use configuration providers

The Aspire PostgreSQL integration supports Microsoft.Extensions.Configuration. It loads the NpgsqlSettings from appsettings.json or other configuration files by using the Aspire:Npgsql key. Example appsettings.json that configures some of the options:

The following example shows an appsettings.json file that configures some of the available options:

JSON — appsettings.json

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

For the complete PostgreSQL client integration JSON schema, see Aspire.Npgsql/ConfigurationSchema.json.

Use inline delegates

You can also pass the Action<NpgsqlSettings> configureSettings delegate to set up some or all the options inline, for example to disable health checks:

C# — Program.cs

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Client integration health checks

By default, Aspire client integrations have health checks enabled for all services. Similarly, many Aspire hosting integrations also enable health check endpoints. For more information, see:

• Adds the NpgSqlHealthCheck, which verifies that commands can be successfully executed against the underlying Postgres database.
• Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic

Observability and telemetry

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The Aspire PostgreSQL integration uses the following log categories:

• Npgsql.Connection
• Npgsql.Command
• Npgsql.Transaction
• Npgsql.Copy
• Npgsql.Replication
• Npgsql.Exception

Tracing

The Aspire PostgreSQL integration will emit the following tracing activities using OpenTelemetry:

• Npgsql

Metrics

The Aspire PostgreSQL integration will emit the following metrics using OpenTelemetry:

• Npgsql:
  • ec_Npgsql_bytes_written_per_second
  • ec_Npgsql_bytes_read_per_second
  • ec_Npgsql_commands_per_second
  • ec_Npgsql_total_commands
  • ec_Npgsql_current_commands
  • ec_Npgsql_failed_commands
  • ec_Npgsql_prepared_commands_ratio
  • ec_Npgsql_connection_pools
  • ec_Npgsql_multiplexing_average_commands_per_batch
  • ec_Npgsql_multiplexing_average_write_time_per_batch