Docs updates (#3622)

* Add docs for

* Add docs for max uses

* Clean up casing and grammar in comments

* Add more docs on pool sizing

* Grammar

* Add better footer

* Final updates

Author: brianc

docs/pages/apis/pool.mdx

@@ -16,28 +16,28 @@ The pool is initially created empty and will create new clients lazily as they a
 
 ```ts
 type Config = {
-  // all valid client config options are also valid here
-  // in addition here are the pool specific configuration parameters:
+  // All valid client config options are also valid here.
+  // In addition here are the pool specific configuration parameters:
 
-  // number of milliseconds to wait before timing out when connecting a new client
-  // by default this is 0 which means no timeout
+  // Number of milliseconds to wait before timing out when connecting a new client.
+  // By default this is 0 which means no timeout.
   connectionTimeoutMillis?: number
 
-  // number of milliseconds a client must sit idle in the pool and not be checked out
-  // before it is disconnected from the backend and discarded
-  // default is 10000 (10 seconds) - set to 0 to disable auto-disconnection of idle clients
+  // Number of milliseconds a client must sit idle in the pool and not be checked out
+  // before it is disconnected from the backend and discarded.
+  // Default is 10000 (10 seconds) - set to 0 to disable auto-disconnection of idle clients.
   idleTimeoutMillis?: number
 
-  // maximum number of clients the pool should contain
-  // by default this is set to 10.  There is some nuance to setting the maximum size of your pool.
-  // see https://node-postgres.com/guides/pool-sizing for more information
+  // Maximum number of clients the pool should contain.
+  // By default this is set to 10. There is some nuance to setting the maximum size of your pool.
+  // See https://node-postgres.com/guides/pool-sizing for more information.
   max?: number
 
-  // minimum number of clients the pool should hold on to and _not_ destroy with the idleTimeoutMillis
-  // this can be useful if you get very bursty traffic and want to keep a few clients around.
-  // note: current the pool will not automatically create and connect new clients up to the min, it will
+  // Minimum number of clients the pool should hold on to and _not_ destroy with the idleTimeoutMillis.
+  // This can be useful if you get very bursty traffic and want to keep a few clients around.
+  // Note: currently the pool will not automatically create and connect new clients up to the min, it will
   // only not evict and close clients except those which exceed the min count.
-  // the default is 0 which disables this behavior.
+  // The default is 0 which disables this behavior.
   min?: number
 
   // Default behavior is the pool will keep clients open & connected to the backend
@@ -47,15 +47,28 @@ type Config = {
   //
   // Setting `allowExitOnIdle: true` in the config will allow the node event loop to exit
   // as soon as all clients in the pool are idle, even if their socket is still open
-  // to the postgres server.  This can be handy in scripts & tests
+  // to the postgres server. This can be handy in scripts & tests
   // where you don't want to wait for your clients to go idle before your process exits.
   allowExitOnIdle?: boolean
 
+  // Number of times a client can be checked out from the pool before it is
+  // disconnected and a new client is created in its place.
+  // The default is Infinity which means a client will never be automatically destroyed
+  // outside of other lifecycle events like manually removing it, it timing out due to idleness, etc.
+  maxUses?: number
+
   // Sets a max overall life for the connection.
   // A value of 60 would evict connections that have been around for over 60 seconds,
   // regardless of whether they are idle. It's useful to force rotation of connection pools through
-  // middleware so that you can rotate the underlying servers. The default is disabled (value of zero)
+  // middleware so that you can rotate the underlying servers. The default is disabled (value of zero).
   maxLifetimeSeconds?: number
+
+  // Called once when a new client is created, before it is made available to the pool.
+  // The client is fully connected and queryable at this point.
+  // Can be a regular function or an async function.
+  // If the function throws or returns a promise that rejects, the client is destroyed
+  // and the error is returned to the caller requesting the connection.
+  onConnect?: (client: Client) => void | Promise<void>
 }
 ```
 
@@ -70,7 +83,19 @@ const pool = new Pool({
   max: 20,
   idleTimeoutMillis: 30000,
   connectionTimeoutMillis: 2000,
-  maxLifetimeSeconds: 60
+  maxLifetimeSeconds: 60,
+})
+```
+
+example using `onConnect` to run setup commands on each new client:
+
+```js
+import { Pool } from 'pg'
+
+const pool = new Pool({
+  onConnect: async (client) => {
+    await client.query('SET search_path TO my_schema')
+  },
 })
 ```
 

docs/pages/features/queries.mdx

@@ -26,7 +26,7 @@ console.log(res.rows[0])
 // { name: 'brianc', email: 'brian.m.carlson@gmail.com' }
 ```
 
-<div class="alert alert-warning">
+<div className="alert alert-warning">
   PostgreSQL does not support parameters for identifiers. If you need to have dynamic database, schema, table, or column names (e.g. in DDL statements) use [pg-format](https://www.npmjs.com/package/pg-format) package for handling escaping these values to ensure you do not have SQL injection!
 </div>
 
@@ -99,8 +99,8 @@ console.log(res.rows[0])
 
 In the above example the first time the client sees a query with the name `'fetch-user'` it will send a 'parse' request to the PostgreSQL server & execute the query as normal. The second time, it will skip the 'parse' request and send the _name_ of the query to the PostgreSQL server.
 
-<div class='message is-warning'>
-  <div class='message-body'>
+<div className='message is-warning'>
+  <div className='message-body'>
 Be careful not to fall into the trap of premature optimization.  Most of your queries will likely not benefit much, if at all, from using prepared statements.  This is a somewhat "power user" feature of PostgreSQL that is best used when you know how to use it - namely with very complex queries with lots of joins and advanced operations like union and switch statements.  I rarely use this feature in my own apps unless writing complex aggregate queries for reports and I know the reports are going to be executed very frequently.
   </div>
 </div>

docs/pages/guides/pool-sizing.md

@@ -16,10 +16,22 @@ In this situation, I'd probably set the `max` to 20 or 25. This lets you have pl
 
 If the number of instances of your services which connect to your database is more dynamic and based on things like load, auto-scaling containers, or running in cloud-functions, you need to be a bit more thoughtful about what your max might be. Often in these environments, there will be another database pooling proxy in front of the database like pg-bouncer or the RDS-proxy, etc. I'm not sure how all these function exactly, and they all have some trade-offs, but let's assume you're not using a proxy. Then I'd be pretty cautious about how large you set any individual pool. If you're running an application under pretty serious load where you need dynamic scaling or lots of lambdas spinning up and sending queries, your queries are likely fast and you should be fine setting the `max` to a low value like 10 -- or just leave it alone, since `10` is the default.
 
+### Vercel
+
+If you're running on Vercel with [fluid compute](https://vercel.com/kb/guide/efficiently-manage-database-connection-pools-with-fluid-compute), your serverless functions can handle multiple requests concurrently and stick around between invocations. In this case, you can treat it similarly to a traditional long-lived process and use a default-ish pool size of `10`. The pool will stay warm across requests and you'll get the benefits of connection reuse. You'll probably need to put pgBouncer (or some kind of pooler like what is offered with Supabase, RDS, GCP, etc.) in front of your database, as Vercel worker count can grow quite a bit larger than the number of reasonable max connections Postgres can handle.
+
+### Cloudflare workers
+
+In a fully stateless serverless environment like Cloudflare Workers where your worker is killed, suspended, moved to a new compute node, or shut down at the end of every request, you'll still probably be okay with a pool size `max` of `10`, though you can lower it if you start hitting connection exhaustion limits on your pooler. In Cloudflare the pooler is Hyperdrive, and in my experience it works fantastically with their workers setup. Make sure at the end of your serverless handler, after everything is done, you close and dispose of the pool by calling `pool.end()`. Setting the pool to a size larger than 1 is still recommended, as things like tRPC and other server-side routing & request batching code could result in multiple independent queries executing at the same time. With a pool size of `1` you are turning what is "a few things at once" into all things waiting in line one after another on the one available client in the pool.
+
 ## pg-bouncer, RDS-proxy, etc.
 
 I'm not sure of all the pooling services for Postgres. I haven't used any myself. Throughout the years of working on `pg`, I've addressed issues caused by various proxies behaving differently than an actual Postgres backend. There are also gotchas with things like transactions. On the other hand, plenty of people run these with much success. In this situation, I would just recommend using some small but reasonable `max` value like the default value of `10` as it can still be helpful to keep a few TCP sockets from your services to the Postgres proxy open.
 
 ## Conclusion, tl;dr
 
 It's a bit of a complicated topic and doesn't have much impact on things until you need to start scaling. At that point, your number of connections _still_ probably won't be your scaling bottleneck. It's worth thinking about a bit, but mostly I'd just leave the pool size to the default of `10` until you run into troubles: hopefully you never do!
+
+## Need help?
+
+In my career, this has been the most error-prone thing related to running Postgres & Node, particularly with the differences in various serverless providers (Cloudflare, Vercel, Lambda, etc.) versus more traditional hosting. If you have any questions or need help, please don't hesitate to email me at [brian.m.carlson@gmail.com](mailto:brian.m.carlson@gmail.com) or reach out on GitHub.

docs/theme.config.js

@@ -15,7 +15,20 @@ export default {
     next: true,
   },
   footer: {
-    text: `MIT ${new Date().getFullYear()} © Brian Carlson.`,
+    content: (
+      <span>
+        As of 2026-03-01 I am taking a break from the workforce to focus entirely on this project! Please consider{' '}
+        <a
+          href="https://github.com/sponsors/brianc"
+          target="_blank"
+          rel="noopener noreferrer"
+          style={{ textDecoration: 'underline' }}
+        >
+          sponsoring this work on GitHub
+        </a>
+        !
+      </span>
+    ),
   },
   editLink: {
     text: 'Edit this page on GitHub',
@@ -55,6 +68,21 @@ l-161 -22 -94 41 c-201 87 -327 113 -533 112 -77 -1 -166 -7 -196 -13z m-89
   chat: {
     link: 'https://discord.gg/2afXp5vUWm',
   },
+  navbar: {
+    extraContent: (
+      <a
+        href="https://github.com/sponsors/brianc"
+        target="_blank"
+        rel="noopener noreferrer"
+        title="Sponsor this project"
+        className="_p-2 _text-current"
+      >
+        <svg viewBox="0 0 24 24" width="24" height="24" fill="#db61a2">
+          <path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z" />
+        </svg>
+      </a>
+    ),
+  },
   head: (
     <>
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />