Get started with the Azure PostgreSQL integrations

Konten ini belum tersedia dalam bahasa Anda.

Azure Database for PostgreSQL—Flexible Server is a relational database service based on the open-source Postgres database engine. It’s a fully managed database-as-a-service that can handle mission-critical workloads with predictable performance, security, high availability, and dynamic scalability. The Aspire Azure PostgreSQL integration provides a way to connect to existing Azure PostgreSQL databases, or create new instances from .NET with the docker.io/library/postgres container image.

In this introduction, you’ll see how to install and use the Aspire Azure PostgreSQL integrations in a simple configuration. If you already have this knowledge, see Azure PostgreSQL Hosting integration for full reference details.

Set up hosting integration

To begin, install the Aspire Azure PostgreSQL Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure PostgreSQL database instances from your Aspire hosting projects:

aspire add azure-postgresql

Aspire CLI interaktif; pilih hasil pencarian yang sesuai saat diminta:

Select an integration to add:

> azure-postgresql (Aspire.Hosting.Azure.PostgreSQL)
> Other results listed as selectable options...

#:package Aspire.Hosting.Azure.PostgreSQL@*

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

Next, in the AppHost project, create instances of Azure PostgreSQL server and database resources, then pass the database to the consuming client projects:

Select your programming language to get started

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddUvicornApp("api", "./api", "main:app")
                            .WithExternalHttpEndpoints()
                            .WaitFor(postgresdb)
                            .WithReference(postgresdb);

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

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

var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
                 .WithExternalHttpEndpoints()
                 .WaitFor(postgresdb)
                 .WithReference(postgresdb);

builder.Build().Run();

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire Azure PostgreSQL client integration:

dotnet add package Aspire.Azure.Npgsql

#:package Aspire.Azure.Npgsql@*

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

In the Program.cs file of your client-consuming project, call the AddAzureNpgsqlDataSource extension method on any IHostApplicationBuilder to register an NpgsqlDataSource for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb");

To interact with Azure PostgreSQL databases in your Python consuming projects, you need to include a PostgreSQL adapter library. Two popular options are psycopg (synchronous) and asyncpg (asynchronous). You can install either of these libraries using pip. In this article, example code uses psycopg:

pip install psycopg[binary]

Ensure that you import psycopg in code files that interact with the database. You should also import the os module to access environment variables:

import psycopg
import os

To interact with Azure PostgreSQL databases in your JavaScript consuming projects, you need to include a PostgreSQL client library. A popular option is pg. You can install this library using npm:

npm install pg

Ensure that you import pg in code files that interact with the database:

import pg from 'pg';

Use injected Azure PostgreSQL properties

In the AppHost, when you used the WithReference method to pass an Azure PostgreSQL server or database resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called postgresdb becomes POSTGRESDB_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

string hostname = builder.Configuration.GetValue<string>("POSTGRESDB_HOST");
string databaseport = builder.Configuration.GetValue<string>("POSTGRESDB_PORT");
string jdbcconnectionstring = builder.Configuration.GetValue<string>("POSTGRESDB_JDBCCONNECTIONSTRING");
string databasename = builder.Configuration.GetValue<string>("POSTGRESDB_DATABASENAME");

Use the os.getenv() method to obtain these environment variables in consuming projects:

postgres_uri = os.getenv("POSTGRESDB_URI")
postgres_name = os.getenv("POSTGRESDB_DATABASENAME", "db")

Use the process.env object to obtain these environment variables in consuming projects:

const pghost = process.env.POSTGRESDB_HOST;
const pgport = process.env.POSTGRESDB_PORT;
const pgdatabase = process.env.POSTGRESDB_DATABASENAME;
// Note: When using Microsoft Entra ID (default), username and password are not used

Use Azure PostgreSQL resources in client code

Now that you’ve added NpgsqlDataSource to the builder in the consuming project, you can use the Azure PostgreSQL resource to get and store data. Get the NpgsqlDataSource instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource to query the database...
}

Having obtained the data source, you can work with the Azure PostgreSQL database as you would in any other C# application.

Use the information you have obtained about the Azure PostgreSQL resource to connect to the database. Here is an example of how to connect using psycopg:

async with await psycopg.AsyncConnection.connect(postgres_uri, autocommit=True) as conn:
    # Use connection to query the database...

Having obtained the connection, you can work with the Azure PostgreSQL database as you would in any other Python application.

Use the information you have obtained about the Azure PostgreSQL resource to connect to the database. Here is an example of how to connect using pg:

const client = new pg.Client({
  host: pghost,
  database: pgdatabase,
  port: pgport,
  // Note: When using Microsoft Entra ID (default), configure Azure authentication
});

client.connect();

Having obtained the connection, you can work with the Azure PostgreSQL database as you would in any other JavaScript application.

Next steps

Now, that you have an Aspire app with Azure PostgreSQL integrations up and running, you can use the following reference documents to learn how to configure and interact with the Azure PostgreSQL resources:

Understand the Azure PostgreSQL hosting integration Discover how to configure password authentication, run as container, and more.

Understand the Azure PostgreSQL client integration Discover how to configure keyed clients, observability, and more.