For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.databases.add_connection_pool(
    database_cluster_uuid="9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    body={
        "name": "backend-pool",
        "mode": "transaction",
        "size": 10,
        ...,
    },
)

Description

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 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_cluster_uuid}/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.

Parameters

database_cluster_uuid string required

A unique identifier for a database cluster.

name string required

Example: backend-pool

A unique name for the connection pool. Must be between 3 and 60 characters.

mode string required

Example: transaction

The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.

size integer required

Example: 10

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

Example: defaultdb

The database for use with the connection pool.

user string optional

Example: doadmin

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 optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

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 optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

private_connection object optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

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 optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

standby_connection object optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

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 optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

standby_private_connection object optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

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 optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

add_conn_pool_req = {
  "name": "backend-pool",
  "mode": "transaction",
  "size": 10,
  "db": "defaultdb",
  "user": "doadmin"
}    

add_conn_pool_resp = client.databases.add_connection_pool(database_cluster_uuid="9cc10173", body=add_conn_pool_req)

Response Example

{
  "pool": {
    "user": "doadmin",
    "name": "backend-pool",
    "size": 10,
    "db": "defaultdb",
    "mode": "transaction",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require",
      "database": "backend-pool",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25061,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    }
  }
}

More Information

See /v2/databases/{database_cluster_uuid}/pools in the API reference for additional detail on responses, headers, parameters, and more.