---
title: "Turn the connection pooler on (transaction mode by default) or change its settings"
method: PUT
path: "/databases/{databaseId}/pooler"
tags: ["Databases"]
---

# Turn the connection pooler on (transaction mode by default) or change its settings

`PUT /databases/{databaseId}/pooler`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/databases/{databaseId}/pooler`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Path parameters

- `databaseId` string, uuid, required

## Request body

- object
  - `mode` 'transaction' | 'session'
  - `defaultPoolSize` integer
  - `maxClientConnections` integer

## Response `200`

Pooler (provisioning)

- object
  - `databaseId` string, uuid, required
  - `supported` boolean, required: connection pooling exists for PostgreSQL only
  - `enabled` boolean, required
  - `status` 'disabled' | 'provisioning' | 'running' | 'error', required
  - `statusDetail` string, nullable, required
  - `mode` 'transaction' | 'session', required: transaction (default): a server connection per transaction; session: per client connection
  - `defaultPoolSize` integer, required: server connections to PostgreSQL per database/user pair
  - `maxClientConnections` integer, required: client connections PgBouncer accepts
  - `host` string, nullable, required: internal host of the pooler, reachable from the organization's projects
  - `port` integer, nullable, required
  - `pooledUrl` string, nullable, required: pooled connection URL; masked unless revealed (databases:reveal and ?reveal=true)
  - `directUrl` string, nullable, required: the database's direct connection URL (migrations, LISTEN/NOTIFY, long sessions); masked unless revealed
  - `notes` string[], required: what to keep in mind in the chosen mode
  - `updatedAt` string, nullable, required: ISO-8601 timestamp

## Other responses

- `400`: Invalid request (code invalid_request)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Conflicting state (code conflict); details.preparing = the database tools are starting, retry after details.retryAfterSeconds
- `429`: Too many requests (code rate_limited); see Retry-After
- `501`: Not available on this server (code not_configured)
- `503`: Hosting engine unavailable (code provider_unavailable)

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)