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.

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.

dotnet add package Aspire.Npgsql

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.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

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:

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:

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:

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:

builder.AddNpgsqlDataSource("postgresdb");

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

{
  "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:

{
  "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:

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