다음을 통해 공유

.NET Aspire PostgreSQL 통합

  • 아티클

포함:호스팅 통합 및 Client 통합

PostgreSQL 안정성, 기능 견고성 및 성능에 대한 강력한 명성을 얻은 수년간의 활성 개발을 통해 강력한 오픈 소스 개체 관계형 데이터베이스 시스템입니다. .NET Aspire PostgreSQL 통합은 기존 PostgreSQL 데이터베이스에 연결하거나 docker.io/library/postgres 컨테이너 이미지사용하여 .NET 새 인스턴스를 만드는 방법을 제공합니다.

호스팅 통합

PostgreSQL 호스팅 통합은 PostgreSQLserver를 PostgresServerResource 유형으로 모델링합니다. 이 형식 및 API에 액세스하려면, 📦Aspire를 추가할 수 있는PostgreSQL NuGet 패키지를 앱 호스트 프로젝트의 호스팅에서 선택하세요.

dotnet add package Aspire.Hosting.PostgreSQL

자세한 내용은 dotnet add package 또는 .NET 응용 프로그램에서 패키지 종속성을 관리하기를 참조하십시오.

PostgreSQL server 리소스 추가

앱 호스트 프로젝트에서 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 리소스에는 username"postgres"의 기본 자격 증명이 포함되어 있으며, CreateDefaultPasswordParameter 메서드를 사용하여 임의로 생성된 password가 포함됩니다.

WithReference 메서드는 ExampleProject의 "messaging"로 명명된 연결을 구성합니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

팁

기존 PostgreSQLserver연결하려는 경우 대신 AddConnectionString 호출합니다. 자세한 내용은 기존 리소스를 참조하세요.

PostgreSQL pgAdmin 리소스 추가

AddPostgres 메서드를 사용하여 builder에 PostgreSQL 리소스를 추가할 때, dpage/pgadmin4 컨테이너를 추가하기 위해 WithPgAdmin 호출을 체인하여 연결할 수 있습니다. 이 컨테이너는 웹 기반 관리 대시보드를 제공하는 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 데이터베이스에 대한 웹 기반 관리 대시보드를 제공하는 컨테이너를 추가합니다.

PostgreSQL pgWeb 리소스 추가

AddPostgres 방법으로 builder에 PostgreSQL 리소스를 추가할 때, WithPgWeb의 호출을 연속하여 sosedoff/pgweb 컨테이너를 추가할 수 있습니다. 이 컨테이너는 웹 기반 관리 대시보드를 제공하는 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 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨참조하세요.

데이터 바인드 마운트를 사용하여 PostgreSQLserver 리소스를 추가하십시오.

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 문서: 바인드 마운트를 참조하십시오.

init bind mount을 사용하여 PostgreSQLserver 리소스 추가

init 바인드 마운트를 PostgreSQLserver 리소스에 추가하려면 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 바인드 마운트는 Windows의 C:\PostgreSQL\Init 경로나 Unix의 /PostgreSQL/Init 경로로 호스트 컴퓨터에 있는 PostgreSQLserver 컨테이너에 마운트됩니다.

매개 변수를 사용하여 PostgreSQLserver 리소스 추가

컨테이너 이미지에서 사용하는 사용자 이름 및 암호를 명시적으로 제공하려는 경우 이러한 자격 증명을 매개 변수로 제공할 수 있습니다. 다음 대체 예제를 고려합니다.

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이 실행 중인지와 연결이 설정될 수 있는지를 확인합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.Npgsql NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire PostgreSQL client 통합을 시작하려면 📦Aspire설치합니다. Npgsqlclient사용 프로젝트에서 NuGet 패키지, 즉 PostgreSQLclient사용하는 애플리케이션에 대한 프로젝트입니다. PostgreSQL client 통합은 NpgsqlDataSource 인스턴스를 등록하여 PostgreSQL와 상호 작용하는 데 사용할 수 있습니다.

dotnet add package Aspire.Npgsql

Npgsql client 추가

client을 사용하는 프로젝트의 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 통합 개요참조하세요.

  • NpgSqlHealthCheck을(를) 추가하여, 기본 Postgres 데이터베이스에 대해 명령이 성공적으로 실행될 수 있음을 확인하게 해 줍니다.
  • 등록된 모든 상태 검사가 통과해야만 앱이 트래픽을 수용할 준비가 된 것으로 간주되도록 지정하는 /health HTTP 엔드포인트와의 통합을 수행합니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성핵심 요소라고도 합니다. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.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

Azure PostgreSQL 호스팅 통합

PostgreSQL 리소스를 Azure에 배포하려면 📦Aspire호스팅을 위한Azure.PostgreSQL NuGet 패키지를 설치하십시오:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Azure PostgreSQL server 리소스 추가

.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에 대한 호출은 PostgreSQL server 리소스를 AzurePostgres 유연한 Server로 배포하도록 구성합니다.

중요하다

기본적으로 AddAzurePostgresFlexibleServerMicrosoft Entra ID 인증을 구성합니다. 이렇게 하려면 이러한 리소스에 연결해야 하는 애플리케이션을 변경해야 합니다. 자세한 내용은 Client 통합참조하세요.

Azure로 인증된 Npgsql client 추가

기본적으로 PostgreSQL 호스팅 통합에서 AddAzurePostgresFlexibleServer을 호출하면, 인증을 사용하도록 📦Azure를 구성하여 ID NuGet 패키지가 설정됩니다.

dotnet add package Azure.Identity

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 메서드는 연결 문자열 작성기에서 토큰을 제공하는 데 사용됩니다.

더 보기