Aspire PostgreSQL integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

PostgreSQL är ett kraftfullt objektrelationssystem med öppen källkod med många års aktiv utveckling som har gett det ett starkt rykte för tillförlitlighet, funktions robusthet och prestanda. Med integreringen AspirePostgreSQL kan du ansluta till befintliga PostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Hostingtjänstintegration

PostgreSQL hostingintegrationen modellerar olika PostgreSQL-resurser som olika typer.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Om du vill komma åt dessa typer och API:er för att uttrycka dem som resurser i ditt AppHost-projekt installerar du 📦Aspire. Gästfrihet.PostgreSQL NuGet-paket:

dotnet add package Aspire.Hosting.PostgreSQL

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

Mer information finns i dotnet add package eller i Hantera paketberoenden i .NET-applikationer.

Lägg till PostgreSQL serverresurs

I ditt AppHost-projekt anropar du AddPostgres instansen builder för att lägga till en PostgreSQL serverresurs och anropar AddDatabase sedan instansen postgres för att lägga till en databasresurs enligt följande exempel:

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

När Aspire lägger till en containeravbildning i AppHost, som visas i föregående exempel med docker.io/library/postgres-avbildningen, skapas en ny PostgreSQL-serverinstans på din lokala dator. En referens till servern PostgreSQL och databasinstansen (variabeln postgresdb) används för att lägga till ett beroende till ExampleProject.

När du lägger till en databasresurs i appmodellen skapas databasen om den inte redan finns. Skapandet av databasen förlitar sig på AppHost-händelse-API:erna, särskilt ResourceReadyEvent. Med andra ord, när resursen postgres är klar utlöses händelsen och databasresursen skapas.

PostgreSQL-serverresursen innehåller standardautentiseringsuppgifter med en username av "postgres" och slumpmässigt genererade password med hjälp av metoden CreateDefaultPasswordParameter.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "messaging". Mer information finns i Livscykel för containerresurser.

Lägga till PostgreSQL resurs med databasskript

När du lägger till en PostgresDatabaseResourceförlitar den sig som standard på följande skript för att skapa databasen:

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

Om du vill ändra standardskriptet kedjar du ett anrop till WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, String) metoden i databasresursverktyget:

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

I föregående exempel skapas en databas med namnet app_db. Skriptet körs när databasresursen skapas. Skriptet skickas som en sträng till WithCreationScript metoden, som sedan körs i resursens PostgreSQL kontext.

Lägg till PostgreSQL pgAdmin-resurs

När du lägger till PostgreSQL resurser i builder med metoden AddPostgres kan du länka anrop till WithPgAdmin för att lägga till containern dpage/pgadmin4. Den här containern är en plattformsoberoende klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. Tänk på följande exempel:

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

Den följande koden lägger till en container baserad på docker.io/dpage/pgadmin4-bilden. Containern används för att hantera PostgreSQL server- och databasresurser. Metoden WithPgAdmin lägger till en container som hanterar en webbaserad administratörsinstrumentpanel för PostgreSQL databaser.

Konfigurera värdport för pgAdmin

Om du vill konfigurera värdporten för pgAdmin-containern anropar du metoden WithHostPort på PostgreSQL serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgAdmin-containern. Värdporten tilldelas annars slumpmässigt.

Lägg till PostgreSQL pgWeb-resurs

När du lägger till PostgreSQL resurser i builder med metoden AddPostgres kan du länka anrop till WithPgWeb för att lägga till sosedoff/pgweb container. Den här containern är en plattformsoberoende klient för PostgreSQL databaser som hanterar en webbaserad administratörsinstrumentpanel. Tänk på följande exempel:

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

Den följande koden lägger till en container baserad på docker.io/sosedoff/pgweb-bilden. Alla registrerade PostgresDatabaseResource-instanser används för att skapa en konfigurationsfil per instans. Varje konfiguration är bunden till katalogen för pgweb containerbokmärken. Mer information finns i PgWeb-dokument: Server anslutningsbokmärken.

Konfigurera pgWeb värdport

Om du vill konfigurera värdporten för pgWeb-containern anropar du metoden WithHostPort på PostgreSQL-serverresursen. I följande exempel visas hur du konfigurerar värdporten för pgAdmin-containern:

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

Föregående kod lägger till och konfigurerar värdporten för pgWeb-containern. Värdporten tilldelas annars slumpmässigt.

Lägga till PostgreSQL serverresurs med datavolym

Om du vill lägga till en datavolym i PostgreSQL-serverresursen anropar du metoden WithDataVolume på PostgreSQL serverresursen:

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

Datavolymen används för att bevara PostgreSQL serverdata utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/postgresql/data i servercontainern PostgreSQL och om ingen name-parameter anges genereras namnet slumpvis. Mer information om datavolymer och detaljer om varför de föredras framför bindmountsfinns i Docker dokumentation: Volymer.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Lägg till PostgreSQL serverresurs med databindningspunkt

Om du vill lägga till en databindningsmontering till PostgreSQL-serverresursen anropar du metoden 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...

Monteringar av databindningar förlitar sig på värddatorns filsystem för att bevara serverdata PostgreSQL vid omstarter av containrar. Databindningsmontering monteras på C:\PostgreSQL\Data på Windows (eller /PostgreSQL/Data på Unix) på värddatorn i PostgreSQL-servercontainern. Mer information om databindningspunkter finns i Docker dokumentationen: Bindningspunkter.

Lägg till PostgreSQL server-resurs med init-bindmontering

Om du vill lägga till en init-bindningsmontering till PostgreSQL-serverresursen anropar du metoden 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-bind mounten förlitar sig på värddatorns filssystem för att initiera PostgreSQL-serverdatabasen med init-mappen för containrarna. Den här mappen används för initiering, körning av körbara gränssnittsskript eller .sql kommandofiler efter att mappen postgres-data har skapats. Init-bindningen är monterad på sökvägen C:\PostgreSQL\Init på värddatorn med Windows (eller /PostgreSQL/Init på Unix) i PostgreSQL-servercontainern.

Lägga till PostgreSQL serverresurs med parametrar

När du uttryckligen vill ange användarnamnet och lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

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

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Värdtjänst för integrationshälsokontroller

PostgreSQL värdintegrering lägger automatiskt till en hälsokontroll för PostgreSQL serverresursen. Hälsokontrollen verifierar att PostgreSQL-servern körs och att en anslutning kan upprättas till den.

Integreringen av värdtjänst förlitar sig på 📦 AspNetCore.HealthChecks.Npgsql NuGet-paketet.

Använda med icke-program.NET

Värdintegrering PostgreSQL kan användas med alla programteknik, inte bara .NET program. När du använder WithReference för att referera till en PostgreSQL resurs matas anslutningsinformation automatiskt in som miljövariabler i det refererande programmet.

För program som inte använder klientintegrering kan du komma åt anslutningsinformationen via miljövariabler. Här är ett exempel på hur du konfigurerar miljövariabler för ett icke-program.NET :

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
    .WithLifetime(ContainerLifetime.Persistent);

var database = postgres.AddDatabase("myDatabase");

// Example: Configure a non-.NET application with PostgreSQL access
var app = builder.AddExecutable("my-app", "node", "app.js", ".")
    .WithReference(database) // Provides ConnectionStrings__myDatabase
    .WithEnvironment(context =>
    {
        // Additional individual connection details as environment variables
        context.EnvironmentVariables["POSTGRES_HOST"] = postgres.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["POSTGRES_PORT"] = postgres.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
        context.EnvironmentVariables["POSTGRES_USER"] = postgres.Resource.UserNameParameter;
        context.EnvironmentVariables["POSTGRES_PASSWORD"] = postgres.Resource.PasswordParameter;
        context.EnvironmentVariables["POSTGRES_DATABASE"] = database.Resource.DatabaseName;
    });

builder.Build().Run();

Den här konfigurationen ger icke-programmet.NET flera miljövariabler:

• ConnectionStrings__myDatabase: Den fullständiga PostgreSQL anslutningssträngen
• POSTGRES_HOST: Serverns värdnamn/IP-adress PostgreSQL
• POSTGRES_PORT: Portnumret som PostgreSQL servern lyssnar på
• POSTGRES_USER: Databasens användarnamn
• POSTGRES_PASSWORD: Det dynamiskt genererade lösenordet
• POSTGRES_DATABASE: Namnet på databasen

Ditt icke-program.NET kan sedan läsa dessa miljövariabler för att ansluta till PostgreSQL databasen med hjälp av lämplig databasdrivrutin för den tekniken (till exempel psycopg2 för Python, pg för Node.jseller pq för Go).

Client integrering

Kom igång med AspirePostgreSQL-klientintegrering genom att installera 📦Aspire. Npgsql NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder PostgreSQL-klienten. PostgreSQL-klientintegrering registrerar en NpgsqlDataSource- instans som du kan använda för att interagera med PostgreSQL.

dotnet add package Aspire.Npgsql

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

Lägg till Npgsql-klient

I Program.cs-filen för ditt klientprojekt anropar du AddNpgsqlDataSource-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en NpgsqlDataSource för användning via beroendeinjiceringscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

När du har lagt till NpgsqlDataSource i byggaren kan du hämta NpgsqlDataSource-instansen med hjälp av dependency injection. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nyckelad Npgsql-klient

Det kan finnas situationer där du vill registrera flera NpgsqlDataSource instanser med olika anslutningsnamn. Om du vill registrera nyckelade Npgsql-klienter anropar du metoden AddKeyedNpgsqlDataSource:

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

Sedan kan du hämta NpgsqlDataSource-instans genom dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckeltjänster finns i .NET beroendeinjektion: Nyckeltjänster.

Konfiguration

Den AspirePostgreSQL integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

Aspire PostgreSQL-integreringen stöder Microsoft.Extensions.Configuration. Den läser in NpgsqlSettings från appsettings.json eller andra konfigurationsfiler med hjälp av Aspire:Npgsql-nyckeln. Exempel appsettings.json som konfigurerar några av alternativen:

I följande exempel visas en appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

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

Det fullständiga PostgreSQL klientintegreringsschemat JSON finns i Aspire. Npgsql/ConfigurationSchema.json.

Använd inline-delegater

Du kan också skicka Action<NpgsqlSettings> configureSettings delegering för att konfigurera vissa eller alla alternativ inline, till exempel för att inaktivera hälsokontroller.

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

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET apphälsokontroller i C#
• Hälsokontroller i ASP.NET Core

• Lägger till NpgSqlHealthCheck, som verifierar att kommandon kan köras mot den underliggande Postgres databasen.
• Integrerar med HTTP-slutpunkten /health, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska anses vara redo att ta emot trafik.

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Aspire PostgreSQL-integreringen använder följande loggkategorier:

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

Spårning

Aspire PostgreSQL-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Npgsql

Mätvärden

Integreringen AspirePostgreSQL genererar följande mått med hjälp av 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

Se även

• PostgreSQL dokument
• Aspire Azure PostgreSQL integrering
• Aspire Integrationer
• Aspire GitHub Repo