Connect to PostgreSQL

This page describes how consuming apps connect to a PostgreSQL resource that’s already modeled in your AppHost. For the AppHost API surface — adding a PostgreSQL server, databases, pgAdmin, pgWeb, volumes, and more — see PostgreSQL Hosting integration.

When you reference a PostgreSQL resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the Aspire PostgreSQL client integration for automatic dependency injection, health checks, and telemetry.

Connection properties

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called postgresdb becomes POSTGRESDB_URI.

PostgreSQL server

The PostgreSQL server resource exposes the following connection properties:

Property Name	Description
Host	The hostname or IP address of the PostgreSQL server
Port	The port number the PostgreSQL server is listening on
Username	The username for authentication
Password	The password for authentication
Uri	The connection URI in postgresql:// format, with the format postgresql://{Username}:{Password}@{Host}:{Port}
JdbcConnectionString	JDBC-format connection string, with the format jdbc:postgresql://{Host}:{Port}. User and password credentials are provided as separate Username and Password properties.

Example connection strings:

Uri: postgresql://postgres:p%40ssw0rd1@localhost:5432
JdbcConnectionString: jdbc:postgresql://localhost:5432

PostgreSQL database

The PostgreSQL database resource inherits all properties from its parent server resource and adds:

Property Name	Description
Uri	The connection URI with the database name, with the format postgresql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}
JdbcConnectionString	JDBC connection string with database name, with the format jdbc:postgresql://{Host}:{Port}/{DatabaseName}. User and password credentials are provided as separate Username and Password properties.
DatabaseName	The name of the database

Example connection strings:

Uri: postgresql://postgres:p%40ssw0rd1@localhost:5432/catalog
JdbcConnectionString: jdbc:postgresql://localhost:5432/catalog

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds a PostgreSQL database resource named postgresdb and references it from the consuming app.

C#

For C# apps, the recommended approach is the Aspire PostgreSQL client integration. It registers an NpgsqlDataSource through dependency injection and adds health checks and telemetry automatically. If you’d rather read environment variables directly, see the Read environment variables section at the end of this tab.

Install the client integration

Install the 📦 Aspire.Npgsql NuGet package in the client-consuming project:

.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 the Npgsql data source

In Program.cs, call AddNpgsqlDataSource on your IHostApplicationBuilder to register an NpgsqlDataSource. The connectionName must match the PostgreSQL database resource name from the AppHost:

C# — Program.cs

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Resolve the data source through dependency injection:

C# — ExampleService.cs

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

Add keyed Npgsql clients

To register multiple NpgsqlDataSource instances with different connection names, use AddKeyedNpgsqlDataSource:

C# — Program.cs

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

Then resolve each instance by key:

C# — ExampleService.cs

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

Configuration

The Aspire PostgreSQL client integration offers multiple ways to provide configuration.

Connection strings. When using a connection string from the ConnectionStrings configuration section, pass the connection name to AddNpgsqlDataSource:

C# — Program.cs

builder.AddNpgsqlDataSource("postgresdb");

The connection string is resolved from the ConnectionStrings section:

JSON — appsettings.json

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

For more information, see Npgsql connection string parameters.

Configuration providers. The client integration supports Microsoft.Extensions.Configuration. It loads NpgsqlSettings from appsettings.json (or any other configuration source) by using the Aspire:Npgsql key:

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.

Inline delegates. Pass an Action<NpgsqlSettings> to configure settings inline, for example to disable health checks:

C# — Program.cs

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

Client integration health checks

Aspire client integrations enable health checks by default. The PostgreSQL client integration adds:

• The NpgSqlHealthCheck, which verifies that commands can be successfully executed against the underlying PostgreSQL database.
• Integration with the /health HTTP endpoint, where all registered health checks must pass before the app is considered ready to accept traffic.

Observability and telemetry

The Aspire PostgreSQL client integration automatically configures logging, tracing, and metrics through OpenTelemetry.

Logging categories:

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

Tracing activities:

• Npgsql

Metrics:

• 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

Any of these telemetry features can be disabled through the configuration options above.

Read environment variables in C#

If you prefer to read environment variables directly without the client integration:

C# — Program.cs

var connectionString = Environment.GetEnvironmentVariable(
    "POSTGRESDB_URI");

await using var dataSource = NpgsqlDataSource.Create(connectionString!);
await using var conn = await dataSource.OpenConnectionAsync();

Go

Use the pgx driver, the most actively maintained PostgreSQL driver for Go:

Terminal

go get github.com/jackc/pgx/v5

Note

lib/pq is another popular Go PostgreSQL driver, but pgx is recommended for new projects because it offers better performance, native PostgreSQL protocol support, and active maintenance.

Read the injected environment variable and connect:

Go — main.go

package main

import (
    "context"
    "os"
    "github.com/jackc/pgx/v5"
)

func main() {
    // Read the Aspire-injected connection URI
    connStr := os.Getenv("POSTGRESDB_URI")

    conn, err := pgx.Connect(context.Background(), connStr)
    if err != nil {
        panic(err)
    }
    defer conn.Close(context.Background())
}

Python

Install a PostgreSQL driver. This example uses psycopg:

Terminal

pip install psycopg[binary]

Read the injected environment variable and connect:

Python — app.py

import os
import psycopg

# Read the Aspire-injected connection URI
postgres_uri = os.getenv("POSTGRESDB_URI")

async with await psycopg.AsyncConnection.connect(
    postgres_uri, autocommit=True
) as conn:
    # Use conn to query the database...
    pass

TypeScript

Install the PostgreSQL client library:

Terminal

npm install pg

Read the injected environment variables and connect:

JavaScript — index.js

import pg from 'pg';

// Read Aspire-injected connection properties
const client = new pg.Client({
    user: process.env.POSTGRESDB_USERNAME,
    host: process.env.POSTGRESDB_HOST,
    database: process.env.POSTGRESDB_DATABASENAME,
    password: process.env.POSTGRESDB_PASSWORD,
    port: process.env.POSTGRESDB_PORT,
});

await client.connect();

Or use the connection URI directly:

JavaScript — Connect with URI

const client = new pg.Client({
    connectionString: process.env.POSTGRESDB_URI,
});

await client.connect();

Tip

If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost. See Pass custom environment variables in the Hosting integration reference.