Aspire.Hosting.PostgreSQL 13.6.4

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Aspire.Hosting.PostgreSQL --version 13.6.4
                    


                    

                
NuGet\Install-Package Aspire.Hosting.PostgreSQL -Version 13.6.4
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Aspire.Hosting.PostgreSQL" Version="13.6.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="13.6.4" />
                    


                            Directory.Packages.props
                        

                    

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


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Aspire.Hosting.PostgreSQL --version 13.6.4
                    


                    

                
#r "nuget: Aspire.Hosting.PostgreSQL, 13.6.4"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Aspire.Hosting.PostgreSQL@13.6.4
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Aspire.Hosting.PostgreSQL&version=13.6.4
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Aspire.Hosting.PostgreSQL&version=13.6.4
                    


                            Install as a Cake Tool

PostgreSQL hosting integration

Use this integration to model, configure, and orchestrate a PostgreSQL resource in an Aspire solution.

Getting started

Add the integration

From your AppHost directory, add the Aspire.Hosting.PostgreSQL integration with the Aspire CLI:

aspire add Aspire.Hosting.PostgreSQL

Usage example

In the AppHost, add a PostgreSQL resource and reference it from another resource with either C# or TypeScript:

C#

var db = builder.AddPostgres("pgsql").AddDatabase("mydb");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(db);

TypeScript

const db = await builder.addPostgres("pgsql").addDatabase("mydb");

const myService = await builder.addNodeApp("myService", "../my-service", "server.js")
                       .withReference(db);

REPL

Call WithRepl() to opt into a REPL command on the PostgreSQL server resource in the dashboard:

builder.AddPostgres("postgres").WithRepl();

await builder.addPostgres("postgres").withRepl();

REPL access is disabled by default and is available only in run mode. Enable it only for trusted dashboard users: the shell uses the resource's configured credentials and is not read-only. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to users who can execute resource commands.

Use \q before closing the terminal tab to end the session cleanly. Closing the tab alone can leave psql running inside the container. Stopping the container also ends any remaining REPL processes.

When the container is running, this opens psql in the terminal dock, connected to the postgres database with the resource's configured credentials. Use \connect to switch databases and \q to exit. The session runs inside the container using Docker (or the configured Podman runtime); no local PostgreSQL client is required. Passwords are passed through environment variables, not command-line arguments.

Connection Properties

When you reference a PostgreSQL resource using WithReference, the following connection properties are made available to the consuming project:

PostgreSQL server

The PostgreSQL server resource exposes the following connection properties:

Property Name Description
Host The hostname or IP address of the PostgreSQL server
Port The port number the PostgreSQL server is listening on
Username The username for authentication
Password The password for authentication
Uri The connection URI in postgresql:// format, with the format postgresql://{Username}:{Password}@{Host}:{Port}
JdbcConnectionString JDBC-format connection string, with the format jdbc:postgresql://{Host}:{Port}. User and password credentials are provided as separate Username and Password properties.

PostgreSQL database

The PostgreSQL database resource inherits all properties from its parent PostgresServerResource and adds:

Property Name Description
Uri The connection URI with the database name, with the format postgresql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}
JdbcConnectionString JDBC connection string with database name, with the format jdbc:postgresql://{Host}:{Port}/{DatabaseName}. User and password credentials are provided as separate Username and Password properties.
DatabaseName The name of the database

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

Data volumes and bind mounts

Use WithDataVolume (or WithDataBindMount) to persist database data across restarts:

var db = builder.AddPostgres("pgsql")
                .WithDataVolume();

The data directory mounted into the container depends on the PostgreSQL version of the configured container image, which Aspire selects automatically:

PostgreSQL version Container data directory
17 and earlier /var/lib/postgresql/data
18 and later /var/lib/postgresql

Keeping an existing data volume working (PostgreSQL 18 upgrade)

PostgreSQL 18 changed the on-disk data layout: the official image now expects the data directory at /var/lib/postgresql and stores cluster files in a major-version-specific subdirectory (see docker-library/postgres#1259 and docker-library/postgres#37). Because Aspire 13.4 upgraded the default PostgreSQL image to 18, a data volume that was created by an earlier Aspire version (PostgreSQL 17) is not compatible and the container fails to start with an error such as:

Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" ...
       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql

PostgreSQL does not upgrade data files between major versions automatically. Choose one of the following.

Option 1 — Stay on PostgreSQL 17 (no migration, recommended)

Pin the container image back to a PostgreSQL 17 tag. Your existing data volume keeps working unchanged, and Aspire automatically selects the matching data directory (/var/lib/postgresql/data) for version 17.

var db = builder.AddPostgres("pgsql")
                .WithImageTag("17.6")
                .WithDataVolume();

Call WithImageTag (or WithImage) before WithDataVolume. Aspire picks the data directory from the configured image tag at the time WithDataVolume is called, so the tag must be set first.

Option 2 — Upgrade the data volume to PostgreSQL 18

To move to PostgreSQL 18, upgrade your existing cluster by following the official PostgreSQL upgrading documentation (for example, using pg_dumpall/restore or pg_upgrade), then run with the default (18+) image.

If the data is disposable (for example, it is re-seeded on startup), you can instead start fresh by removing the old volume and letting Aspire create a new PostgreSQL 18 volume:

# Find the volume (Aspire names it "{appname}-{hash}-{resourceName}-data")
docker volume ls

# Stop your app first, then list any containers still referencing the volume
# (docker volume rm fails while the volume is in use).
docker ps -a --filter volume=<old-volume-name>

# Remove each referencing container, then remove the volume so Aspire creates
# a fresh PostgreSQL 18 volume on the next run.
docker rm -f <container-id>
docker volume rm <old-volume-name>

Back up your data volume before performing any migration.

MCP (Model Context Protocol) Support

The PostgreSQL hosting integration provides support for adding an MCP sidecar container that enables AI agents to interact with PostgreSQL databases. This is enabled by calling WithPostgresMcp() on a PostgreSQL database resource.

var db = builder.AddPostgres("pg")
                .AddDatabase("mydb")
                .WithPostgresMcp();

The PostgreSQL MCP server is currently powered by Postgres MCP Pro) and provides tools for database exploration, query execution, index tuning, and health checks.

Additional documentation

https://aspire.dev/integrations/gallery/ https://aspire.dev/integrations/databases/postgres/postgres-host/

Feedback & contributing

https://github.com/microsoft/aspire

*Postgres, PostgreSQL and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada, and used with their permission.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (47)

Showing the top 5 NuGet packages that depend on Aspire.Hosting.PostgreSQL:

Package Downloads
Aspire.Hosting.Azure.PostgreSQL

Azure PostgreSql Flexible Server resource types for Aspire.
CommunityToolkit.Aspire.Hosting.PostgreSQL.Extensions

An Aspire hosting integration for extending PostgreSQL resources with additional management tooling.
CommunityToolkit.Aspire.Hosting.Keycloak.Extensions

Aspire hosting extensions for Keycloak (includes PostgreSQL integration).
MMCA.Common.Aspire.Hosting

MMCA framework: Aspire AppHost extension methods for the cross-cutting infrastructure (RabbitMQ broker, JWKS service discovery, gRPC project wiring) used by extracted microservice deployments
Nextended.Aspire.Hosting.Supabase

This Library provides an Aspire Supabase solution

GitHub repositories (37)

Showing the top 20 popular GitHub repositories that depend on Aspire.Hosting.PostgreSQL:

Repository Stars
dotnet/eShop
A reference .NET application implementing an eCommerce site
fullstackhero/dotnet-starter-kit
Production Grade Cloud-Ready .NET 10 Starter Kit (Web API + React Client) with Multitenancy Support, and Clean/Modular Architecture that saves roughly 200+ Development Hours! All Batteries Included.
ChilliCream/graphql-platform
Welcome to the home of the Hot Chocolate GraphQL server for .NET, the Strawberry Shake GraphQL client for .NET and Nitro the awesome Monaco based GraphQL IDE.
Nethereum/Nethereum
Ethereum .Net cross platform integration library
cmu-sei/GHOSTS
GHOSTS (General Human-Oriented Synthetic Teammates and Systems) is a realistic user simulation framework for cyber experimentation, simulation, training, and exercise
evangelosvlachos96-dotcom/booking-microservices
Flight booking system built as .NET 10 microservices with Vertical Slice Architecture, DDD, CQRS, Event Sourcing, gRPC, RabbitMQ, Wolverine, PostgreSQL, MongoDB and .NET Aspire.
NikiforovAll/keycloak-authorization-services-dotnet
Authentication and Authorization with Keycloak and ASP.NET Core 🔐
CommunityToolkit/Aspire
A community project with additional components and extensions for Aspire
meysamhadeli/booking-modular-monolith
A practical Modular Monolith architecture with the latest technologies and architecture like Vertical Slice Architecture, Event Driven Architecture, CQRS, DDD, gRpc, Wolverine, and Aspire in .Net 10.
OpenCoreMMO/OpenCoreMMO
Modern MMORPG server emulator written in C#
mehmetozkaya/Design-Microservices-Architecture-with-Patterns-Principles
Design Microservices Architecture with Patterns & Principles. Design Microservices Architecture with Design Patterns, Principles and the Best Practices. How to handle millions of request with designing system for high availability, high scalability, low latency, and resilience to network failures on distributed microservices.
platformplatform/PlatformPlatform
A platform designed for building enterprise-grade, multi-tenant products using Azure, .NET, React, TypeScript, Infrastructure as Code, etc.
thangchung/practical-dotnet-aspire
The practical .NET Aspire builds on the coffeeshop app business domain
Corsinvest/cv4pve-admin
Web management platform for Proxmox VE clusters: like vCenter but for Proxmox
J-Tech-Japan/Sekiban
Sekiban - an Opinionated Event Sourcing and CQRS Framework using C#. It can store data into Azure Cosmos DB, AWS Dynamo DB or Postgres
davidfowl/aspire-ai-chat-demo
Aspire AI Chat is a full-stack chat sample that combines modern technologies to deliver a ChatGPT-like experience.
kaybi-gh/K7
Self-hosted media server for a small circle of family and friends.
daohainam/microservice-patterns
Microservice pattern demos (Saga, EventSourcing, CQRS...) running on .NET Aspire
poorna-soysa/grpc-demo
This repository contains a sample application built with .NET 8, demonstrating the use of gRPC for high-performance remote procedure calls
Azure-Samples/eShopOnAzure
A variant of https://github.com/dotnet/eShop that uses Azure services
Version Downloads Last Updated
13.6.4 7,499 10/24/2026
13.6.3 19,560 10/21/2026
13.6.2 19,200 10/20/2026
13.6.1 285,706 10/7/2026
13.6.0 224,372 9/29/2026
13.5.4 304,285 9/15/2026
13.5.3 546,999 8/25/2026
13.5.2 82,410 8/21/2026
13.5.1 39,002 8/20/2026
13.5.0 75,300 8/18/2026
13.4.6 1,416,569 6/19/2026
13.4.5 140,351 6/17/2026
13.4.4 102,080 6/15/2026
13.4.3 204,755 6/8/2026
13.4.2 89,793 6/3/2026
13.4.1 9,757 6/3/2026
13.4.0 149,109 6/1/2026
13.3.5 348,500 5/21/2026
13.3.4 61,826 5/19/2026
13.3.3 132,649 5/15/2026
Loading failed