.NET Aspire PostgreSQL 통합

아티클
01/31/2025

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

호스팅 통합

PostgreSQL 호스팅 통합은 다양한 PostgreSQL 리소스를 다음과 같은 형식으로 모델화합니다.

이 형식과 API를 앱 호스트 프로젝트에서 리소스로 표현하기 위해 액세스하려면, 📦Aspire호스팅.PostgreSQL NuGet 패키지를 설치하십시오.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

자세한 내용은 dotnet add package 또는 .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 서버 및 PostgreSQL 데이터베이스 인스턴스(postgresdb 변수)에 대한 참조는 ExampleProject종속성을 추가하는 데 사용됩니다. PostgreSQL 서버 리소스에는 username이 "postgres"인 기본 자격 증명이 포함되어 있으며 password이 CreateDefaultPasswordParameter 메서드를 사용하여 임의로 생성됩니다.

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

팁

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

PostgreSQL pgAdmin 리소스 추가

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

pgAdmin 호스트 포트 구성

pgAdmin 컨테이너에 대한 호스트 포트를 구성하려면 PostgreSQL 서버 리소스에서 WithHostPort 메서드를 호출합니다. 다음 예제에서는 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 컨테이너에 대한 호스트 포트를 추가하고 구성합니다. 그렇지 않으면 호스트 포트가 임의로 할당됩니다.

PostgreSQL pgWeb 리소스 추가

PostgreSQL 방법으로 builder에 AddPostgres 리소스를 추가할 때, WithPgWeb의 호출을 연속하여 sosedoff/pgweb 컨테이너를 추가할 수 있습니다. 이 컨테이너는 웹 기반 관리 대시보드를 제공하는 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 컨테이너에 대한 호스트 포트를 구성하려면 PostgreSQL 서버 리소스에서 WithHostPort 메서드를 호출합니다. 다음 예제에서는 pgAdmin 컨테이너에 대한 호스트 포트를 구성하는 방법을 보여줍니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(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 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨참조하세요.

데이터 바인드 마운트를 사용하여 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 bind mount을 사용하여 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 클라이언트 통합을 시작하려면 📦Aspire설치합니다. Npgsql은 클라이언트 사용 프로젝트에서 NuGet 패키지를, 즉 PostgreSQL 클라이언트를 사용하는 애플리케이션에 대한 프로젝트입니다. PostgreSQL 클라이언트 통합은 과 상호 작용할 수 있는 PostgreSQL 인스턴스를 등록합니다.

.NET CLI
PackageReference

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);

건강 검진

기본적으로 .NET.NET Aspire 통합은 모든 서비스에 대해 상태 점검이 가능하도록 합니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.

기본 Postgres 데이터베이스에 대해 명령이 성공적으로 실행될 수 있음을 확인하는 NpgSqlHealthCheck추가합니다.
등록된 모든 상태 검사가 통과해야만 앱이 트래픽을 수용할 준비가 된 것으로 간주되도록 지정하는 /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

다음을 통해 공유