Aspire.Hosting.PostgreSQL 13.5.0

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


                    

                
NuGet\Install-Package Aspire.Hosting.PostgreSQL -Version 13.5.0
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.5.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="13.5.0" />
                    


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


                    

                
#r "nuget: Aspire.Hosting.PostgreSQL, 13.5.0"
#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.5.0
#: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.5.0
                    


                            Install as a Cake Addin
                        

                    

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


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

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 (32)

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).
Nextended.Aspire.Hosting.Supabase

This Library provides an Aspire Supabase solution
Altemiq.Aspire.Hosting.PostgreSQL.Extensions

PostgreSQL support for .NET Aspire.

GitHub repositories (53)

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.
thomhurst/TUnit
A modern, fast and flexible .NET testing framework
oskardudycz/EventSourcing.NetCore
Examples and Tutorials of Event Sourcing in .NET
evolutionary-architecture/evolutionary-architecture-by-example
Navigate the complex landscape of .NET software architecture with our step-by-step, story-like guide. Unpack the interplay between modular monoliths, microservices, domain-driven design, and various architectural patterns. Go beyond the one-size-fits-all solutions and understand how to blend these approaches based on your unique needs.
Nethereum/Nethereum
Ethereum .Net cross platform integration library
GZTimeWalker/GZCTF
The GZ::CTF project, an open source CTF platform.
Azure/data-api-builder
Data API builder provides modern REST, GraphQL endpoints and MCP tools to your Azure Databases and on-prem stores.
meysamhadeli/booking-microservices
A practical microservices with the latest technologies and architectures like Vertical Slice Architecture, Event Sourcing, CQRS, DDD, gRpc, MongoDB, RabbitMq, Wolverine, and Aspire in .Net 10.
bitfoundation/bitplatform
Build all of your apps using what you already know and love ❤️
abpframework/abp-samples
Sample solutions built with the ABP Framework
microsoft/aspire-samples
Browse the sample apps demonstrating Aspire integration across C#, JavaScript, TypeScript, Python, Go, containers, databases, cloud, AI, and observability scenarios.
tonybaloney/CSnakes
Embed Python in .NET
colinin/abp-next-admin
这是基于vue-vben-admin 模板适用于abp vNext的前端管理项目
mehdihadeli/food-delivery-microservices
🍔 A practical and cloud-native food delivery microservices, built with .Net Aspire, .Net 10, Wolverine, Domain-Driven Design, CQRS, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.
cmu-sei/GHOSTS
GHOSTS (General Human-Oriented Synthetic Teammates and Systems) is a realistic user simulation framework for cyber experimentation, simulation, training, and exercise
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, Masstransit, and Aspire in .Net 10.
Version Downloads Last Updated
13.5.0 1,451 8/18/2026
13.4.6 731,150 6/19/2026
13.4.5 88,981 6/17/2026
13.4.4 68,306 6/15/2026
13.4.3 148,648 6/8/2026
13.4.2 70,605 6/3/2026
13.4.1 6,634 6/3/2026
13.4.0 101,265 6/1/2026
13.3.5 248,310 5/21/2026
13.3.4 35,553 5/19/2026
13.3.3 112,223 5/15/2026
13.3.2 35,603 5/14/2026
13.3.1 28,356 5/12/2026
13.3.0 231,464 5/7/2026
13.2.4 299,182 4/24/2026
13.2.3 62,483 4/21/2026
13.2.2 200,776 4/8/2026
13.2.1 123,549 3/31/2026
13.2.0 242,231 3/23/2026
13.1.3 78,593 3/19/2026
Loading failed