Skip to content
Install

Use a connection pooler

Each Postgres connection uses memory on the database server, so a database can serve only a limited number of them. A connection pooler accepts many client connections and shares a small set of Postgres server connections between them. Use a pooler when an app opens more connections than the database can serve. Orchard runs the pooler with PgBouncer.

New databases with 1 GB of memory or less start with a pooler. A superadmin can change this default in Instance admin > Configuration > Connection pooler for new small databases.

  • Edit access to the project: the Admin or Member project role.
  • A dedicated database.
  1. Open the database.
  2. Go to Settings > Connection pooler.
  3. Turn on Pool connections.

The Address row shows the pooler address and its status. Wait for the status to change from Starting to Running.

Turning on the pooler does not change the database connection string. Apps keep connecting directly to Postgres until you change them.

  1. Copy the address from the Address row. The address has this format:

    pg-<name>-pooler-rw.<namespace>.svc.cluster.local:5432
  2. Open the app.

  3. Go to Variables.

  4. Set the connection string variable to a value that uses the pooler address as the host. Keep the same user, password, and database name.

  5. Select Save.

The pooler address works only inside the cluster.

  1. Open the database.
  2. Go to Settings > Connection pooler.
  3. Update the settings.
  4. Select Save.

Clients reconnect once when the pooler restarts.

SettingCLI flagDefaultRangeDescription
Mode--modetransactiontransaction, sessionHow the pooler assigns server connections.
Pool size--pool-size101 to 100Server connections for each database and user.
Max client connections--max-client-conn50010 to 5000Clients the pooler accepts before it refuses new ones.
Not in the dashboard--instances11 to 3Pooler instances.

Two modes are available:

  • Transaction: The pooler assigns a server connection for each transaction. This mode fits most apps.
  • Session: The pooler assigns a server connection for each client. Use this mode if the app uses LISTEN or session settings.
  1. Open the database.
  2. Go to Settings > Connection pooler.
  3. Turn off Pool connections.

Orchard deletes the pooler. Connections that use its address fail, so point all apps back to the database host first.