[world-postgres] Add maxPoolSize config for graphile (#1527)

Co-authored-by: Peter Wielander <mittgfu@gmail.com>

Author: NathanColosimo

.changeset/large-ideas-float.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-postgres": patch
+---
+
+Add maxPoolSize configuration

docs/content/docs/deploying/world/postgres-world.mdx

@@ -160,6 +160,12 @@ Prefix for graphile-worker queue job names. Useful when sharing a database betwe
 
 Number of concurrent workers polling for jobs. Default: `10`
 
+### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
+
+Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: `10`
+
+For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
+
 ### Programmatic configuration
 
 {/* @skip-typecheck: incomplete code sample */}
@@ -170,6 +176,7 @@ const world = createWorld({
   connectionString: "postgres://user:password@host:5432/database",
   jobPrefix: "myapp_",
   queueConcurrency: 20,
+  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
 });
 ```
 

packages/world-postgres/README.md

@@ -35,6 +35,9 @@ export WORKFLOW_POSTGRES_JOB_PREFIX="myapp"
 
 # Optional: Worker concurrency (default: 10)
 export WORKFLOW_POSTGRES_WORKER_CONCURRENCY="10"
+
+# Optional: Internal pg.Pool max size (default: 10)
+export WORKFLOW_POSTGRES_MAX_POOL_SIZE="10"
 ```
 
 ### Programmatic Usage
@@ -49,6 +52,7 @@ const world = createWorld({
   connectionString: "postgres://username:password@localhost:5432/database",
   jobPrefix: "myapp", // optional
   queueConcurrency: 10, // optional
+  maxPoolSize: 10, // optional, overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE when `pool` is omitted
 });
 
 // Or pass an existing pg.Pool (shared with your app Drizzle, etc.); `world.close()` will not end it.
@@ -62,6 +66,7 @@ const worldFromPool = createWorld({ pool });
 | Option             | Type      | Default                                                                                | Description                                                                                          |
 | ------------------ | --------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `connectionString` | `string`  | `process.env.WORKFLOW_POSTGRES_URL` or `'postgres://world:world@localhost:5432/world'` | Used only when `pool` is omitted, to construct an internal pool                                      |
+| `maxPoolSize`      | `number`  | `process.env.WORKFLOW_POSTGRES_MAX_POOL_SIZE` or `pg.Pool` default (`10`)              | Optional. Sets the internal `pg.Pool` max size when `createWorld()` creates the pool                |
 | `pool`             | `pg.Pool` | —                                                                                      | Optional. When set, used for Drizzle, Graphile Worker, and stream writes. `world.close()` does not end it. |
 | `jobPrefix`        | `string`  | `process.env.WORKFLOW_POSTGRES_JOB_PREFIX`                                             | Optional prefix for queue job names                                                                  |
 | `queueConcurrency` | `number`  | `10`                                                                                   | Number of concurrent active step executions per process                                              |
@@ -74,6 +79,11 @@ const worldFromPool = createWorld({ pool });
 | `WORKFLOW_POSTGRES_URL`                | PostgreSQL connection string                                 | `'postgres://world:world@localhost:5432/world'` |
 | `WORKFLOW_POSTGRES_JOB_PREFIX`         | Prefix for queue job names                                   | -                                               |
 | `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | Number of concurrent workers                                 | `10`                                            |
+| `WORKFLOW_POSTGRES_MAX_POOL_SIZE`      | Internal `pg.Pool` max size                                  | `10`                                            |
+
+When `pool` is omitted, `maxPoolSize` precedence is: `createWorld({ maxPoolSize })`, then `WORKFLOW_POSTGRES_MAX_POOL_SIZE`, then the `pg.Pool` default.
+
+For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
 
 ## Database Setup
 

packages/world-postgres/src/config.ts

@@ -1,8 +1,8 @@
 import type { Pool } from 'pg';
 
 type PgConnectionConfig =
-  | { connectionString: string; pool?: undefined }
-  | { pool: Pool; connectionString?: undefined };
+  | { connectionString: string; maxPoolSize?: number; pool?: undefined }
+  | { pool: Pool; connectionString?: undefined; maxPoolSize?: undefined };
 
 export type PostgresWorldConfig = PgConnectionConfig & {
   jobPrefix?: string;

packages/world-postgres/src/index.ts

@@ -20,6 +20,15 @@ function createStorage(drizzle: Drizzle): Storage {
   };
 }
 
+function getDefaultMaxPoolSize(): number | undefined {
+  const parsed = parseInt(
+    process.env.WORKFLOW_POSTGRES_MAX_POOL_SIZE || '',
+    10
+  );
+
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 export function createWorld(
   config: PostgresWorldConfig = {
     connectionString:
@@ -31,12 +40,14 @@ export function createWorld(
       10,
   }
 ): World & { start(): Promise<void> } {
+  const maxPoolSize = config.maxPoolSize ?? getDefaultMaxPoolSize();
   const pool =
     config.pool ||
     new Pool({
       connectionString:
         config.connectionString ||
         'postgres://world:world@localhost:5432/world',
+      ...(maxPoolSize !== undefined ? { max: maxPoolSize } : {}),
     });
 
   const drizzle = createClient(pool);