@porulle/adapter-postgres 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @porulle/adapter-postgres
+
+The PostgreSQL `DatabaseAdapter` for `@porulle/core`. Drizzle on `postgres-js`. The only database backend Porulle ships today.
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+import { postgresAdapter } from "@porulle/adapter-postgres";
+
+export default defineConfig({
+  databaseAdapter: postgresAdapter({
+    connectionString: process.env.DATABASE_URL!,
+    pool: {
+      max: 20,
+      idleTimeout: 30,
+      connectTimeout: 10,
+      statementTimeoutMs: 30_000,
+      lockTimeoutMs: 10_000,
+      pooled: false,        // set true behind pgbouncer / pgcat / Fly MPG
+    },
+  }),
+  // …
+});
+```
+
+## `pooled: true` — when to set it
+
+If your `DATABASE_URL` points at a **transaction-mode pooler** (pgbouncer, pgcat, Fly Managed Postgres), set `pooled: true`. The pooler rejects libpq startup parameters like `statement_timeout` — when `pooled` is on, the adapter skips them. Set the timeouts on the DB role instead:
+
+```sql
+ALTER ROLE app SET statement_timeout = '30s';
+ALTER ROLE app SET lock_timeout = '10s';
+```
+
+Direct PostgreSQL connections (no pooler) leave `pooled: false` (the default) so the adapter sets the timeouts per-session.
+
+## What it does
+
+- Opens a `postgres-js` connection pool with the given options.
+- Wraps it in Drizzle (`drizzle-orm/postgres-js`).
+- Implements `DatabaseAdapter` from `@porulle/core` — `transaction(fn)` honours nested transactions correctly.
+
+## What it doesn't do
+
+- No automatic migrations. Use `bunx drizzle-kit push` (dev) or `bunx drizzle-kit migrate` (prod) — see the CLI's `migrate` command.
+- No connection retry on cold start. The kernel surfaces the error; redeploy or your platform's healthcheck handles it.
+
+## See also
+
+- [Root README — Quick Start](../../../README.md#quick-start)
+- [`SECURITY.md`](../../../SECURITY.md) — multi-tenant org-scoping is enforced at the repo layer; this adapter is the substrate

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import type { DatabaseAdapter } from "@porulle/core";
+export interface PostgresPoolOptions {
+    /** Maximum number of connections in the pool. Default: 20. */
+    max?: number;
+    /** Seconds a connection can idle before being closed. Default: 30. */
+    idleTimeout?: number;
+    /** Seconds to wait for a connection before throwing. Default: 10. */
+    connectTimeout?: number;
+    /**
+     * Maximum time (ms) any single SQL statement can run before PostgreSQL kills it.
+     * Default: 30000. Set to 0 to disable.
+     *
+     * NOTE: this is sent as a libpq startup parameter, which transaction-mode
+     * poolers (pgbouncer, pgcat, Fly Managed Postgres' pooler) reject as an
+     * "unsupported startup parameter". When `pooled: true` is set we skip the
+     * startup parameter — set the timeouts on the DB role instead, e.g.
+     * `ALTER ROLE app SET statement_timeout = '30s';`
+     */
+    statementTimeoutMs?: number;
+    /**
+     * Maximum time (ms) to wait for a row lock. Default: 10000. Same pooler
+     * caveat as `statementTimeoutMs` — skipped when `pooled: true`.
+     */
+    lockTimeoutMs?: number;
+    /**
+     * Set to true when connecting through a transaction-mode pooler
+     * (pgbouncer, pgcat, Fly Managed Postgres). Skips startup parameters that
+     * poolers reject. Defaults to false (assumes a direct PG connection).
+     */
+    pooled?: boolean;
+}
+export interface PostgresAdapterOptions {
+    connectionString: string;
+    /** Connection pool tuning. Defaults are production-reasonable. */
+    pool?: PostgresPoolOptions;
+}
+export type PostgresDrizzleClient = ReturnType<typeof drizzle>;
+export type PostgresDatabaseAdapter = DatabaseAdapter<PostgresDrizzleClient, unknown>;
+export declare function postgresAdapter(options: PostgresAdapterOptions): PostgresDatabaseAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC/D,MAAM,MAAM,uBAAuB,GAAG,eAAe,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;AAEtF,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,uBAAuB,CAgCxF"}

package/dist/index.js

@@ -0,0 +1,32 @@
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+export function postgresAdapter(options) {
+    const pool = options.pool ?? {};
+    const statementTimeout = pool.statementTimeoutMs ?? 30_000;
+    const lockTimeout = pool.lockTimeoutMs ?? 10_000;
+    const pooled = pool.pooled ?? false;
+    const client = postgres(options.connectionString, {
+        max: pool.max ?? 20,
+        idle_timeout: pool.idleTimeout ?? 30,
+        connect_timeout: pool.connectTimeout ?? 10,
+        prepare: false,
+        // Direct PG connections accept these as startup parameters. Pooled
+        // connections reject them — set timeouts via `ALTER ROLE ... SET` instead.
+        ...(pooled
+            ? {}
+            : {
+                connection: {
+                    statement_timeout: String(statementTimeout),
+                    lock_timeout: String(lockTimeout),
+                },
+            }),
+    });
+    const db = drizzle(client);
+    return {
+        provider: "postgresql",
+        db,
+        async transaction(fn) {
+            return db.transaction(async (tx) => fn(tx));
+        },
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@porulle/adapter-postgres",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@porulle/core": "workspace:*",
+    "drizzle-orm": "^0.45.1",
+    "postgres": "^3.4.7"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "The PostgreSQL DatabaseAdapter for @porulle/core. Drizzle on postgres-js. The only database backend Porulle ships today.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/adapters/adapter-postgres"
+  },
+  "author": "Porulle contributors"
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+import type { DatabaseAdapter } from "@porulle/core";
+
+export interface PostgresPoolOptions {
+  /** Maximum number of connections in the pool. Default: 20. */
+  max?: number;
+  /** Seconds a connection can idle before being closed. Default: 30. */
+  idleTimeout?: number;
+  /** Seconds to wait for a connection before throwing. Default: 10. */
+  connectTimeout?: number;
+  /**
+   * Maximum time (ms) any single SQL statement can run before PostgreSQL kills it.
+   * Default: 30000. Set to 0 to disable.
+   *
+   * NOTE: this is sent as a libpq startup parameter, which transaction-mode
+   * poolers (pgbouncer, pgcat, Fly Managed Postgres' pooler) reject as an
+   * "unsupported startup parameter". When `pooled: true` is set we skip the
+   * startup parameter — set the timeouts on the DB role instead, e.g.
+   * `ALTER ROLE app SET statement_timeout = '30s';`
+   */
+  statementTimeoutMs?: number;
+  /**
+   * Maximum time (ms) to wait for a row lock. Default: 10000. Same pooler
+   * caveat as `statementTimeoutMs` — skipped when `pooled: true`.
+   */
+  lockTimeoutMs?: number;
+  /**
+   * Set to true when connecting through a transaction-mode pooler
+   * (pgbouncer, pgcat, Fly Managed Postgres). Skips startup parameters that
+   * poolers reject. Defaults to false (assumes a direct PG connection).
+   */
+  pooled?: boolean;
+}
+
+export interface PostgresAdapterOptions {
+  connectionString: string;
+  /** Connection pool tuning. Defaults are production-reasonable. */
+  pool?: PostgresPoolOptions;
+}
+
+export type PostgresDrizzleClient = ReturnType<typeof drizzle>;
+export type PostgresDatabaseAdapter = DatabaseAdapter<PostgresDrizzleClient, unknown>;
+
+export function postgresAdapter(options: PostgresAdapterOptions): PostgresDatabaseAdapter {
+  const pool = options.pool ?? {};
+
+  const statementTimeout = pool.statementTimeoutMs ?? 30_000;
+  const lockTimeout = pool.lockTimeoutMs ?? 10_000;
+  const pooled = pool.pooled ?? false;
+
+  const client = postgres(options.connectionString, {
+    max: pool.max ?? 20,
+    idle_timeout: pool.idleTimeout ?? 30,
+    connect_timeout: pool.connectTimeout ?? 10,
+    prepare: false,
+    // Direct PG connections accept these as startup parameters. Pooled
+    // connections reject them — set timeouts via `ALTER ROLE ... SET` instead.
+    ...(pooled
+      ? {}
+      : {
+          connection: {
+            statement_timeout: String(statementTimeout),
+            lock_timeout: String(lockTimeout),
+          } as Record<string, string>,
+        }),
+  });
+  const db = drizzle(client);
+
+  return {
+    provider: "postgresql",
+    db,
+    async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+      return db.transaction(async (tx) => fn(tx));
+    },
+  };
+}