How to enable PostgreSQL connection pool using UpCloud API

Last updated on: October 22, 2026

PostgreSQL connection pool allows you to serve a larger number of client connections to any given Managed Database than normally possible while keeping the server resource usage low. With connection pooling enabled, client connections are grouped together and do not each take up a separate backend process on the server. Therefore, adding a connection pooler that utilizes fewer backend connections frees up server resources for more important uses. For how connection pools work, including pool sizes, modes and how to connect, see Managed PostgreSQL connection pooling.

Accessing UpCloud API

UpCloud API offers a programmable interface to all of our services and features with easy-to-understand commands. If you are new to our API, have a look at How to get started using the UpCloud API.

In this guide, we’ll explain the API queries you can use to create and manage your PostgreSQL connection pool. Full documentation of our API is available for advanced users who might want to skip to the point.

Connection pooling modes

Each connection pool runs in one of three modes, which you set with pool_mode:

session: a client keeps a server connection until it disconnects.
transaction: a client uses a server connection only for the length of each transaction. This is the most commonly used mode.
statement: a server connection is returned to the pool after every statement, and transactions with more than one statement aren't allowed.

For how each mode affects your clients, and which PostgreSQL features need session mode, see Managed PostgreSQL connection pooling.

Getting connection pool details

PostgreSQL Managed Databases can have more than one connection pool used for different logical databases and database users. You can get a list of all connection pools for a given Managed Database identified by a UUID with the following command.

GET /1.3/database/{uuid}/connection-pools

Furthermore, you can get details on individual connection pools by selecting one by name.

GET /1.3/database/{uuid}/connection-pools/{pool_name}

The response would include the connection pool details such as in the example below.

Output
{
    "connection_uri": "postgres://upadmin:{password}@example-mctapmghasah.db.upclouddatabases.com:11570/pool-1?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "transaction",
    "pool_name": "pool-1",
    "pool_size": 10,
    "username": "upadmin"
}

The same details, with the exception of connection_uri, are needed for creating a new pool.

Creating a new connection pool

Creating a new connection pool takes but a simple POST request with the required parameters set in the request body. The example request shown below lists everything needed.

POST /1.3/database/{uuid}/connection-pools

{
  "database": "defaultdb",
  "pool_mode": "transaction",
  "pool_name": "pool-1",
  "pool_size": 10,
  "username": "upadmin"
}

All the parameters except the username are required.

Database is the logical database the pool connects to.
Pool name needs to be unique, because clients use it in place of the database name when they connect through the pool.
Pool mode is session, transaction or statement, as described in Connection pooling modes.
Pool size is the number of server connections the pool opens to the database, not the number of clients it accepts. The recommended size is roughly 3-5 times the number of CPU cores allocated in your Managed Database node configuration. The sizes of all pools on a Managed Database together must fit within its connection limit, which is the plan's maximum connections minus three. If they don't, the API returns 409 with a message that the pools have more connections than the database can handle.
Username limits the pool to one database user, and other users are rejected. Leave it out to allow any database user.

When you create a connection pool, you get a response to confirm the action. The response also shows the pool's connection_uri, which you use to connect through the pool. It has the pool name in place of the database name and its own port, separate from the database's port. If you set a username, the URI also includes that user's credentials.

Output
{
    "connection_uri": "postgres://upadmin:{password}@example-mctapmghasah.db.upclouddatabases.com:11570/pool-1?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "transaction",
    "pool_name": "pool-1",
    "pool_size": 10,
    "username": "upadmin"
}

To connect over the public network, which needs public access enabled, use the public hostname. It adds the prefix public- to the hostname in connection_uri, for example:

postgres://upadmin:{password}@public-example-mctapmghasah.db.upclouddatabases.com:11570/pool-1?sslmode=require

If you need to find the new connection_uri at any time later, you can always query the pool by name.

GET /1.3/database/{uuid}/connection-pools/pool-1

You will then get the connection pool details in the response.

Modifying connection pool

If you need to make changes to a connection pool, you can update the pool parameters with PATCH request with the parameters you want to change in the body.

PATCH /1.3/database/{uuid}/connection-pools/{pool_name}

{
  "database": "defaultdb",
  "pool_mode": "transaction",
  "pool_size": 20,
  "username": "upadmin"
}

In the response, you will then see the new details of your connection pool.

Output
{
    "connection_uri": "postgres://upadmin:{password}@example-mctapmghasah.db.upclouddatabases.com:11570/pool-1?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "transaction",
    "pool_name": "pool-1",
    "pool_size": 20,
    "username": "upadmin"
}

Deleting connection pool

Lastly, should you no longer need any given connection pool, you can delete a connection pool identified by name using the following request.

DELETE /1.3/database/{uuid}/connection-pools/{pool_name}

If you get no error, the named connection pool was deleted successfully. The delete command itself only returns a response status code 204 with no content. Any clients connected through the pool are disconnected.

Summary

The UpCloud API makes it simple to create and manage your connection pools. Enabling a connection pool for PostgreSQL Managed Database can considerably improve your database throughput and save you money on your resource usage.

If you’d like to find out more about the UpCloud API and the related queries for Managed Databases, head over to our API documentation for the full specification.

UpCloud Managed Databases can also be configured using our Terraform provider. To get started, see How to configure Managed Databases using Terraform.

Contributed by: Janne Ruostemaa