# PostgresBuilderExtensions Methods

- Package: [Aspire.Hosting.PostgreSQL](/reference/api/csharp/aspire.hosting.postgresql.md)
- Type: [PostgresBuilderExtensions](/reference/api/csharp/aspire.hosting.postgresql/postgresbuilderextensions.md)
- Kind: `Methods`
- Members: `15`

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

## AddDatabase(IResourceBuilder<PostgresServerResource>, string, string?)

- Name: `AddDatabase(IResourceBuilder<PostgresServerResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresDatabaseResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L150-L177)

Adds a PostgreSQL database to the application model.

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

## 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(IResourceBuilder<PostgresServerResource>, string, string?)](/reference/api/csharp/aspire.hosting.postgresql/postgresbuilderextensions/methods.md#adddatabase-iresourcebuilder-postgresserverresource-string-string) 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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `AddPostgres(IDistributedApplicationBuilder, string, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L54-L123)

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

```csharp
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)
    {
        // ...
    }
}
```

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, string)

- Name: `WithCreationScript(IResourceBuilder<PostgresDatabaseResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresDatabaseResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L547-L552)

Defines the SQL script used to create the database.

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

## Parameters

- `builder` (`IResourceBuilder<PostgresDatabaseResource>`)
  The builder for the [PostgresDatabaseResource](/reference/api/csharp/aspire.hosting.postgresql/postgresdatabaseresource.md).
- `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

```csharp
CREATE DATABASE "<QUOTED_DATABASE_NAME>"
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithDataBindMount(IResourceBuilder<PostgresServerResource>, string, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L486-L491)

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

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

## 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`.

## Remarks

The data directory location varies by PostgreSQL version:

- PostgreSQL 17 and earlier: `/var/lib/postgresql/data`
- PostgreSQL 18 and later: `/var/lib/postgresql`

This method automatically selects the correct path based on the configured container image tag.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithDataVolume(IResourceBuilder<PostgresServerResource>, string?, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L455-L460)

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

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

## 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`.

## Remarks

The data directory location varies by PostgreSQL version:

- PostgreSQL 17 and earlier: `/var/lib/postgresql/data`
- PostgreSQL 18 and later: `/var/lib/postgresql`

This method automatically selects the correct path based on the configured container image tag.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHostPort(IResourceBuilder<PgAdminContainerResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PgAdminContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs)

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

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

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHostPort(IResourceBuilder<PgWebContainerResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PgWebContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs)

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

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

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHostPort(IResourceBuilder<PostgresServerResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs)

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

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

## 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`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

> **Obsolete:** Use WithInitFiles instead.

- Name: `WithInitBindMount(IResourceBuilder<PostgresServerResource>, string, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L506-L509)

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

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

## 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`.

## Remarks

This method is not available in polyglot app hosts. Use [PostgresBuilderExtensions.WithInitFiles(IResourceBuilder<PostgresServerResource>, string)](/reference/api/csharp/aspire.hosting.postgresql/postgresbuilderextensions/methods.md#withinitfiles-iresourcebuilder-postgresserverresource-string) instead.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## WithInitFiles(IResourceBuilder<PostgresServerResource>, string)

- Name: `WithInitFiles(IResourceBuilder<PostgresServerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L522-L529)

Copies init files to a PostgreSQL container resource.

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

## 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`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithPassword(IResourceBuilder<PostgresServerResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L565-L569)

Configures the password that the PostgreSQL resource is used.

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

## 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`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithPgAdmin(IResourceBuilder<T>, Action<IResourceBuilder<PgAdminContainerResource>>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L195-L236)

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

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

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithPgWeb(IResourceBuilder<PostgresServerResource>, Action<IResourceBuilder<PgWebContainerResource>>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L305-L355)

Adds an administration and development platform for PostgreSQL to the application model using pgweb.

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

## 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

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithPostgresMcp(IResourceBuilder<PostgresDatabaseResource>, Action<IResourceBuilder<PostgresMcpContainerResource>>, string?)

> **Experimental:** ASPIREPOSTGRES001 - [Learn more](/diagnostics/aspirepostgres001/)

- Name: `WithPostgresMcp(IResourceBuilder<PostgresDatabaseResource>, Action<IResourceBuilder<PostgresMcpContainerResource>>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresDatabaseResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L378-L408)

Adds a Postgres MCP server container and configures it to connect to the database represented by `builder`.

```csharp
public static class PostgresBuilderExtensions
{
    public static IResourceBuilder<PostgresDatabaseResource> WithPostgresMcp(
        this IResourceBuilder<PostgresDatabaseResource> builder,
        Action<IResourceBuilder<PostgresMcpContainerResource>>? configureContainer = null,
        string? containerName = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<PostgresDatabaseResource>`)
  The Postgres database resource builder.
- `configureContainer` (`Action<IResourceBuilder<PostgresMcpContainerResource>>`) `optional`
  Configuration callback for the Postgres MCP container resource.
- `containerName` (`string?`) `optional`
  The name of the container (optional).

## Returns

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

## Remarks

The Postgres MCP server is configured to use SSE transport and will expose an HTTP endpoint. This version of the package defaults to the tag of the container image.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithUserName(IResourceBuilder<PostgresServerResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PostgresServerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs#L582-L586)

Configures the user name that the PostgreSQL resource is used.

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

## 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`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.