.NET Aspire PostgreSQL 統合

[アーティクル]
12/12/2024

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

ホスティング統合

PostgreSQL ホスティング統合は、PostgresServerResource の種類として PostgreSQLserver をモデル化します。この型と、それに追加するための API へアクセスするには、📦Aspireのホスティング、アプリホストプロジェクトで NuGet パッケージPostgreSQL を利用します。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

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

リソース PostgreSQLserver 追加する

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

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 イメージでコンテナーイメージをアプリホストに追加すると、ローカルコンピューターに新しい PostgreSQLserver インスタンスが作成されます。 PostgreSQL server と PostgreSQL データベースインスタンス (postgresdb 変数) への参照を使用して、ExampleProjectに依存関係を追加します。 PostgreSQL server リソースには、CreateDefaultPasswordParameter メソッドを使用して、"postgres" とランダムに生成された password の username を持つ既定の資格情報が含まれています。

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

ヒント

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

PostgreSQL pgAdminリソースを追加する

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

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 イメージに基づいてコンテナーを追加します。コンテナーは、PostgreSQLserver リソースとデータベースリソースを管理するために使用されます。 WithPgAdmin メソッドは、PostgreSQL データベース用の Web ベースの管理者ダッシュボードを提供するコンテナーを追加します。

pgWeb リソース PostgreSQL 追加する

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

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 接続ブックマークを参照してください。

データボリューム PostgreSQLserver リソースを追加する

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

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...

データボリュームは、コンテナーのライフサイクル外に PostgreSQLserver データを保持するために使用されます。データボリュームは、PostgreSQLserver コンテナー内の /var/lib/postgresql/data パスにマウントされ、name パラメーターが指定されていない場合は、名前がランダムに生成されます。データボリュームの詳細と、マウントのバインド優先される理由の詳細については、「ドキュメント: ボリューム」を参照してください。

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

PostgreSQL server リソースにデータバインドマウントを追加するには、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...

重要

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

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

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

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

PostgreSQL server リソースをパラメーターと共に追加する

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

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 ホスティング統合により、PostgreSQLserver リソースの正常性チェックが自動的に追加されます。正常性チェックでは、PostgreSQLserver が実行されていることと、PostgreSQLserver への接続を確立できることを確認します。

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

Client 統合

.NET Aspire PostgreSQL client 統合を開始するには、📦Aspireをインストールします。Npgsql、clientを使用するプロジェクト、つまり、PostgreSQLclientを使用するアプリケーションのプロジェクト内の NuGet パッケージです。 PostgreSQL client 統合では、PostgreSQLとの対話に使用できる NpgsqlDataSource インスタンスが登録されます。

.NET コマンドラインインターフェース
PackageReference

dotnet add package Aspire.Npgsql

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

Npgsql client を追加する

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

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

ヒント

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

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

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

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

キー付き Npgsql client を追加する

接続名が異なる複数の 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がサポートされます。 Aspire:Npgsql キーを使用して、appsettings.json またはその他の構成ファイルから NpgsqlSettings を読み込みます。いくつかのオプションを構成する appsettings.json の例:

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

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

完全な PostgreSQLclient 統合 JSON スキーマについては、Aspireを参照してください。Npgsql/ConfigurationSchema。json.

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

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

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

健康診断

既定では、.NET.NET Aspire 統合により、すべてのサービス正常性チェックが有効になります。詳細については、.NET.NET Aspire 統合の概要を参照してください。

基になる Postgres Database に対してコマンドが正常に実行できることを確認する NpgSqlHealthCheckを追加します。
/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

ホスティング統合の AzurePostgreSQL

Azureに PostgreSQL リソースをデプロイするには、📦Aspire.Hosting.Azure.NuGet パッケージPostgreSQL をインストールします。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

リソース AzurePostgreSQLserver 追加する

.NET Aspire Azure PostgreSQL ホスティング統合をインストールしたら、アプリホストプロジェクトで AddAzurePostgresFlexibleServer 拡張メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

上記の AddAzurePostgresFlexibleServer の呼び出しでは、PostgresSQL server リソースを AzurePostgres フレキシブル Serverとしてデプロイするように構成します。

大事な

既定では、AddAzurePostgresFlexibleServer はの Microsoft Entra ID 認証を構成します。これには、これらのリソースに接続する必要があるアプリケーションを変更する必要があります。詳細については、Client 統合を参照してください。

Azure 認証された Npgsql client を追加する

既定では、PostgreSQL のホスティング統合で AddAzurePostgresFlexibleServer を呼び出すと、📦Azureを構成します。そして、認証を有効にするための NuGet パッケージが設定されます。

.NET CLI
PackageReference

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

PostgreSQL 接続は、client 統合と Azure.Identityを使用して使用できます。

builder.AddNpgsqlDataSource(
    "postgresdb", 
    configureDataSourceBuilder: (dataSourceBuilder) =>
{
    if (!string.IsNullOrEmpty(dataSourceBuilder.ConnectionStringBuilder.Password))
    {
        return;
    }

    dataSourceBuilder.UsePeriodicPasswordProvider(async (_, ct) =>
    {
        var credentials = new DefaultAzureCredential();
        var token = await credentials.GetTokenAsync(
            new TokenRequestContext([
                "https://ossrdbms-aad.database.windows.net/.default"
            ]), ct);

        return token.Token;
    },
    TimeSpan.FromHours(24),
    TimeSpan.FromSeconds(10));
});

上記のコードスニペットは、Azure.Identity パッケージの DefaultAzureCredential クラスを使用して、Microsoft Entra ID で認証し、PostgreSQL データベースに接続するトークンを取得する方法を示しています。 UsePeriodicPasswordProvider メソッドを使用して、接続文字列ビルダーにトークンを提供します。

次の方法で共有

.NET Aspire PostgreSQL 統合

ホスティング統合

リソース PostgreSQLserver 追加する

PostgreSQL pgAdminリソースを追加する

pgWeb リソース PostgreSQL 追加する

データボリューム PostgreSQLserver リソースを追加する

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

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

PostgreSQL server リソースをパラメーターと共に追加する

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

Client 統合

Npgsql client を追加する

キー付き Npgsql client を追加する

構成

接続文字列を使用する

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

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

健康診断

可観測性とテレメトリ

伐採

トレース

メトリック

ホスティング統合の AzurePostgreSQL

リソース AzurePostgreSQLserver 追加する

Azure 認証された Npgsql client を追加する

関連項目

その他のリソース

次の方法で共有

.NET Aspire PostgreSQL 統合

ホスティング統合

リソース PostgreSQLserver 追加する

PostgreSQL pgAdminリソースを追加する

pgWeb リソース PostgreSQL 追加する

データ ボリューム PostgreSQLserver リソースを追加する

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

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

PostgreSQL server リソースをパラメーターと共に追加する

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

Client 統合

Npgsql client を追加する

キー付き Npgsql client を追加する

構成

接続文字列を使用する

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

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

健康診断

可観測性とテレメトリ

伐採

トレース

メトリック

ホスティング統合の AzurePostgreSQL

リソース AzurePostgreSQLserver 追加する

Azure 認証された Npgsql client を追加する

関連項目

その他のリソース

データボリューム PostgreSQLserver リソースを追加する

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

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