Skip to content
Atlas, your robot learning host

Interim portrait

Atlas · Foundations connection-pool

Hello, little human. I am Atlas. One useful idea is plenty for a beginning. Read the explanation, then explore an example.

Choose your robot No recording yet · text complete
concept for junior engineers
  • database

Connection Pool

A connection pool manages a limited collection of database connections for checkout and reuse; when no usable connection or spare capacity is available, acquisition waits or fails under the pool’s policy.

Tune in, human.

Reviewed videos and Shorts

Captions requested · no autoplay

Finding reviewed videos…

    Keep the useful bits, human.

    Beginner field notes

    Choose explanation level
    • A connection pool manages channels an application can borrow to talk to a database. It shares reusable connections rather than creating an unlimited supply.
    • A maximum is a cap, not a promise that every slot is already open. The cited pg.Pool starts empty and creates connections lazily.
    • When pg.Pool is full and every client is borrowed, the next acquisition waits for a returned client. An idle client at the cap can still be borrowed.
    See a worked example

    Track two reusable connections and two different waiting exits

    Sample only. Nothing here runs on your computer.

    Example input · do not paste
    OFFLINE Lantern Archive pool. Capacity 2; healthy pre-opened C1,C2 start idle. Each read request needs exactly one exclusive connection; choose the lowest-numbered idle connection. No connection opens, closes, fails or is evicted during the trace; no retries or other writers.
Active waiters are FIFO. A healthy released connection goes immediately to the oldest active waiter. A waiter expires 5 logical units after arrival; expiry is processed before a same-time action, with no active expiry/release tie in this trace. A supplied cancellation removes only a waiting request. Acquisition expiry never cancels running work.
t0: A arrives and takes C1.
t1: B arrives and takes C2.
t2: C arrives and waits.
t3: D arrives and waits.
t4: D is canceled while waiting.
t5: A’s read explicitly completes successfully; A releases C1.
t6: E arrives and waits.
t7: F arrives and waits.
t8: B’s read explicitly completes successfully; B releases C2.
t12: F’s waiting deadline is explicitly reached.
t13: C’s read explicitly completes successfully; C releases C1.
t14: E’s read explicitly completes successfully; E releases C2.
All times are invented integer bookkeeping values, not measured durations or production timeout settings.
    Example output · do not paste
    t0: C1=A; C2 idle; queue empty.
t1: C1=A,C2=B; no idle connection.
t2: queue C, deadline t7.
t3: queue C,D. Both connections remain borrowed.
t4: queue C; canceled D never checks out.
t5: A releases C1; oldest waiter C immediately receives C1, before its waiting deadline.
t6: queue E, deadline t11.
t7: queue E,F; F deadline t12. C is already running, so its former waiting deadline does not cancel it.
t8: B releases C2; E receives C2 before F. Queue F.
t12: F expires without checkout; C1=C,C2=E still running.
t13: C1 becomes idle after C’s given successful completion/release.
t14: C2 becomes idle after E’s given successful completion/release. Both idle; queue empty.
Given completed reads: A,B,C,E; canceled D; wait-expired F. Maximum borrowed: 2; maximum waiting: 2; C waited 3 units and E waited 2; new connections created during this trace: 0.

    Track assignments and waiting identities separately from the explicitly supplied read outcomes. C reuses C1 and E reuses C2. A request that leaves the waiting queue never became a running query in this model. The five-unit rule constrains acquisition waiting, not the duration of an assigned read, and it grants no cancellation behavior in a real driver.

    Visual

    In the stated two-connection trace, A and B initially occupy C1 and C2. Once their explicitly completed reads release those connections, waiting C and E receive the same connections in FIFO order. This is a partial timing illustration, not live database activity.

    The reviewed description and complete diagram source are available here.

    Read the complete diagram source

    This is the source for the reviewed diagram, not a command to run.

    sequenceDiagram
  participant A as Request A
  participant P as Example pool: C1 and C2
  participant C as Waiting request C
  participant E as Waiting request E
  A->>P: t0: check out C1
  Note over P: t1: B checks out C2#59; both busy
  C->>P: t2: wait for a connection
  A->>P: t5: given successful read completion#59; release C1
  P-->>C: Hand off the same C1
  E->>P: t6: wait for a connection
  Note over P: t8: B completes successfully and releases C2
  P-->>E: Hand off C2 to oldest active waiter
    Sources and full explanation

    Notes sources · Beginner

    AI source review · 2026-10-17

    Reviewed explanation

    A database connection pool keeps track of connections an application can borrow, use and return. Reusing a healthy connection can avoid repeating connection setup for each request. It does not reuse the earlier query result, make every operation fast or make connections unlimited. In node-postgres, the checked-out client is the object through which an application uses its borrowed PostgreSQL connection.

    Separate the pool’s total, idle and borrowed connections from the requests waiting to acquire one. A maximum is a cap: a library may create connections lazily and retire idle or broken ones. Reaching the cap is not itself exhaustion if an idle connection can still be checked out. When the cap is reached and all usable connections are borrowed, another acquisition must wait or fail according to the applicable policy. A cap on one pool also does not bound every other pool or process using the database.

    A holder must finish using its connection and perform any required cleanup before returning it safely. Query errors do not remove the need to release or discard the client appropriately. Some libraries handle checkout and release for a single-query convenience operation, while a transaction may need several statements on the same connection. Forgetting to return clients can exhaust a pool; depending on timeout configuration, later acquisitions can fail or keep waiting. This is not a recommendation to increase the maximum as a substitute for finding a leak.

    The cited pg.Pool documents FIFO acquisition waiting when full and busy. Our paper model also chooses FIFO, plus explicitly accepted cancellation and a five-logical-unit acquisition limit. Those cancellation rules are not a claim that pg.Pool provides a particular cancel method. The timeout applies only while waiting for checkout; it is not a query deadline and never cancels a holder’s database work. Every time and completion below is supplied, with no retry, connection failure, eviction, multiplexing or race hidden between rows.

    The example starts with two healthy connections already open. C receives C1 after A’s explicitly successful read and release; E receives C2 after B’s. D withdraws while waiting and F reaches its waiting deadline without a checkout. C and E can hold their connections beyond five units because that acquisition deadline stopped applying when they were assigned. No real database, query, policy, credential or clock is involved, and no later release or query success should be guessed from this finite trace.

    • node-postgres: pg.Pool API

      Maintainer documentation describes lazy creation, bounded pool size, idle versus checked-out clients, FIFO waiting when full and busy, return versus destruction, and exhaustion when clients are not released. Its library/configuration-specific behavior is not a universal pool contract. The example’s cancellation and five-logical-unit deadline are explicitly fictional.

    • node-postgres: Pooling

      Explains reusable database clients, connection-setup work, checkout/use/return and safe release after both success and error. Single-query convenience and transaction scope differ. No fixed connection latency, default capacity, universal pipelining rule or performance guarantee is adopted.

    AI source comparison recorded 2026-10-17. Human learner validation is pending.

    Quick quiz · one question

    Keep pool capacity separate from waiting

    Sample scenario. Pre-opened C1/C2, capacity 2; otherwise the same explicit FIFO/deadline rules. Completing the read and returning its healthy lease are separately supplied in each success-and-release event.

    Given connections
    C1, C2 already open and healthy, with one exclusive borrower each. Lowest-numbered idle selection and FIFO waiting. No new connection, SQL, cached result, failure, retry or hidden work.
    Waiting rule
    5 invented logical units from arrival, only while waiting. Expiry is processed before same-time actions, which run in listed order. Granted reads have no checkout deadline. Cancellation removes only a waiting request. No real clock or timer runs.
    Logical time 0
    A arrives for checkout.
    Logical time 1
    B arrives for checkout.
    Logical time 2
    C arrives for checkout.
    Logical time 3
    D arrives for checkout.
    Logical time 4
    D is canceled while waiting.
    Logical time 5
    A has an explicitly supplied successful read, then returns its healthy connection. Release alone is not evidence of success.
    Logical time 6
    E arrives for checkout.
    Logical time 7
    F arrives for checkout.
    Logical time 8
    B has an explicitly supplied successful read, then returns its healthy connection. Release alone is not evidence of success.
    Logical time 12
    Only advance the stated logical observation.
    Logical time 13
    C has an explicitly supplied successful read, then returns its healthy connection. Release alone is not evidence of success.
    Logical time 14
    E has an explicitly supplied successful read, then returns its healthy connection. Release alone is not evidence of success.

    With two healthy existing connections, trace checkout, reuse, cancellation and timeout. Did any checkout create a new connection, and how long did C and E wait?

    Answers stay on this device.

    Sources and exercise scope
    • node-postgres: pg.Pool API

      Maintainer documentation describes lazy creation, bounded pool size, idle versus checked-out clients, FIFO waiting when full and busy, return versus destruction, and exhaustion when clients are not released. Its library/configuration-specific behavior is not a universal pool contract. The example’s cancellation and five-logical-unit deadline are explicitly fictional.

    • node-postgres: Pooling

      Explains reusable database clients, connection-setup work, checkout/use/return and safe release after both success and error. Single-query convenience and transaction scope differ. No fixed connection latency, default capacity, universal pipelining rule or performance guarantee is adopted.

    Original synthetic exercise. AI comparison against the reviewed lesson recorded on 2026-10-17; the references above state their scope. Human learner validation has not been run. A result here records this attempt; it does not establish mastery.

    Save or adjust this lesson
    Reference notes · file removal and public access

    Robot reference desk

    Understand what can change

    These reviewed public notes are available to everyone. They do not establish that an operation ran or inspect your files, backups or permissions.

    File removal

    Before deleting files: deleting a file can remove it without putting it in Trash or a recycle bin, and recovery is not guaranteed. Check the intended targets and whether a usable backup or recovery option exists before continuing.

    Sources for this note

    Public access

    Before making a resource public: public read access can let anyone view the exposed content, and public write access can allow changes to data. Check the actual audience, exposed content and allowed operations before continuing. This guidance does not inspect or change your permissions.

    Sources for this note

    A link can carry these public reference topics in its fragment. Page scripts, extensions, browser history and copied links can read them. This page attempts to minimize that fragment when JavaScript runs; reloading afterward can lose the selection. No project details or conversation text belong in a lesson link. Privacy details.