PostgresBuilderExtensions Methods

Docs / Reference / Search C# APIs / Aspire.Hosting.PostgreSQL / PostgresBuilderExtensions / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting.PostgreSQL PostgresBuilderExtensions Methods

Class Methods 14 members

Provides extension methods for adding PostgreSQL resources to an Hosting.IDistributedApplicationBuilder.

AddDatabase(IResourceBuilder<PostgresServerResource>, string, string?) extension IResourceBuilder<PostgresDatabaseResource>

Adds a PostgreSQL database to the application model.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresDatabaseResource> AddDatabase(
        this IResourceBuilder<PostgresServerResource> builder,
        string name,
        string? databaseName = null)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L140-L167

Parameters

builder IResourceBuilder<PostgresServerResource> The PostgreSQL server resource builder.

name string The name of the resource. This name will be used as the connection string name when referenced in a dependency.

databaseName string? optional The name of the database. If not provided, this defaults to the same value as name.

Returns

IResourceBuilder<PostgresDatabaseResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This resource includes built-in health checks. When this resource is referenced as a dependency using the ResourceBuilderExtensions.WaitFor extension method then the dependent resource will wait until the Postgres database is available.

Note that calling PostgresBuilderExtensions.AddDatabase will result in the database being created on the Postgres server when the server becomes ready. The database creation happens automatically as part of the resource lifecycle.

AddPostgres(IDistributedApplicationBuilder, string, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>, int?) extension IResourceBuilder<PostgresServerResource>

Adds a PostgreSQL resource to the application model. A container is used for local development.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> AddPostgres(
        this IDistributedApplicationBuilder builder,
        string name,
        IResourceBuilder<ParameterResource>? userName = null,
        IResourceBuilder<ParameterResource>? password = null,
        int? port = null)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L47-L116

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder.

name string The name of the resource. This name will be used as the connection string name when referenced in a dependency.

userName IResourceBuilder<ParameterResource> optional The parameter used to provide the user name for the PostgreSQL resource. If null a default value will be used.

password IResourceBuilder<ParameterResource> optional The parameter used to provide the administrator password for the PostgreSQL resource. If null a random password will be generated.

port int? optional The host port used when launching the container. If null a random port will be assigned.

Returns

IResourceBuilder<PostgresServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This resource includes built-in health checks. When this resource is referenced as a dependency using the ResourceBuilderExtensions.WaitFor extension method then the dependent resource will wait until the Postgres resource is able to service requests.

This version of the package defaults to the tag of the container image.

WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, string) extension IResourceBuilder<PostgresDatabaseResource>

Defines the SQL script used to create the database.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresDatabaseResource> WithCreationScript(
        this IResourceBuilder<PostgresDatabaseResource> builder,
        string script)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L439-L444

Parameters

builder IResourceBuilder<PostgresDatabaseResource> The builder for the PostgresDatabaseResource.

script string The SQL script used to create the database.

Returns

IResourceBuilder<PostgresDatabaseResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

The script can only contain SQL statements applying to the default database like CREATE DATABASE. Custom statements like table creation and data insertion are not supported since they require a distinct connection to the newly created database. Default script is

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

WithDataBindMount(IResourceBuilder<PostgresServerResource>, string, bool) extension IResourceBuilder<PostgresServerResource>

Adds a bind mount for the data folder to a PostgreSQL container resource.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithDataBindMount(
        this IResourceBuilder<PostgresServerResource> builder,
        string source,
        bool isReadOnly = false)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L386-L389

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

source string The source directory on the host to mount into the container.

isReadOnly bool optional A flag that indicates if this is a read-only mount.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

WithDataVolume(IResourceBuilder<PostgresServerResource>, string?, bool) extension IResourceBuilder<PostgresServerResource>

Adds a named volume for the data folder to a PostgreSQL container resource.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithDataVolume(
        this IResourceBuilder<PostgresServerResource> builder,
        string? name = null,
        bool isReadOnly = false)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L371-L374

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

name string? optional The name of the volume. Defaults to an auto-generated name based on the application and resource names.

isReadOnly bool optional A flag that indicates if this is a read-only volume.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

WithHostPort(IResourceBuilder<PgAdminContainerResource>, int?) extension IResourceBuilder<PgAdminContainerResource>

Configures the host port that the PGAdmin resource is exposed on instead of using randomly assigned port.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PgAdminContainerResource> WithHostPort(
        this IResourceBuilder<PgAdminContainerResource> builder,
        int? port)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs

Parameters

builder IResourceBuilder<PgAdminContainerResource> The resource builder for PGAdmin.

port int? The port to bind on the host. If null is used random port will be assigned.

Returns

IResourceBuilder<PgAdminContainerResource> The resource builder for PGAdmin.

WithHostPort(IResourceBuilder<PgWebContainerResource>, int?) extension IResourceBuilder<PgWebContainerResource>

Configures the host port that the pgweb resource is exposed on instead of using randomly assigned port.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PgWebContainerResource> WithHostPort(
        this IResourceBuilder<PgWebContainerResource> builder,
        int? port)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs

Parameters

builder IResourceBuilder<PgWebContainerResource> The resource builder for pgweb.

port int? The port to bind on the host. If null is used random port will be assigned.

Returns

IResourceBuilder<PgWebContainerResource> The resource builder for pgweb.

WithHostPort(IResourceBuilder<PostgresServerResource>, int?) extension IResourceBuilder<PostgresServerResource>

Configures the host port that the PostgreSQL resource is exposed on instead of using randomly assigned port.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithHostPort(
        this IResourceBuilder<PostgresServerResource> builder,
        int? port)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

port int? The port to bind on the host. If null is used random port will be assigned.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

Obsolete — Use WithInitFiles instead.

WithInitBindMount(IResourceBuilder<PostgresServerResource>, string, bool) extension IResourceBuilder<PostgresServerResource>

Adds a bind mount for the init folder to a PostgreSQL container resource.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithInitBindMount(
        this IResourceBuilder<PostgresServerResource> builder,
        string source,
        bool isReadOnly = true)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L402-L405

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

source string The source directory on the host to mount into the container.

isReadOnly bool optional A flag that indicates if this is a read-only mount.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

WithInitFiles(IResourceBuilder<PostgresServerResource>, string) extension IResourceBuilder<PostgresServerResource>

Copies init files to a PostgreSQL container resource.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithInitFiles(
        this IResourceBuilder<PostgresServerResource> builder,
        string source)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L416-L423

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

source string The source directory or files on the host to copy into the container.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

WithPassword(IResourceBuilder<PostgresServerResource>, IResourceBuilder<ParameterResource>) extension IResourceBuilder<PostgresServerResource>

Configures the password that the PostgreSQL resource is used.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithPassword(
        this IResourceBuilder<PostgresServerResource> builder,
        IResourceBuilder<ParameterResource> password)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L455-L459

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

password IResourceBuilder<ParameterResource> The parameter used to provide the password for the PostgreSQL resource.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.

WithPgAdmin(IResourceBuilder<T>, Action<IResourceBuilder<PgAdminContainerResource>>, string?) extension IResourceBuilder<T>

Adds a pgAdmin 4 administration and development platform for PostgreSQL to the application model.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<T> WithPgAdmin<T>(
        this IResourceBuilder<T> builder,
        Action<IResourceBuilder<PgAdminContainerResource>>? configureContainer = null,
        string? containerName = null)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L183-L224

Parameters

builder IResourceBuilder<T> The PostgreSQL server resource builder.

configureContainer Action<IResourceBuilder<PgAdminContainerResource>> optional Callback to configure PgAdmin container resource.

containerName string? optional The name of the container (Optional).

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This version of the package defaults to the tag of the container image.

WithPgWeb(IResourceBuilder<PostgresServerResource>, Action<IResourceBuilder<PgWebContainerResource>>, string?) extension IResourceBuilder<PostgresServerResource>

Adds an administration and development platform for PostgreSQL to the application model using pgweb. This version of the package defaults to the tag of the container image.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithPgWeb(
        this IResourceBuilder<PostgresServerResource> builder,
        Action<IResourceBuilder<PgWebContainerResource>>? configureContainer = null,
        string? containerName = null)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L287-L337

Parameters

builder IResourceBuilder<PostgresServerResource> The Postgres server resource builder.

configureContainer Action<IResourceBuilder<PgWebContainerResource>> optional Configuration callback for pgweb container resource.

containerName string? optional The name of the container (Optional).

Returns

IResourceBuilder<PostgresServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Use in application host with a Postgres resource

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
   .WithPgWeb();
var db = postgres.AddDatabase("db");

var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

WithUserName(IResourceBuilder<PostgresServerResource>, IResourceBuilder<ParameterResource>) extension IResourceBuilder<PostgresServerResource>

Configures the user name that the PostgreSQL resource is used.

public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresServerResource> WithUserName(
        this IResourceBuilder<PostgresServerResource> builder,
        IResourceBuilder<ParameterResource> userName)
    {
        // ...
    }
}

PostgresBuilderExtensions.cs#L470-L474

Parameters

builder IResourceBuilder<PostgresServerResource> The resource builder.

userName IResourceBuilder<ParameterResource> The parameter used to provide the user name for the PostgreSQL resource.

Returns

IResourceBuilder<PostgresServerResource> The ApplicationModel.IResourceBuilder`1.