.NET Aspire PostgreSQL 統合

2025-06-11

含まれているもの: ホスティング統合 —および— Client 統合

PostgreSQL は、信頼性、機能の堅牢性、およびパフォーマンスに対する高い評価を得ている、長年にわたるアクティブな開発を行う、強力なオープンソースのオブジェクトリレーショナルデータベースシステムです。 .NET Aspire PostgreSQL 統合により、既存の PostgreSQL データベースに接続したり、.NETを使用して docker.io/library/postgres から新しいインスタンスを作成したりできます。

ホスティング統合

PostgreSQL ホスティング統合は、さまざまな PostgreSQL リソースを次の種類としてモデル化します。

これらの型と API にアクセスして、アプリホストプロジェクト内のリソースとして表現するには、📦Aspire.Hosting の NuGet パッケージPostgreSQL をインストールします。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Hosting.PostgreSQL

<PackageReference Include="Aspire.Hosting.PostgreSQL"
                  Version="*" />

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

PostgreSQLサーバーリソースを追加する

アプリホストプロジェクトで、AddPostgres インスタンスの builder を呼び出して PostgreSQL サーバーリソースを追加し、次の例に示すように、AddDatabase インスタンスで postgres を呼び出してデータベースリソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

.NET .NET Aspire 前の例に示すように、docker.io/library/postgres イメージを使用してコンテナーイメージをアプリホストに追加すると、ローカルコンピューターに新しい PostgreSQL サーバーインスタンスが作成されます。 PostgreSQL サーバーとデータベースインスタンス (postgresdb 変数) への参照を使用して、依存関係をExampleProjectに追加します。

データベースリソースをアプリモデルに追加すると、データベースがまだ存在しない場合は作成されます。データベースの作成は、アプリホストイベント API (特に ResourceReadyEvent) に依存します。つまり、 postgres リソースの準備ができたら、イベントが発生し、データベースリソースが作成されます。

PostgreSQL サーバーリソースには、username の "postgres" として、password メソッドを使用してランダムに生成された CreateDefaultPasswordParameter を含む既定の資格情報が含まれています。

WithReference メソッドは、ExampleProjectという名前の "messaging" で接続を構成します。詳細については、「コンテナーリソースのライフサイクルの」を参照してください。

ヒント

既存の PostgreSQL サーバーに接続する場合は、代わりに AddConnectionString を呼び出します。詳細については、「既存のリソースを参照する」を参照してください。

PostgreSQL リソースをデータベーススクリプトとともに追加する

既定では、 PostgresDatabaseResourceを追加すると、次のスクリプトに依存してデータベースが作成されます。

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

既定のスクリプトを変更するには、データベースリソースビルダーで WithCreationScript メソッドの呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");

var databaseName = "app_db";
var creationScript = $$"""
    -- Create the database
    CREATE DATABASE {{databaseName}};

    """;

var db = postgres.AddDatabase(databaseName)
                 .WithCreationScript(creationScript);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

前の例では、 app_dbという名前のデータベースを作成します。このスクリプトは、データベースリソースの作成時に実行されます。スクリプトは文字列として WithCreationScript メソッドに渡され、 PostgreSQL リソースのコンテキストで実行されます。

注

作成スクリプトを使用する場合、データベースへの接続コマンド (\c) はサポートされていません。

PostgreSQL pgAdminリソースを追加する

PostgreSQL メソッドを使用して builder に AddPostgres リソースを追加する場合は、WithPgAdmin への呼び出しをチェーンして、dpage/pgadmin4 コンテナーを追加できます。このコンテナーは、Web ベースの管理ダッシュボードを提供する、PostgreSQL データベース用のクロスプラットフォームクライアントです。次の例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

上記のコードは、docker.io/dpage/pgadmin4 イメージに基づいてコンテナーを追加します。コンテナーは、PostgreSQL サーバーとデータベースリソースを管理するために使用されます。 WithPgAdmin メソッドは、PostgreSQL データベース用の Web ベースの管理者ダッシュボードを提供するコンテナーを追加します。

pgAdmin ホストポートを構成する

pgAdmin コンテナーのホストポートを構成するには、WithHostPort サーバーリソースで PostgreSQL メソッドを呼び出します。次の例は、pgAdmin コンテナーのホストポートを構成する方法を示しています。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

上記のコードでは、pgAdmin コンテナーのホストポートを追加して構成します。それ以外の場合、ホストポートはランダムに割り当てられます。

pgWeb リソース PostgreSQL 追加する

PostgreSQL メソッドを使用して builder リソースを AddPostgres に追加する場合は、WithPgWeb への呼び出しをチェーンして、sosedoff/pgweb コンテナーを追加できます。このコンテナーは、Web ベースの管理ダッシュボードを提供する、PostgreSQL データベース用のクロスプラットフォームクライアントです。次の例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

上記のコードは、docker.io/sosedoff/pgweb イメージに基づいてコンテナーを追加します。登録されているすべての PostgresDatabaseResource インスタンスは、インスタンスごとに構成ファイルを作成するために使用され、各構成は、pgweb コンテナーブックマークディレクトリにバインドされます。詳細については、PgWeb ドキュメントの Server 接続ブックマークを参照してください。

pgWeb ホストポートを構成する

pgWeb コンテナーのホストポートを構成するには、WithHostPort サーバーリソースで PostgreSQL メソッドを呼び出します。次の例は、pgAdmin コンテナーのホストポートを構成する方法を示しています。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(pgWeb => pgWeb.WithHostPort(5050));

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

上記のコードでは、pgWeb コンテナーのホストポートを追加して構成します。それ以外の場合、ホストポートはランダムに割り当てられます。

データボリュームを持つ PostgreSQL サーバーリソースを追加する

PostgreSQL サーバーリソースにデータボリュームを追加するには、WithDataVolume サーバーリソースで PostgreSQL メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

データボリュームは、コンテナーのライフサイクル外に PostgreSQL サーバーデータを保持するために使用されます。データボリュームは、/var/lib/postgresql/data サーバーコンテナーの PostgreSQL パスにマウントされ、name パラメーターが指定されていない場合は、名前がランダムに生成されます。データボリュームおよび、それがバインドマウントよりも優先される理由についての詳細は、をご覧ください。

重要

.NET Aspire PostgreSQL統合を含む一部のデータベース統合では、Azure Container Apps (ACA) へのデプロイ後にデータボリュームを正常に使用できません。これは、ACA は Server メッセージブロック (SMB) を使用してコンテナーをデータボリュームに接続し、一部のシステムではこの接続を使用できないためです。 Aspire ダッシュボードでは、この問題の影響を受けるデータベースの状態は [アクティブ化] または [アクティブ化に失敗しました] になっていますが、[実行中] と表示されることはありません。

この問題を解決するには、マネージドサービス Azure Database for PostgreSQL を使用して、ACA 内のコンテナーではなくデプロイされたデータベースをホストします。これは、この問題に関係なく推奨される方法です。次のアプリホストコードは、データベースを Azure Database for PostgreSQL にデプロイし、開発中にデータボリュームを含むコンテナーとして実行する方法を示しています。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer(container => 
                      {
                        container.WithDataVolume();
                      });

builder.Build().Run();

PostgreSQL サーバーリソースにデータバインドマウントを追加する

PostgreSQL サーバーリソースにデータバインドマウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

重要

データバインドマウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適したボリュームと比較して機能が制限されています。ただし、バインドマウントを使用すると、ホストシステム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データバインドマウントは、ホストマシンのファイルシステムに依存して、コンテナーの再起動時に PostgreSQL サーバーデータを保持します。データバインドマウントは、C:\PostgreSQL\Data サーバーコンテナー内のホストコンピューター上の Windows 上の /PostgreSQL/Data (または Unix上の PostgreSQL) パスにマウントされます。データバインドマウントの詳細については、「Docker ドキュメント：バインドマウント」を参照してください。

initバインドマウントでPostgreSQLサーバーリソースを追加する

PostgreSQL サーバーリソースに init バインドマウントを追加するには、WithInitBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

init バインドマウントは、ホストコンピューターのファイルシステムに依存して、コンテナー PostgreSQL フォルダーを使用してサーバーデータベースを初期化します。このフォルダーは、postgres-data フォルダーの作成後に、実行可能なシェルスクリプトまたは .sql コマンドファイルを実行する初期化に使用されます。 init バインドマウントは、C:\PostgreSQL\Init サーバーコンテナー内のホストコンピューター上の Windows 上の /PostgreSQL/Init (または Unixの PostgreSQL) パスにマウントされます。

パラメーター付きでサーバーリソース PostgreSQL を追加する

コンテナーイメージで使用されるユーザー名とパスワードを明示的に指定する場合は、これらの資格情報をパラメーターとして指定できます。次の代替例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

パラメーターの指定の詳細については、「外部パラメーターの」を参照してください。

ホスティング統合の正常性チェック

PostgreSQL ホスティング統合により、PostgreSQL サーバーリソースの正常性チェックが自動的に追加されます。正常性チェックでは、PostgreSQL サーバーが実行されていること、およびサーバーへの接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks.Npgsql NuGet パッケージに依存します。

Client 統合

.NET Aspire PostgreSQL クライアント統合を開始するには、クライアントを利用するアプリケーションプロジェクトに、📦AspireNpgsql NuGet パッケージをインストールしてください。このプロジェクトは PostgreSQL クライアントを使用するものです。 PostgreSQL クライアント統合は、との対話に使用できる PostgreSQL インスタンスを登録します。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Npgsql

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

Npgsql クライアントを追加する

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の AddNpgsqlDataSource で IHostApplicationBuilder 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する NpgsqlDataSource を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに PostgreSQL サーバーリソースを追加するときに使用する名前と一致する必要があります。詳細については、「PostgreSQL サーバーリソースを追加」を参照してください。

ビルダーに NpgsqlDataSource を追加した後、依存関係の挿入を使用して NpgsqlDataSource インスタンスを取得できます。たとえば、サンプルサービスからデータソースオブジェクトを取得するには、それをコンストラクターパラメーターとして定義し、ExampleService クラスが依存関係挿入コンテナーに登録されていることを確認します。

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

依存関係の挿入についての詳細は、.NET "依存関係の挿入"を参照してください。

キー付き Npgsql クライアントを追加する

接続名が異なる複数の NpgsqlDataSource インスタンスを登録する場合があります。キー付き Npgsql クライアントを登録するには、AddKeyedNpgsqlDataSource メソッドを呼び出します。

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

その後、依存関係の挿入を使用して NpgsqlDataSource インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

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

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

設定

.NET Aspire PostgreSQL 統合には、プロジェクトの要件と規則を満たす複数の構成アプローチとオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddNpgsqlDataSource メソッドを呼び出すときに接続文字列の名前を指定できます。

builder.AddNpgsqlDataSource("postgresdb");

その後、接続文字列は ConnectionStrings 構成セクションから取得されます。

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

詳細については、ConnectionStringを参照してください。

構成プロバイダーを使用する

.NET Aspire PostgreSQL 統合では、Microsoft.Extensions.Configurationがサポートされます。 NpgsqlSettings キーを使用して、appsettings.json またはその他の構成ファイルから Aspire:Npgsql を読み込みます。いくつかのオプションを構成する appsettings.json の例:

次の例は、使用可能なオプションの一部を構成する appsettings.json ファイルを示しています。

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

完全な PostgreSQL クライアント統合 JSON スキーマについては、Aspireを参照してください。Npgsql/ConfigurationSchema.json.

インラインデリゲートを使用する

また、Action<NpgsqlSettings> configureSettings デリゲートを渡して、一部またはすべてのオプションをインラインで設定することもできます。たとえば、正常性チェックを無効にできます。

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

Client 統合ヘルスチェック

既定では、.NET.NET Aspireクライアント統合すべてのサービスで正常性チェック有効になっています。同様に、多くの .NET.NET Aspireホスティング統合もヘルスチェックエンドポイントを有効にします。詳細については、以下を参照してください。

C#でのアプリ正常性チェック .NET
ASP.NET Core での健康診断チェック

基になる NpgSqlHealthCheck データベースに対してコマンドが正常に実行できることを確認する Postgresを追加します。
/health HTTP エンドポイントと統合します。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱とも呼ばれます。統合の可観測性とテレメトリの詳細については、統合の概要参照してください。バッキングサービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET Aspire PostgreSQL 統合では、次のログカテゴリが使用されます。

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

トレース作業

.NET Aspire PostgreSQL 統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

Npgsql

メトリック

.NET Aspire PostgreSQL 統合では、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