Skip to content

Instantly share code, notes, and snippets.

@spraints
Created April 16, 2026 17:02
Show Gist options
  • Select an option

  • Save spraints/d6444bc9e211a1d997391da818f3e137 to your computer and use it in GitHub Desktop.

Select an option

Save spraints/d6444bc9e211a1d997391da818f3e137 to your computer and use it in GitHub Desktop.
claude made me a picture of pgbouncer server state transitions

PgBouncer Server Connection States

stateDiagram-v2
    [*] --> new : launch_new_connection()

    new --> idle : login/auth completed
    new --> active : restored from takeover (already linked to client)

    idle --> active : assigned to waiting client
    idle --> used : idle timeout, needs check_query

    active --> idle : released (no reset needed)
    active --> tested : released with reset_query
    active --> used : released with check_query (deprecated)
    active --> being_canceled : cancel request pending

    used --> tested : janitor schedules check_query
    used --> idle : no check needed

    tested --> idle : reset/check query succeeded

    being_canceled --> idle : all cancel requests completed

    active_cancel --> being_canceled : cancel sent, more cancels pending
    active_cancel --> active : replication cancel, relinked to client

    new --> [*] : disconnect
    idle --> [*] : disconnect / timeout
    active --> [*] : disconnect
    used --> [*] : disconnect
    tested --> [*] : disconnect / check failed
    being_canceled --> [*] : disconnect
    active_cancel --> [*] : disconnect
Loading

State definitions

State Description
new TCP connect and PostgreSQL authentication handshake in progress.
idle Connected to PostgreSQL, not assigned to any client. Ready to be handed out.
active Linked to a client, actively forwarding query traffic.
used Recently released from a client, awaiting a health-check query before reuse.
tested Running a health-check (server_check_query) or reset query (server_reset_query). Moves to idle on success.
active_cancel Actively sending a cancel request to PostgreSQL (e.g. client disconnected mid-query).
being_canceled Has a cancel request in flight against it from another connection in active_cancel state.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment