@viktorbarzin/pg 0.1.0 → 1.1.0

package/README.md

@@ -2,9 +2,13 @@
 
 Drizzle on Bun's built-in SQL client for an app on a shared Postgres:
 
-- a pool of at most 4 (`APP_POOL_MAX`; with the realtime LISTEN connection,
-  5 per pod) that reads the password from a mounted file on every new
-  connection, so a rotated password does not break new connections;
+- a pool of at most 4 by default (`APP_POOL_MAX`; with the realtime LISTEN
+  connection, 5 per pod), or the size you pass, that reads the password from
+  a mounted file on every new connection, so a rotated password does not
+  break new connections;
+- the per-pod connection budget for a role with a connection limit: half the
+  limit (a rollout overlaps two pods), and realtime only when that leaves at
+  least 2;
 - migrations under a session `pg_advisory_lock` (drizzle's migrator takes
   none), a migrate CLI for an init container, and throwaway test databases.
 
@@ -23,11 +27,37 @@ await pool.getDb().select().from(items);
 process.exitCode = await runMigrateCli({ lockKey: migrationLockKey("myapp") });
 ```
 
+On a platform that limits the role's connections
+(`CLOUD_DATABASE_CONNECTION_LIMIT`), size the pool from the budget and keep
+realtime off when it says so:
+
+<!-- typecheck-preamble
+import { pgTable, text } from "drizzle-orm/pg-core";
+const items = pgTable("items", { title: text("title") });
+const schema = { items };
+-->
+```ts
+import { connectionBudgetFromEnv, createPool, pgSettingsFromEnv } from "@viktorbarzin/pg";
+
+const budget = connectionBudgetFromEnv(); // limit 2: { perPod: 1, poolMax: 1, realtime: false }
+export const pool = createPool({ settings: () => pgSettingsFromEnv(), schema, max: budget.poolMax });
+export const realtimeOn = budget.realtime;
+```
+
+| Limit (Cloud Size) | Per pod | Pool | Realtime LISTEN |
+|---|---|---|---|
+| none | 5 | 4 | 1 |
+| 2 (nano) | 1 | 1 | off |
+| 4 (small) | 2 | 1 | 1 |
+| 8 (medium) | 4 | 3 | 1 |
+
 | Export | |
 |---|---|
 | `pgSettingsFromEnv(env?)` | `DATABASE_URL` (required) and `DATABASE_PASSWORD_FILE` |
 | `createSqlClient(settings, { max?, idleTimeout? })` | a Bun `SQL` client; idle connections kept by default |
-| `createPool({ settings, schema, key? })` | lazy, once per process: `getDb()`, `getClient()`, `close()` |
+| `createPool({ settings, schema, key?, max? })` | lazy, once per process: `getDb()`, `getClient()`, `close()`; `max` (a number or a function, default `APP_POOL_MAX`) is read when the pool opens |
+| `connectionBudget(limit)` | `{ perPod, poolMax, realtime }`: `floor(limit / 2)` per pod, realtime when that is at least 2; `null` gives the default 4 + 1; a limit under 2 throws |
+| `connectionBudgetFromEnv(env?)` | the same for `CLOUD_DATABASE_CONNECTION_LIMIT` (unset: no limit; not a whole number: throws) |
 | `migrationLockKey(appName)` | the first 8 bytes of sha256(`migrate:<app>`) as a signed int64 |
 | `runMigrations(client, opts)` | `{ applied }`; the client must have `max: 1`; `beforeMigrate` runs under the lock |
 | `runMigrateCli({ lockKey, beforeMigrate?, env? })` | reads `DATABASE_URL`, `DATABASE_PASSWORD_FILE`, `MIGRATIONS_DIR` (default `./drizzle`); returns the exit code |

package/dist/index.d.ts

@@ -7,8 +7,32 @@ export interface PgSettings {
     /** DATABASE_PASSWORD_FILE: a mounted file with the rotated password; null uses the URL's password. */
     passwordFile: string | null;
 }
-/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. */
+/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. The default pool size. */
 export declare const APP_POOL_MAX = 4;
+/** How many Postgres connections one app pod may hold, and how it spends them. */
+export interface ConnectionBudget {
+    /** Every connection the pod may hold: the pool plus the LISTEN connection. */
+    perPod: number;
+    /** The pool's `max`. */
+    poolMax: number;
+    /** Whether the pod may hold a realtime LISTEN connection (one of perPod). */
+    realtime: boolean;
+}
+/**
+ * The per-pod budget for a role whose connection limit is `limit` (null: no
+ * limit given, the default pool of APP_POOL_MAX plus one LISTEN connection).
+ *
+ * A pod gets half the limit, rounded down: during a rollout a surge pod runs
+ * beside the old one, and the migrate container connects while the old pod
+ * still holds its connections. Realtime takes one of them only when at least
+ * two are left; with one, realtime is off and the pool has it.
+ */
+export declare function connectionBudget(limit: number | null): ConnectionBudget;
+/**
+ * connectionBudget() for the platform contract's
+ * CLOUD_DATABASE_CONNECTION_LIMIT (a whole number; unset or empty: no limit).
+ */
+export declare function connectionBudgetFromEnv(env?: Record<string, string | undefined>): ConnectionBudget;
 /**
  * The platform env contract the Terraform app module sets: DATABASE_URL
  * (required) and DATABASE_PASSWORD_FILE.
@@ -27,12 +51,14 @@ export interface Pool<TSchema extends Record<string, unknown>> {
 }
 /**
  * The app's pool, once per process (keyed by `key`): lazy, so nothing
- * connects until the first getDb() or getClient().
+ * connects until the first getDb() or getClient(). `max` (default
+ * APP_POOL_MAX) is read when the pool opens.
  */
 export declare function createPool<TSchema extends Record<string, unknown>>(opts: {
     settings: () => PgSettings;
     schema: TSchema;
     key?: string;
+    max?: number | (() => number);
 }): Pool<TSchema>;
 /** A per-app advisory-lock key: the first 8 bytes of sha256(`migrate:<app>`) as a signed int64. */
 export declare function migrationLockKey(appName: string): bigint;

package/dist/index.js

@@ -4,8 +4,10 @@
  *
  * - The password comes from DATABASE_PASSWORD_FILE, read each time a new
  *   connection opens, so a Vault rotation does not break new connections.
- * - An app pod keeps at most 5 connections: the pool (APP_POOL_MAX = 4) plus
- *   the realtime LISTEN connection. The migrate entrypoint uses 1.
+ * - An app pod keeps at most 5 connections by default: the pool
+ *   (APP_POOL_MAX = 4) plus the realtime LISTEN connection. The migrate
+ *   entrypoint uses 1. A platform with a smaller per-role connection limit
+ *   sizes the pool with `max` and connectionBudget().
  * - Nothing connects at import time: the first getDb() call opens the pool.
  * - drizzle-orm's migrator takes no lock of its own, so runMigrations holds a
  *   session-level pg_advisory_lock around it.
@@ -17,8 +19,38 @@ import { processSingleton } from "@viktorbarzin/runtime";
 import { SQL } from "bun";
 import { drizzle } from "drizzle-orm/bun-sql";
 import { migrate } from "drizzle-orm/bun-sql/migrator";
-/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. */
+/** ADR budget: 5 connections per pod, one of them the realtime LISTEN. The default pool size. */
 export const APP_POOL_MAX = 4;
+/**
+ * The per-pod budget for a role whose connection limit is `limit` (null: no
+ * limit given, the default pool of APP_POOL_MAX plus one LISTEN connection).
+ *
+ * A pod gets half the limit, rounded down: during a rollout a surge pod runs
+ * beside the old one, and the migrate container connects while the old pod
+ * still holds its connections. Realtime takes one of them only when at least
+ * two are left; with one, realtime is off and the pool has it.
+ */
+export function connectionBudget(limit) {
+    if (limit === null)
+        return { perPod: APP_POOL_MAX + 1, poolMax: APP_POOL_MAX, realtime: true };
+    const perPod = Number.isInteger(limit) ? Math.floor(limit / 2) : 0;
+    if (perPod < 1)
+        throw new Error(`a connection limit of ${limit} leaves no connection per pod (at least 2 needed)`);
+    const realtime = perPod >= 2;
+    return { perPod, poolMax: realtime ? perPod - 1 : perPod, realtime };
+}
+/**
+ * connectionBudget() for the platform contract's
+ * CLOUD_DATABASE_CONNECTION_LIMIT (a whole number; unset or empty: no limit).
+ */
+export function connectionBudgetFromEnv(env = process.env) {
+    const raw = nonEmpty(env.CLOUD_DATABASE_CONNECTION_LIMIT);
+    if (raw === null)
+        return connectionBudget(null);
+    if (!/^[0-9]+$/.test(raw))
+        throw new Error(`CLOUD_DATABASE_CONNECTION_LIMIT must be a whole number (got "${raw}")`);
+    return connectionBudget(Number(raw));
+}
 function nonEmpty(value) {
     return value === undefined || value.trim() === "" ? null : value.trim();
 }
@@ -48,7 +80,8 @@ export function createSqlClient(settings, opts = {}) {
 }
 /**
  * The app's pool, once per process (keyed by `key`): lazy, so nothing
- * connects until the first getDb() or getClient().
+ * connects until the first getDb() or getClient(). `max` (default
+ * APP_POOL_MAX) is read when the pool opens.
  */
 export function createPool(opts) {
     const slot = processSingleton(opts.key ?? "db.pool", () => ({
@@ -56,7 +89,12 @@ export function createPool(opts) {
     }));
     const open = () => {
         if (slot.shared === null) {
-            const client = createSqlClient(opts.settings());
+            const max = typeof opts.max === "function"
+                ? opts.max()
+                : (opts.max ?? APP_POOL_MAX);
+            if (!Number.isInteger(max) || max < 1)
+                throw new Error(`pool max must be a whole number >= 1 (got ${max})`);
+            const client = createSqlClient(opts.settings(), { max });
             slot.shared = { client, db: drizzle({ client, schema: opts.schema }) };
         }
         return slot.shared;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@viktorbarzin/pg",
-	"version": "0.1.0",
+	"version": "1.1.0",
 	"description": "Drizzle on Bun SQL: a small pool that re-reads a rotated password file, migrations under an advisory lock, a migrate CLI and throwaway test databases.",
 	"license": "MIT",
 	"type": "module",
@@ -38,13 +38,13 @@
 		"test": "bun test"
 	},
 	"peerDependencies": {
-		"@viktorbarzin/log": "^0.1.0",
-		"@viktorbarzin/runtime": "^0.1.0",
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
 		"drizzle-orm": "^0.45.0"
 	},
 	"devDependencies": {
-		"@viktorbarzin/log": "^0.1.0",
-		"@viktorbarzin/runtime": "^0.1.0",
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
 		"drizzle-orm": "^0.45.4"
 	}
 }