connection_pools

Creates, updates, deletes, gets or lists a connection_pools resource.

Overview

Name	`connection_pools`
Type	Resource
Id	`digitalocean.databases.connection_pools`

Fields

The following fields are returned by SELECT queries:

databases_get_connection_pool
databases_list_connection_pools

A JSON object with a key of pool.

Name	Datatype	Description
`name`	`string`	A unique name for the connection pool. Must be between 3 and 60 characters. (example: backend-pool)
`connection`	`object`
`db`	`string`	The database for use with the connection pool. (example: defaultdb)
`mode`	`string`	The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. (example: transaction)
`private_connection`	`object`
`size`	`integer (int32)`	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.
`standby_connection`	`object`
`standby_private_connection`	`object`
`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. (example: doadmin)

A JSON object with a key of pools.

Name	Datatype	Description
`name`	`string`	A unique name for the connection pool. Must be between 3 and 60 characters. (example: backend-pool)
`connection`	`object`
`db`	`string`	The database for use with the connection pool. (example: defaultdb)
`mode`	`string`	The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. (example: transaction)
`private_connection`	`object`
`size`	`integer (int32)`	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.
`standby_connection`	`object`
`standby_private_connection`	`object`
`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. (example: doadmin)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Description
`databases_get_connection_pool`	`select`	`database_cluster_uuid`, `pool_name`	To show information about an existing connection pool for a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. The response will be a JSON object with a `pool` key.
`databases_list_connection_pools`	`select`	`database_cluster_uuid`	To list all of the connection pools available to a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools`. The result will be a JSON object with a `pools` key. This will be set to an array of connection pool objects.
`databases_add_connection_pool`	`insert`	`database_cluster_uuid`, `data__name`, `data__mode`, `data__size`, `data__db`	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_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.
`databases_update_connection_pool`	`replace`	`database_cluster_uuid`, `pool_name`, `data__mode`, `data__size`, `data__db`	To update a connection pool for a PostgreSQL database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`.
`databases_delete_connection_pool`	`delete`	`database_cluster_uuid`, `pool_name`	To delete a specific connection pool for a PostgreSQL database cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`database_cluster_uuid`	`string (uuid)`	A unique identifier for a database cluster. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`pool_name`	`string`	The name used to identify the connection pool. (example: backend-pool)

`SELECT` examples

databases_get_connection_pool
databases_list_connection_pools

To show information about an existing connection pool for a PostgreSQL database cluster, send a GET request to /v2/databases/$DATABASE_ID/pools/$POOL_NAME.
The response will be a JSON object with a pool key.

SELECT
name,
connection,
db,
mode,
private_connection,
size,
standby_connection,
standby_private_connection,
user
FROM digitalocean.databases.connection_pools
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required
AND pool_name = '{{ pool_name }}' -- required;

To list all of the connection pools available to a PostgreSQL database cluster, send a GET request to /v2/databases/$DATABASE_ID/pools.
The result will be a JSON object with a pools key. This will be set to an array of connection pool objects.

SELECT
name,
connection,
db,
mode,
private_connection,
size,
standby_connection,
standby_private_connection,
user
FROM digitalocean.databases.connection_pools
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required;

`INSERT` examples

databases_add_connection_pool
Manifest

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

INSERT INTO digitalocean.databases.connection_pools (
data__name,
data__mode,
data__size,
data__db,
data__user,
database_cluster_uuid
)
SELECT 
'{{ name }}' --required,
'{{ mode }}' --required,
{{ size }} --required,
'{{ db }}' --required,
'{{ user }}',
'{{ database_cluster_uuid }}'
RETURNING
pool
;

# Description fields are for documentation purposes
- name: connection_pools
  props:
    - name: database_cluster_uuid
      value: string (uuid)
      description: Required parameter for the connection_pools resource.
    - name: name
      value: string
      description: >
        A unique name for the connection pool. Must be between 3 and 60 characters.
        
    - name: mode
      value: string
      description: >
        The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.
        
    - name: size
      value: integer
      description: >
        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.
        
    - name: db
      value: string
      description: >
        The database for use with the connection pool.
        
    - name: user
      value: string
      description: >
        The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user.
        

`REPLACE` examples

databases_update_connection_pool

To update a connection pool for a PostgreSQL database cluster, send a PUT request to /v2/databases/$DATABASE_ID/pools/$POOL_NAME.

REPLACE digitalocean.databases.connection_pools
SET 
data__mode = '{{ mode }}',
data__size = {{ size }},
data__db = '{{ db }}',
data__user = '{{ user }}'
WHERE 
database_cluster_uuid = '{{ database_cluster_uuid }}' --required
AND pool_name = '{{ pool_name }}' --required
AND data__mode = '{{ mode }}' --required
AND data__size = '{{ size }}' --required
AND data__db = '{{ db }}' --required;

`DELETE` examples

databases_delete_connection_pool

To delete a specific connection pool for a PostgreSQL database cluster, send
a DELETE request to /v2/databases/$DATABASE_ID/pools/$POOL_NAME.

A status of 204 will be given. This indicates that the request was processed
successfully, but that no response body is needed.

DELETE FROM digitalocean.databases.connection_pools
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' --required
AND pool_name = '{{ pool_name }}' --required;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

REPLACE examples​

DELETE examples​