Get started with the PostgreSQL integrations

PostgreSQL is a powerful, open source object-relational database system with many years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. The Aspire PostgreSQL integration provides a way to connect to existing PostgreSQL databases, or create new instances from the docker.io/library/postgres container image.

Use this guide to add PostgreSQL to an Aspire solution. Choose the AppHost language for your solution first, then follow the matching quickstart. For the full PostgreSQL hosting API surface in either C# or TypeScript, see PostgreSQL Hosting integration.

Note

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up the PostgreSQL Hosting integration

Choose your AppHost language, then add PostgreSQL to the AppHost. For the full C# and TypeScript hosting API surface, see PostgreSQL Hosting integration.

Select your AppHost language

C# TypeScript

TypeScript AppHost quickstart

Use this path when your Aspire solution is modeled in apphost.ts.

Add the PostgreSQL Hosting integration with the Aspire CLI

Terminal

aspire add postgres

This updates your aspire.config.json with the PostgreSQL hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.PostgreSQL": "*"
  }
}

Model PostgreSQL resources in apphost.ts

apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const postgres = await builder.addPostgres("postgres");
const postgresdb = await postgres.addDatabase("postgresdb");

await builder.addNodeApp("api", "./api", "index.js")
    .withExternalHttpEndpoints()
    .waitFor(postgresdb)
    .withReference(postgresdb);

Tip

For the full TypeScript AppHost PostgreSQL API surface, see PostgreSQL Hosting integration.

Connect from your consuming app

The examples below assume your apphost.ts file references postgresdb from the consuming app with withReference(postgresdb).

JavaScript

Install the PostgreSQL client library in your JavaScript or TypeScript consuming project:

Terminal

npm install pg

Import pg in code files that interact with the database:

JavaScript - Import pg

import pg from 'pg';

Use the process.env object to read the injected PostgreSQL properties:

JavaScript - Obtain configuration properties

const pguser = process.env.POSTGRESDB_USERNAME;
const pgpassword = process.env.POSTGRESDB_PASSWORD;
const pghost = process.env.POSTGRESDB_HOST;
const pgport = process.env.POSTGRESDB_PORT;
const pgdatabase = process.env.POSTGRESDB_DATABASENAME;

Connect to PostgreSQL with pg:

JavaScript - Connect to PostgreSQL

const client = new pg.Client({
    user: pguser,
    host: pghost,
    database: pgdatabase,
    password: pgpassword,
    port: pgport,
});

await client.connect();

Python

Install a PostgreSQL driver in your Python consuming project. This example uses psycopg:

Terminal

pip install psycopg[binary]

Import os and psycopg in code files that interact with the database:

Python - Import psycopg

import os
import psycopg

Use os.getenv() to read the injected PostgreSQL properties:

Python - Obtain configuration properties

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

Connect to PostgreSQL with psycopg:

Python - Connect to PostgreSQL

async with await psycopg.AsyncConnection.connect(postgres_uri, autocommit=True) as conn:

C#

Install the Aspire PostgreSQL client integration in each C# consuming project:

.NET CLI

.NET CLI — Add Aspire.Npgsql package

dotnet add package Aspire.Npgsql

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Npgsql@*

PackageReference (*.csproj)

XML — Add Aspire.Npgsql package reference

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

In Program.cs, call the AddNpgsqlDataSource extension method on an IHostApplicationBuilder to register an NpgsqlDataSource for use via dependency injection:

C# - Program.cs

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tip

The connectionName parameter must match the name used when adding the PostgreSQL database resource in the AppHost project.

Get the NpgsqlDataSource instance by using dependency injection:

C# - ExampleService.cs

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

C# AppHost quickstart

Use this path when your Aspire solution is modeled in AppHost.cs.

Add the PostgreSQL Hosting integration to the AppHost

Terminal

aspire add postgres

Or, add the package manually in either AppHost.cs or AppHost.csproj:

C# - AppHost.cs

#:package Aspire.Hosting.PostgreSQL@*

XML - AppHost.csproj

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

Model PostgreSQL resources in AppHost.cs

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

Tip

For the full C# AppHost PostgreSQL API surface, see PostgreSQL Hosting integration.

Connect from your consuming app

The examples below assume your AppHost.cs file references postgresdb from the consuming app with WithReference(postgresdb).

C#

Install the Aspire PostgreSQL client integration in each C# consuming project:

.NET CLI

.NET CLI — Add Aspire.Npgsql package

dotnet add package Aspire.Npgsql

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Npgsql@*

PackageReference (*.csproj)

XML — Add Aspire.Npgsql package reference

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

In Program.cs, call the AddNpgsqlDataSource extension method on an IHostApplicationBuilder to register an NpgsqlDataSource for use via dependency injection:

C# - Program.cs

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tip

The connectionName parameter must match the name used when adding the PostgreSQL database resource in the AppHost project.

Get the NpgsqlDataSource instance by using dependency injection:

C# - ExampleService.cs

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

Python

Install a PostgreSQL driver in your Python consuming project. This example uses psycopg:

Terminal

pip install psycopg[binary]

Import os and psycopg in code files that interact with the database:

Python - Import psycopg

import os
import psycopg

Use os.getenv() to read the injected PostgreSQL properties:

Python - Obtain configuration properties

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

Connect to PostgreSQL with psycopg:

Python - Connect to PostgreSQL

async with await psycopg.AsyncConnection.connect(postgres_uri, autocommit=True) as conn:

JavaScript

Install the PostgreSQL client library in your JavaScript or TypeScript consuming project:

Terminal

npm install pg

Import pg in code files that interact with the database:

JavaScript - Import pg

import pg from 'pg';

Use the process.env object to read the injected PostgreSQL properties:

JavaScript - Obtain configuration properties

const pguser = process.env.POSTGRESDB_USERNAME;
const pgpassword = process.env.POSTGRESDB_PASSWORD;
const pghost = process.env.POSTGRESDB_HOST;
const pgport = process.env.POSTGRESDB_PORT;
const pgdatabase = process.env.POSTGRESDB_DATABASENAME;

Connect to PostgreSQL with pg:

JavaScript - Connect to PostgreSQL

const client = new pg.Client({
    user: pguser,
    host: pghost,
    database: pgdatabase,
    password: pgpassword,
    port: pgport,
});

await client.connect();

Next steps

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

Understand the PostgreSQL hosting integration Discover how to configure persistence, pgAdmin resources, and more.

Understand the PostgreSQL client integration Discover how to configure keyed clients, client integration health checks, and more.

Understand the PostgreSQL community extensions Discover how to add the DbGate management user interface, and more.