---
title: "Add a New Connection Pool (PostgreSQL)"
method: POST
path: "/v2/databases/{database_cluster_uuid}/pools"
tags: ["DigitalOcean-public.v2-new_Databases"]
---

# Add a New Connection Pool (PostgreSQL)

`POST /v2/databases/{database_cluster_uuid}/pools`

For PostgreSQL database clusters, connection pools can be used to allow a
database to share its idle connections. The popular PostgreSQL connection
pooling utility PgBouncer is used to provide this service. [See here for more information](https://docs.digitalocean.com/products/databases/postgresql/how-to/manage-connection-pools/)
about how and why to use PgBouncer connection pooling including
details about the available transaction modes.

To add a new connection pool to a PostgreSQL database cluster, send a POST
request to `/v2/databases/$DATABASE_ID/pools` specifying a name for the pool,
the user to connect with, the database to connect to, as well as its desired
size and transaction mode.

## Path parameters

- `database_cluster_uuid` string, uuid, required

## Request body

- ConnectionPool
  - `name` string, required — A unique name for the connection pool. Must be between 3 and 60 characters.
  - `mode` string, required — The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.
  - `size` integer, required — The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster.
  - `db` string, required — The database for use with the connection pool.
  - `user` string — The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user.
  - `connection` object
    - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
    - `database` string — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
  - `private_connection` object
    - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
    - `database` string — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
  - `standby_connection` object
    - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
    - `database` string — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
  - `standby_private_connection` object
    - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
    - `database` string — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.

## Response `201`

A JSON object with a key of `pool`.

- object
  - `pool` ConnectionPool, required
    - `name` string, required — A unique name for the connection pool. Must be between 3 and 60 characters.
    - `mode` string, required — The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.
    - `size` integer, required — The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster.
    - `db` string, required — The database for use with the connection pool.
    - `user` string — The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user.
    - `connection` object
      - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
      - `database` string — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
    - `private_connection` object
      - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
      - `database` string — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
    - `standby_connection` object
      - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
      - `database` string — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
    - `standby_private_connection` object
      - `uri` string — A connection string in the format accepted by the `psql` command. This is provided as a convenience and should be able to be constructed by the other attributes.
      - `database` string — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `404` — The resource was not found.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/versions/cb3bf9b21459/schema)