feat(store): enhance PostgresStore to support shared pg.Pool instances

- Updated PostgresStoreConfig to accept a preconfigured pg.Pool.
- Added fromPool static method for creating PostgresStore instances from an existing pool.
- Modified connection handling to allow sharing a pool between PostgresStore and PostgresSaver.
- Updated stop method to conditionally close the pool based on ownership.
- Added integration tests for pool sharing functionality.

Author: jadengis

.changeset/add-pool-support-to-postgres-store.md

@@ -0,0 +1,36 @@
+---
+"@langchain/langgraph-checkpoint-postgres": minor
+---
+
+Add support for passing a preconfigured `pg.Pool` to `PostgresStore`, enabling a single connection pool to be shared between `PostgresSaver` and `PostgresStore` for better resource management.
+
+**What changed:**
+
+- `PostgresStoreConfig` now accepts an optional `pool` field for passing a preconfigured `pg.Pool` instance directly. If both `pool` and `connectionOptions` are provided, `pool` takes precedence.
+- Added a new `PostgresStore.fromPool(pool, options?)` static factory method for convenience.
+- When an external pool is provided, `store.stop()` will no longer close the pool — the caller retains ownership of the pool lifecycle.
+
+**Why:**
+
+Previously, `PostgresStore` always created its own internal pool, which meant a server using both a `PostgresSaver` and a `PostgresStore` would hold two separate connection pools. This made it impossible to share connections across use cases and led to unnecessary resource consumption.
+
+**How to update your code:**
+
+```typescript
+import pg from "pg";
+import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
+import { PostgresStore } from "@langchain/langgraph-checkpoint-postgres/store";
+
+// Create a single shared pool
+const pool = new pg.Pool({ connectionString: "postgresql://..." });
+
+// Share it between the saver and the store
+const saver = new PostgresSaver(pool);
+const store = PostgresStore.fromPool(pool);
+
+// Or pass it via the constructor
+const store2 = new PostgresStore({ pool });
+
+await saver.setup();
+await store.setup();
+```

libs/checkpoint-postgres/src/store/index.ts

@@ -54,14 +54,27 @@ export class PostgresStore extends BaseStore {
 
   private ensureTables: boolean;
 
+  private poolOwned: boolean;
+
   constructor(config: PostgresStoreConfig) {
     super();
 
-    // Create connection pool
-    const pool =
-      typeof config.connectionOptions === "string"
-        ? new Pool({ connectionString: config.connectionOptions })
-        : new Pool(config.connectionOptions);
+    // Use the provided pool directly, or create one from connectionOptions.
+    let pool: pg.Pool;
+    if (config.pool) {
+      pool = config.pool;
+      this.poolOwned = false;
+    } else if (config.connectionOptions) {
+      pool =
+        typeof config.connectionOptions === "string"
+          ? new Pool({ connectionString: config.connectionOptions })
+          : new Pool(config.connectionOptions);
+      this.poolOwned = true;
+    } else {
+      throw new Error(
+        'PostgresStoreConfig requires either "pool" or "connectionOptions".'
+      );
+    }
 
     // Initialize core and modules
     this.core = new DatabaseCore(
@@ -186,14 +199,51 @@ export class PostgresStore extends BaseStore {
    */
   static fromConnString(
     connectionString: string,
-    options?: Omit<PostgresStoreConfig, "connectionOptions">
+    options?: Omit<PostgresStoreConfig, "pool" | "connectionOptions">
   ): PostgresStore {
     return new PostgresStore({
       connectionOptions: connectionString,
       ...options,
     });
   }
 
+  /**
+   * Creates a PostgresStore instance from a preconfigured pg.Pool.
+   *
+   * This enables sharing a single connection pool between PostgresSaver and
+   * PostgresStore for better resource management.
+   *
+   * The pool will NOT be closed when the store is stopped -- the caller
+   * retains ownership of the pool lifecycle.
+   *
+   * @param pool - A preconfigured pg.Pool instance.
+   * @param options - Optional configuration (schema, TTL, index, etc.).
+   * @returns A new PostgresStore instance backed by the provided pool.
+   *
+   * @example
+   * ```typescript
+   * import pg from "pg";
+   * import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
+   * import { PostgresStore } from "@langchain/langgraph-checkpoint-postgres/store";
+   *
+   * const pool = new pg.Pool({ connectionString: "postgresql://..." });
+   * const saver = new PostgresSaver(pool);
+   * const store = PostgresStore.fromPool(pool);
+   *
+   * await saver.setup();
+   * await store.setup();
+   * ```
+   */
+  static fromPool(
+    pool: pg.Pool,
+    options?: Omit<PostgresStoreConfig, "pool" | "connectionOptions">
+  ): PostgresStore {
+    return new PostgresStore({
+      pool,
+      ...options,
+    });
+  }
+
   /**
    * Initialize the store by running migrations to create necessary tables and indexes.
    */
@@ -374,13 +424,19 @@ export class PostgresStore extends BaseStore {
   }
 
   /**
-   * Stop the store and close all database connections.
+   * Stop the store and close database connections.
+   *
+   * If the pool was provided externally (e.g. via a pg.Pool instance in
+   * connectionOptions or via {@link fromPool}), the pool will NOT be closed
+   * because the caller retains ownership of the pool lifecycle.
    */
   async stop(): Promise<void> {
     if (this.isClosed) return;
 
     this.ttlManager.stop();
-    await this.core.pool.end();
+    if (this.poolOwned) {
+      await this.core.pool.end();
+    }
     this.isClosed = true;
   }
 

libs/checkpoint-postgres/src/store/modules/types.ts

@@ -181,8 +181,31 @@ export interface PutOptions {
 }
 
 export interface PostgresStoreConfig {
+  /**
+   * A preconfigured pg.Pool instance.
+   *
+   * When provided, this pool will be used directly and will NOT be closed
+   * when the store is stopped -- the caller retains ownership of the pool
+   * lifecycle. This enables sharing a single pool between PostgresSaver
+   * and PostgresStore for better resource management.
+   *
+   * If both `pool` and `connectionOptions` are provided, `pool` takes
+   * precedence.
+   *
+   * @example
+   * ```typescript
+   * const pool = new Pool({ connectionString: "postgresql://..." });
+   * const saver = new PostgresSaver(pool);
+   * const store = new PostgresStore({ pool });
+   * ```
+   */
+  pool?: pg.Pool;
+
   /**
    * PostgreSQL connection string or connection configuration object.
+   * A new pool will be created internally from these options.
+   *
+   * Ignored if `pool` is provided.
    *
    * @example
    * // Connection string
@@ -197,7 +220,7 @@ export interface PostgresStoreConfig {
    *   password: "password"
    * }
    */
-  connectionOptions: string | pg.PoolConfig;
+  connectionOptions?: string | pg.PoolConfig;
 
   /**
    * Database schema name to use for store tables.

libs/checkpoint-postgres/src/tests/store.int.test.ts

@@ -1527,3 +1527,100 @@ describe("PostgresStore Migration System", () => {
     }
   });
 });
+
+describe("PostgresStore Pool Sharing", () => {
+  let sharedPool: pg.Pool;
+  let dbName: string;
+  let dbConnectionString: string;
+
+  beforeEach(async () => {
+    dbName = `pool_share_test_${Date.now()}_${Math.floor(
+      Math.random() * 1000
+    )}`;
+    const adminPool = new Pool({ connectionString: TEST_POSTGRES_URL });
+    try {
+      await adminPool.query(`CREATE DATABASE ${dbName}`);
+    } finally {
+      await adminPool.end();
+    }
+    dbConnectionString = `${TEST_POSTGRES_URL!
+      .split("/")
+      .slice(0, -1)
+      .join("/")}/${dbName}`;
+    sharedPool = new Pool({ connectionString: dbConnectionString });
+  });
+
+  afterEach(async () => {
+    try {
+      await sharedPool.end();
+    } catch {
+      // Pool may already be ended; ignore.
+    }
+    const adminPool = new Pool({ connectionString: TEST_POSTGRES_URL });
+    try {
+      await adminPool.query(`DROP DATABASE IF EXISTS ${dbName} WITH (FORCE)`);
+    } finally {
+      await adminPool.end();
+    }
+  }, 30_000);
+
+  it("should accept a pg.Pool via the constructor", async () => {
+    const store = new PostgresStore({ pool: sharedPool });
+    await store.setup();
+
+    await store.put(["pool-test"], "key1", { data: "hello" });
+    const item = await store.get(["pool-test"], "key1");
+    expect(item).toBeDefined();
+    expect(item?.value).toEqual({ data: "hello" });
+
+    await store.stop();
+  });
+
+  it("should accept a pg.Pool via fromPool factory", async () => {
+    const store = PostgresStore.fromPool(sharedPool);
+    await store.setup();
+
+    await store.put(["pool-test"], "key1", { data: "fromPool" });
+    const item = await store.get(["pool-test"], "key1");
+    expect(item).toBeDefined();
+    expect(item?.value).toEqual({ data: "fromPool" });
+
+    await store.stop();
+  });
+
+  it("should not close an externally-provided pool on stop()", async () => {
+    const store = PostgresStore.fromPool(sharedPool);
+    await store.setup();
+
+    await store.put(["pool-test"], "key1", { data: "before-stop" });
+    await store.stop();
+
+    // The shared pool should still be usable after the store is stopped
+    const result = await sharedPool.query("SELECT 1 AS val");
+    expect(result.rows[0].val).toBe(1);
+  });
+
+  it("should allow a shared pool between two PostgresStore instances", async () => {
+    const store1 = PostgresStore.fromPool(sharedPool, { schema: "shared_a" });
+    const store2 = PostgresStore.fromPool(sharedPool, { schema: "shared_b" });
+
+    await store1.setup();
+    await store2.setup();
+
+    await store1.put(["ns"], "k1", { from: "store1" });
+    await store2.put(["ns"], "k1", { from: "store2" });
+
+    const item1 = await store1.get(["ns"], "k1");
+    const item2 = await store2.get(["ns"], "k1");
+
+    expect(item1?.value).toEqual({ from: "store1" });
+    expect(item2?.value).toEqual({ from: "store2" });
+
+    // Stop both stores -- the shared pool should remain open
+    await store1.stop();
+    await store2.stop();
+
+    const result = await sharedPool.query("SELECT 1 AS val");
+    expect(result.rows[0].val).toBe(1);
+  });
+});