Configure managed connection pooling
Stay organized with collections Save and categorize content based on your preferences.

This page describes how to enable, connect to, and monitor managed connection pooling in AlloyDB for PostgreSQL. Managed connection pooling is a design pattern that optimizes database connection management by maintaining a pool of pre-established connections. This pool of connections are then reused by the application instead of opening and closing connections for every database operation, which improves performance and resource utilization.

Using managed connection pooling, you can scale your database workloads by optimizing resource usage and connection latency for your AlloyDB instances. Managed connection pooling dynamically assigns server connections to incoming requests when possible using pooling and multiplexing. This approach delivers performance improvements, especially for scaled connections, by absorbing sudden connection spikes and by reusing existing database connections. Instead of connecting to a specific database, when using managed connection pooling, an application connects to a pooler, which provides shorter connection times and scalability for your read workloads.

While you can use managed connection pooling for any transactional workload, managed connection pooling is best suited for applications that contain more short-lived connections, or applications that might experience a connection surge.

Before you begin

You must connect to your instance using a direct connection. Managed connection pooling doesn't support connection with the AlloyDB Auth Proxy or AlloyDB Language Connectors.

Required roles

To get the permission that you need to enable and use managed connection pooling, ask your administrator to grant you the Cloud AlloyDB Admin (roles/alloydb.admin) IAM role on the AlloyDB instance. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the alloydb.instances.update permission, which is required to enable and use managed connection pooling.

You might also be able to get this permission with custom roles or other predefined roles.

Advanced configuration options

AlloyDB managed connection pooling supports the following advanced pooling configuration options. You can customize managed connection pooling to meet the needs of your instance using these configuration options. You can set these configurations on an instance-level basis using the Google Cloud console, gcloud CLI, or the AlloyDB API.

Configuration name	Description
Connection mode (`connection-pooling-pool-mode`)	For the connection mode, you can select either transaction (default) or session. Transaction (`transaction`): Pools connections at a transaction level. A server connection is assigned to a client during a transaction. After the transaction completes, the server connection is put back into the pool. Session (`session`): Pools connections at a session level. A server connection is assigned to the client during the whole time that it stays connected. After the client disconnects, the server connection is put back into the pool.
Maximum pool size (`connection-pooling-max-pool-size`)	The maximum size of the connection pool. The default value is 50 connections.
Minimum pool size (`connection-pooling-min-pool-size`)	The minimum size of the connection pool. The default value is 0 connections.
Idle client connection timeout(s) (`connection-pooling-client-connection-idle-timeout`)	The time that a client-connection remains idle before it times out. This value can range from 0 to 2,147,483 seconds, and the default value is 0 seconds. You can only configure this parameter using the Google Cloud console.
Idle server connection timeout(s) (`connection-pooling-server-connection-idle-timeout`)	The time that a server connection remains idle before it times out. This value can range from 0 to 2,147,483 seconds, and the default value is 600 seconds.
Query wait timeout(s) (`connection-pooling-query-wait-timeout`)	The time that a query waits until it times out. This value can range from 0 to 2,147,483 seconds, and the default value is 120 seconds.
Maximum prepared statements (`connection-pooling-max-prepared-statements`)	The maximum number of prepared statements commands sent in the transaction pooling mode. The default value is 0.
Ignore startup parameters (`connection-pooling-ignore-startup-parameters`)	The parameters you want ignored, that aren't tracked in startup packets by default.
Server lifetime(s) (`connection-pooling-server-lifetime`)	The maximum time a server connection is unused before managed connection pooling closes it. The default value is 3600 seconds. You can only configure this parameter using the Google Cloud console.

By default, managed connection pooling initiates connections to the AlloyDB server. When a client connection is established and authenticated, managed connection pooling might create one or more server connections so that the size of the pool matches the chosen configuration. The client connection is then assigned an available server connection. Server connections are maintained until they are explicitly closed or they are idle for longer than the idle server connection timeout period.

Enable managed connection pooling

You can enable managed connection pooling for any existing or new instances.

Enable for a new primary instance

To create a new primary instance with managed connection pooling enabled, see Create a primary instance. You can enable managed connection pooling for an instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Enable for a new read pool instance

To create a new read pool instance with managed connection pooling enabled, see Create a read pool instance. You can enable managed connection pooling for an instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Enable for an existing instance

You can enable managed connection pooling for an existing instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Console

Go to the Clusters page.

Go to Clusters
Click a cluster in the Resource name column.
In the Overview page, navigate to Instances in your cluster.
Click Edit primary or Edit read pool.
Under Managed connection pool, check the box for Enable managed connection pool.
Optional: To configure managed connection pooling options, click Advanced pooling options.

You can customize managed connection pooling options to meet the needs of your instance. For more information, see advanced configurations options.
Click Save changes.

gcloud

To enable managed connection pooling for an existing primary or read pool instance, use the following gcloud alpha alloydb instances update command:

gcloud alpha alloydb instances update INSTANCE_ID \
  --project=PROJECT_ID \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --enable-connection-pooling

Replace the following:

INSTANCE_ID: the ID of the AlloyDB instance that you want to enable managed connection pooling for.
PROJECT_ID: the ID of the project.
REGION_ID: the ID of the region.
CLUSTER_ID: the ID of the cluster.

After you enable managed connection pooling, you can customize managed connection pooling options to meet the needs of your instance by setting the advanced configuration options. For more information on how to set the configuration options, see Modify managed connection pooling for an instance.

REST

To enable managed connection pooling for an existing primary or read pool instance, use the following command and set connectionPoolConfig:

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of the project.
LOCATION_ID: the ID of the cluster's region.
CLUSTER_ID: the ID of the cluster. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
INSTANCE_ID: the ID of the instance.

HTTP method and URL:

PATCH https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Request JSON body:

{
  "connectionPoolConfig": {
    "enabled": true
  }
}

Connect to managed connection pooling

Connecting to managed connection pooling is identical to direct database connections, except on a different port. Managed connection pooling listens on port 6432. Any user added to the AlloyDB instance is able to connect using managed connection pooling.

Connect using built-in authentication

The command example connects your AlloyDB instance to managed connection pooling using built-in authentication.

psql postgresql://USERNAME:PASSWORD@IP_ADDRESS:6432/postgres

Connect using SSL connections

Instance SSL mode also applies to any connections to the managed connection pool. By default, only SSL connections are accepted. To allow unencrypted connections, use the following gcloud alloydb instances update command to set instance SSL mode to ALLOW_UNENCRYPTED_AND_ENCRYPTED.

gcloud alloydb instances update INSTANCE_ID \
  --project=PROJECT_ID \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Modify managed connection pooling for an instance

After you enable managed connection pooling, you can customize managed connection pooling options to meet the needs of your instance using the advanced configuration options. These configuration options are called managed connection pooling flags. For more information on the configuration options, their default values, and ranges, see advanced configuration options.

You can modify managed connection pooling configuration options for an existing instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Console

Go to the Clusters page.

Go to Clusters
Click a cluster in the Resource Name column.
In the Overview page, navigate to Instances in your cluster.
Click Edit instance or Edit read pool for the instance that you want to modify.
Under Managed connection pool, expand Advanced pooling options.
Modify the advanced pooling options that you want to update. You can modify the following options:
- Connection mode
- Maximum pool size
- Minimum pool size
- Maximum client connection
- Idle client connection timeout(s)
- Idle server connection timeout(s)
- Query wait timeout(s)
- Maximum prepared statements
- Ignore startup parameters
- Server lifetime(s)
Click Update instance.

gcloud

To modify managed connection pooling configuration options for an existing instance, use the following gcloud alpha alloydb instances update command:

  gcloud alpha alloydb instances update INSTANCE_ID \
    --project=PROJECT_ID \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    { \
      --connection-pooling-pool-mode=CONNECTION_MODE \
      | --connection-pooling-max-pool-size=MAX_POOL_SIZE \
      | --connection-pooling-min-pool-size=MIN_POOL_SIZE \
      | --connection-pooling-max-client-connections=MAX_CLIENT_CONNECTION \
      | --connection-pooling-server-idle-timeout=SERVER_IDLE_TIMEOUT_PERIOD \
      | --connection-pooling-query-wait-timeout=QUERY_WAIT_TIMEOUT_PERIOD \
      | --connection-pooling-ignore-startup-parameters=IGNORE_STARTUP_PARAMETERS \
    }

Replace the following:

INSTANCE_ID: the name of the AlloyDB instance that you want to disable managed connection pooling for.
PROJECT_ID: the ID of the project.
REGION_ID: the ID of the region.
CLUSTER_ID: the ID of the cluster.
You can configure the following options:
- --connection-pooling-pool-mode. This must be one of session or transaction.
- --connection-pooling-max-pool-size
- --connection-pooling-min-pool-size
- --connection-pooling-max-client-connections
- --connection-pooling-server-idle-timeout
- --connection-pooling-query-wait-timeout
- --connection-pooling-ignore-startup-parameters

REST

To modify managed connection pooling configuration options for an existing read pool instance, use the following command and set connectionPoolConfig:

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of the project.
LOCATION_ID: the ID of the cluster's region.
CLUSTER_ID: the ID of the cluster that you create. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
INSTANCE_ID: the ID of the instance that you create.
You can configure the following options:
- POOL_MODE. This must be one of session or transaction.
- MAX_POOL_SIZE
- MIN_POOL_SIZE
- MAX_CLIENT_CONNECTION
- SERVER_IDLE_TIMEOUT
- QUERY_WAIT_TIMEOUT
- IGNORE_STARTUP_PARAMETERS

HTTP method and URL:

PATCH https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Request JSON body:

{
  "connectionPoolConfig": {
    "enabled": true,
    "flags": {
      "pool_mode": "POOL_MODE",
      "max_pool_size": "MAX_POOL_SIZE",
      "min_pool_size": "MIN_POOL_SIZE",
      "max_client_connection": "MAX_CLIENT_CONNECTION",
      "server_idle_timeout": "SERVER_IDLE_TIMEOUT",
      "query_wait_timeout": "QUERY_WAIT_TIMEOUT",
      "ignore_startup_parameters": "IGNORE_STARTUP_PARAMETERS"
    },
  }
}

View managed connection pooling status for an instance

You can view the status of managed connection pooling for an instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Console

Go to the Clusters page.

Go to Clusters
Click a cluster in the Resource Name column.
In the Overview page, find the instance you want to view the status of managed connection pooling for. The Managed connection pooling field shows whether it is enabled or disabled.

gcloud

To view the status of managed connection pooling for an existing instance, use the following gcloud alpha alloydb instances describe command:

gcloud alpha alloydb instances describe INSTANCE_ID \
  --project=PROJECT_ID \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --format="value(connectionPoolConfig.enabled)"

Replace the following:

INSTANCE_ID: the name of the AlloyDB instance that you want to modify managed connection pooling options for.
PROJECT_ID: the ID of the project.
REGION_ID: the ID of the region.
CLUSTER_ID: the ID of the cluster.

If managed connection pooling is enabled, the following response is returned:

True

REST

To view the status of managed connection pooling for your AlloyDB instance, using the following command and look for connectionPoolConfig:

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of the project.
LOCATION_ID: the ID of the cluster's region.
CLUSTER_ID: the ID of the cluster that you create. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
INSTANCE_ID: the ID of the instance that you create.

HTTP method and URL:

GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Disable managed connection pooling for an existing instance

You can disable managed connection pooling for an existing instance using the Google Cloud console, Google Cloud CLI, or the AlloyDB API.

Console

Go to the Clusters page.

Go to Clusters
Click a cluster in the Resource Name column.
In the Overview page, navigate to Instances in your cluster.
Click Edit instance or Edit read pool for the instance that you want to disable managed pooling connection.
Under Managed connection pool, clear the box for Enable managed connection pool.
Click Update instance.

Note: After you disable managed connection pooling, all connections that were made to the managed connection pooling are dropped.

gcloud

To disable managed connection pooling for an existing instance, use the following gcloud alpha alloydb instances update command:

gcloud alpha alloydb instances update INSTANCE_ID \
  --project=PROJECT_ID \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --no-enable-connection-pooling

Replace the following:

INSTANCE_ID: the name of the AlloyDB instance that you want to disable managed connection pooling for.
PROJECT_ID: the ID of the project.
REGION_ID: the ID of the region.
CLUSTER_ID: the ID of the cluster.

REST

To disable managed connection pooling for an existing read pool instance, use the following command and set connectionPoolConfig to false:

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of the project.
LOCATION_ID: the ID of the cluster's region.
CLUSTER_ID: the ID of the cluster that you create. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
INSTANCE_ID: the ID of the instance that you create.

HTTP method and URL:

PATCH https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Request JSON body:

{
  "connectionPoolConfig": {
    "enabled": false
  }
}

Monitor managed connection pooling

AlloyDB provides the following metrics to help you monitor how managed connection pooling is running on your instance. You can view these metrics using the Metrics Explorer.

Metric name	Description
Number of connection pools `/database/conn_pool/num_pools`	The total number of connection pools per database.
Client connections `/database/conn_pool/client_connections`	Tracks the number of client connections grouped by the status of the client connection per database. The statuses included in this metric are: `active`: the number active connections per database including the idle clients that don't have any pending query requests. `waiting`: the number of clients waiting for a server connection per database.
Server connections `/database/conn_pool/server_connections`	Tracks the number of server connections grouped by the status of the server connection per database. The statuses included in this metric are: `active`: the number of active connections per database. `idle`: the number of idle server connections per database.
Average wait time `/database/conn_pool/client_connections_avg_wait_time`	The average time spent by all clients in waiting state for a server in microseconds per database.

For more information, see AlloyDB metrics.

Limitations

The following limitations apply during the Preview release and are subject to change or removal upon the GA release or after:

Managed connection pooling doesn't support connection with the AlloyDB Auth Proxy or AlloyDB Language Connectors.
If you use managed connection pooling in the transaction pooling mode, then the following SQL features aren't supported:
- SET/RESET
- LISTEN
- WITH HOLD CURSOR
- PREPARE/DEALLOCATE
- PRESERVE/DELETE ROW temp tables
- LOAD
- Session-level advisory locks
- Protocol-level prepared plans

Configure managed connection pooling Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Advanced configuration options

Enable managed connection pooling

Enable for a new primary instance

Enable for a new read pool instance

Enable for an existing instance

Console

gcloud

REST

Connect to managed connection pooling

Connect using built-in authentication

Connect using SSL connections

Modify managed connection pooling for an instance

Console

gcloud

REST

View managed connection pooling status for an instance

Console

gcloud

REST

Disable managed connection pooling for an existing instance

Console

gcloud

REST

Monitor managed connection pooling

Limitations

Configure managed connection pooling
Stay organized with collections Save and categorize content based on your preferences.