@framers/sql-storage-adapter 0.6.16 → 0.7.0

package/dist/adapters/postgresAdapter.js

@@ -4,6 +4,7 @@
 const __isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 import { toPostgresStatement } from '../shared/sqlPlaceholders.js';
 import { splitSqlStatements } from '../shared/splitSqlStatements.js';
+import { validateSegment } from '../shared/segment.js';
 import { getStorageLogger } from '../shared/logger.js';
 /** The type-parser overrides `parsers` asks for, by OID, after checking each value. */
 const typeParserOverrides = (parsers) => {
@@ -46,6 +47,25 @@ const typeParserOverrides = (parsers) => {
     }
     return overrides;
 };
+/** The options that configure a pool when one is made, which a pool of the caller's already has. */
+const POOL_SETTINGS = [
+    'connectionString',
+    'host',
+    'port',
+    'database',
+    'user',
+    'password',
+    'ssl',
+    'max',
+    'min',
+    'idleTimeoutMillis',
+    'connectionTimeoutMillis',
+    'application_name',
+    'statement_timeout',
+    'query_timeout',
+    'allowExitOnIdle',
+    'typeParsers',
+];
 const ISOLATION_LEVELS = new Map([
     ['read uncommitted', 'READ UNCOMMITTED'],
     ['read committed', 'READ COMMITTED'],
@@ -78,33 +98,407 @@ const transactionStatus = (client) => {
 };
 /** The statement and values node-postgres receives: see toPostgresStatement. */
 const prepareStatement = toPostgresStatement;
-/** Execute a mutation through a specific pool or transaction client. */
-const runWithExecutor = async (executor, statement, parameters) => {
+/** Execute a mutation through a pool or a transaction client. */
+const runWith = async (query, statement, parameters) => {
     const { text, values } = prepareStatement(statement, parameters);
-    const result = await executor.query(text, values);
+    const result = await query(text, values);
     const firstRow = result.rows?.[0];
     const lastInsertRowid = firstRow && typeof firstRow === 'object' && 'id' in firstRow
         ? firstRow.id
         : null;
     return { changes: result.rowCount ?? 0, lastInsertRowid };
 };
-/** Read one row through a specific pool or transaction client. */
-const getWithExecutor = async (executor, statement, parameters) => {
+/** Read one row through a pool or a transaction client. */
+const getWith = async (query, statement, parameters) => {
     const { text, values } = prepareStatement(statement, parameters);
-    const result = await executor.query(text, values);
+    const result = await query(text, values);
     return result.rows?.[0] ?? null;
 };
-/** Read every matching row through a specific pool or transaction client. */
-const allWithExecutor = async (executor, statement, parameters) => {
+/** Read every matching row through a pool or a transaction client. */
+const allWith = async (query, statement, parameters) => {
     const { text, values } = prepareStatement(statement, parameters);
-    const result = await executor.query(text, values);
+    const result = await query(text, values);
     return result.rows ?? [];
 };
-/** Execute a statement script through a specific pool or transaction client. */
-const execWithExecutor = async (executor, script) => {
+/** Execute a statement script through a pool or a transaction client. */
+const execWith = async (query, script) => {
     const statements = splitSqlStatements(script);
     for (const text of statements) {
-        await executor.query(text);
+        await query(text, []);
+    }
+};
+/**
+ * The first `limit` words of a statement, past its comments: enough to tell
+ * what the statement is. String literals and dollar-quoted strings count as
+ * one word each and never read as a keyword.
+ */
+const leadingWords = (statement, limit) => {
+    const words = [];
+    let i = 0;
+    const length = statement.length;
+    while (i < length && words.length < limit) {
+        const char = statement[i];
+        if (/\s/.test(char)) {
+            i += 1;
+        }
+        else if (char === '-' && statement[i + 1] === '-') {
+            const end = statement.indexOf('\n', i);
+            i = end === -1 ? length : end + 1;
+        }
+        else if (char === '/' && statement[i + 1] === '*') {
+            // PostgreSQL's block comments nest.
+            let depth = 1;
+            i += 2;
+            while (i < length && depth > 0) {
+                if (statement[i] === '/' && statement[i + 1] === '*') {
+                    depth += 1;
+                    i += 2;
+                }
+                else if (statement[i] === '*' && statement[i + 1] === '/') {
+                    depth -= 1;
+                    i += 2;
+                }
+                else {
+                    i += 1;
+                }
+            }
+        }
+        else if (char === "'") {
+            i += 1;
+            while (i < length) {
+                if (statement[i] === "'" && statement[i + 1] === "'")
+                    i += 2;
+                else if (statement[i] === "'")
+                    break;
+                else
+                    i += 1;
+            }
+            i += 1;
+            words.push({ keyword: "'", identifier: '' });
+        }
+        else if (char === '"') {
+            let identifier = '';
+            i += 1;
+            while (i < length) {
+                if (statement[i] === '"' && statement[i + 1] === '"') {
+                    identifier += '"';
+                    i += 2;
+                }
+                else if (statement[i] === '"') {
+                    break;
+                }
+                else {
+                    identifier += statement[i];
+                    i += 1;
+                }
+            }
+            i += 1;
+            words.push({ keyword: '"', identifier });
+        }
+        else if (char === '$') {
+            const tag = /^\$[A-Za-z_]*\$/.exec(statement.slice(i));
+            if (tag) {
+                const end = statement.indexOf(tag[0], i + tag[0].length);
+                i = end === -1 ? length : end + tag[0].length;
+                words.push({ keyword: '$', identifier: '' });
+            }
+            else {
+                i += 1;
+                words.push({ keyword: '$', identifier: '' });
+            }
+        }
+        else if (/[A-Za-z_]/.test(char)) {
+            const word = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(statement.slice(i))[0];
+            i += word.length;
+            words.push({ keyword: word.toUpperCase(), identifier: word.toLowerCase() });
+        }
+        else {
+            i += 1;
+            words.push({ keyword: char, identifier: '' });
+        }
+    }
+    return words;
+};
+/**
+ * The extension a `CREATE EXTENSION` statement creates when the statement
+ * names no schema (`SCHEMA` or `WITH SCHEMA`), or null for any other
+ * statement.
+ */
+const unqualifiedCreateExtension = (statement) => {
+    const words = leadingWords(statement, 16);
+    if (words[0]?.keyword !== 'CREATE' || words[1]?.keyword !== 'EXTENSION')
+        return null;
+    let at = 2;
+    if (words[2]?.keyword === 'IF' && words[3]?.keyword === 'NOT' && words[4]?.keyword === 'EXISTS')
+        at = 5;
+    const name = words[at];
+    if (!name || (name.keyword !== '"' && !/^[A-Z_]/.test(name.keyword)))
+        return null;
+    if (words.slice(at + 1).some((word) => word.keyword === 'SCHEMA'))
+        return null;
+    return name.identifier;
+};
+/** An unknown thrown value as an Error. */
+const asError = (value) => (value instanceof Error ? value : new Error(String(value)));
+/**
+ * Puts a failed ROLLBACK's error on the transaction's error, as a
+ * non-enumerable `rollbackError` property, when that error can take one.
+ */
+const keepRollbackError = (error, rollbackError) => {
+    if (typeof error !== 'object' || error === null || !Object.isExtensible(error))
+        return;
+    try {
+        Object.defineProperty(error, 'rollbackError', {
+            value: rollbackError,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    catch {
+        // A non-configurable rollbackError is already there: keep it.
+    }
+};
+/**
+ * Listens for a connection error on a checked-out client until `stop()`. pg
+ * emits a client's connection error (the server ending the session, a broken
+ * socket) on the client when no query is running, and pg-pool listens only on
+ * idle clients, so without this an unheard error event would end the process.
+ */
+const watchClient = (client) => {
+    let failure;
+    // A pg-compatible pool whose clients are not event emitters emits nothing to hear.
+    if (typeof client.on !== 'function' || typeof client.removeListener !== 'function') {
+        return { failure: () => undefined, stop: () => undefined };
+    }
+    const onError = (error) => {
+        if (!failure)
+            failure = error;
+    };
+    client.on('error', onError);
+    return {
+        failure: () => failure,
+        stop: () => {
+            client.removeListener?.('error', onError);
+        },
+    };
+};
+/** Where an installed extension's objects are, and whether ALTER EXTENSION ... SET SCHEMA can move them. */
+const EXTENSION_PLACE = 'SELECT n.nspname AS schema, e.extrelocatable AS relocatable FROM pg_extension e ' +
+    'JOIN pg_namespace n ON n.oid = e.extnamespace WHERE e.extname = $1';
+/**
+ * Runs a statement through a segment's connections with care for the one
+ * statement whose effect depends on where it runs: an unqualified
+ * `CREATE EXTENSION` installs into the current schema, which on a segment is
+ * the segment, where no other segment and not the host find the extension's
+ * types. Such a statement runs with `search_path` set to `public` for itself
+ * alone, as it would without a segment (an extension whose control file names
+ * a schema still goes there). Afterwards the adapter checks where the
+ * extension is, since `IF NOT EXISTS` also succeeds for one installed in a
+ * schema the segment cannot see.
+ */
+class SegmentStatements {
+    constructor(segment) {
+        this.segment = segment;
+        /** Extensions already reported as out of the segment's reach. */
+        this.reported = new Set();
+    }
+    /**
+     * Runs `text` on the pool. The connection that runs a `CREATE EXTENSION`
+     * goes back to the pool unless its BEGIN or ROLLBACK failed or it broke
+     * while held, in which case it is closed.
+     */
+    async onPool(pool, text, values) {
+        const extension = unqualifiedCreateExtension(text);
+        if (extension === null) {
+            return pool.query(text, values);
+        }
+        const client = await pool.connect();
+        const watch = watchClient(client);
+        let brokenBy;
+        try {
+            return await this.inOwnTransaction(client, text, values, extension, (error) => {
+                if (!brokenBy)
+                    brokenBy = error;
+            });
+        }
+        finally {
+            watch.stop();
+            client.release(brokenBy ?? watch.failure());
+        }
+    }
+    /** Runs `text` on a transaction's client, inside the caller's transaction. */
+    async inTransaction(client, text, values) {
+        const extension = unqualifiedCreateExtension(text);
+        if (extension === null) {
+            return client.query(text, values);
+        }
+        return this.withinTransaction(client, text, values, extension);
+    }
+    /**
+     * Runs `text` on the connection a `withConnection()` callback holds: inside
+     * the transaction the callback began, as `inTransaction` does, or outside
+     * one in a transaction of its own, as on the pool. On a pg that does not
+     * report a connection's transaction status (before 8.21), the session's
+     * search_path is set to `public` around the statement and set back after it.
+     * `onBroken` hears when the connection cannot be trusted any more, so
+     * `withConnection()` closes it instead of returning it to the pool.
+     */
+    async onConnection(client, text, values, onBroken) {
+        const extension = unqualifiedCreateExtension(text);
+        if (extension === null) {
+            return client.query(text, values);
+        }
+        switch (transactionStatus(client)) {
+            case 'T':
+                return this.withinTransaction(client, text, values, extension);
+            case 'I':
+                return this.inOwnTransaction(client, text, values, extension, onBroken);
+            case 'E':
+                // The transaction has failed: the statement fails with its reason.
+                return client.query(text, values);
+            default:
+                return this.aroundSession(client, text, values, extension, onBroken);
+        }
+    }
+    /**
+     * In a transaction of its own on `client`, whose COMMIT or ROLLBACK ends the
+     * setting. A BEGIN or ROLLBACK that fails leaves the connection in a state
+     * nobody knows, so `onBroken` hears of it.
+     */
+    async inOwnTransaction(client, text, values, extension, onBroken) {
+        try {
+            await client.query('BEGIN');
+        }
+        catch (error) {
+            onBroken(asError(error));
+            throw error;
+        }
+        let result;
+        try {
+            // set_config(..., true) is SET LOCAL: the COMMIT or ROLLBACK below ends it,
+            // so the connection goes back to the pool on the segment's search_path.
+            await client.query("SELECT set_config('search_path', 'public', true)");
+            result = await client.query(text, values);
+            await client.query('COMMIT');
+        }
+        catch (error) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch (rollbackError) {
+                onBroken(asError(rollbackError));
+                keepRollbackError(error, asError(rollbackError));
+            }
+            throw error;
+        }
+        await this.checkReach((t, v) => client.query(t, v), extension);
+        return result;
+    }
+    /** Inside the transaction open on `client`, setting the search_path for the statement and back. */
+    async withinTransaction(client, text, values, extension) {
+        const saved = await client.query("SELECT current_setting('search_path') AS path");
+        const path = saved.rows[0]?.path;
+        await client.query("SELECT set_config('search_path', 'public', true)");
+        // A failure aborts the caller's transaction, whose rollback (or a
+        // rollback to a savepoint before this) undoes the setting.
+        const result = await client.query(text, values);
+        await client.query('SELECT set_config($1, $2, true)', ['search_path', typeof path === 'string' ? path : `${this.segment}, public`]);
+        await this.checkReach((t, v) => client.query(t, v), extension);
+        return result;
+    }
+    /**
+     * With the session's search_path set to `public` for the statement, and set
+     * back after it. When the statement fails inside a transaction, setting it
+     * back fails too, and that transaction's rollback restores it. Without the
+     * transaction status this cannot tell that case from a connection whose
+     * search_path stays on `public`, so a failed set-back tells `onBroken`, and
+     * the connection is closed rather than returned to the pool outside the
+     * segment.
+     */
+    async aroundSession(client, text, values, extension, onBroken) {
+        const saved = await client.query("SELECT current_setting('search_path') AS path");
+        const savedPath = saved.rows[0]?.path;
+        const path = typeof savedPath === 'string' ? savedPath : `${this.segment}, public`;
+        await client.query("SELECT set_config('search_path', 'public', false)");
+        const setBack = async () => {
+            try {
+                await client.query('SELECT set_config($1, $2, false)', ['search_path', path]);
+            }
+            catch (error) {
+                onBroken(asError(error));
+                throw error;
+            }
+        };
+        let result;
+        try {
+            result = await client.query(text, values);
+        }
+        catch (error) {
+            await setBack().catch(() => undefined);
+            throw error;
+        }
+        await setBack();
+        await this.checkReach((t, v) => client.query(t, v), extension);
+        return result;
+    }
+    async checkReach(query, extension) {
+        if (this.reported.has(extension))
+            return;
+        const found = await query(EXTENSION_PLACE, [extension]);
+        const place = found.rows[0];
+        if (!place || place.relocatable !== true)
+            return;
+        if (place.schema === 'public' || place.schema === this.segment)
+            return;
+        this.reported.add(extension);
+        getStorageLogger().warn({ adapter: 'postgres', segment: this.segment, extension, schema: String(place.schema) }, `PostgreSQL extension "${extension}" is installed in schema "${String(place.schema)}", which segment ` +
+            `"${this.segment}" does not reach: its search_path is ${this.segment}, public, so the extension's types and functions ` +
+            `do not resolve here. ALTER EXTENSION "${extension}" SET SCHEMA public moves it where every segment finds it.`);
+    }
+}
+/** A pool on which `end()` has been called. */
+const hasEnded = (pool) => pool.ending === true || pool.ended === true;
+/** The listener the adapter puts on a pool it owns when no `onError` was given. */
+const warnOfIdleError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    getStorageLogger().warn({ adapter: 'postgres', error: message }, `PostgreSQL: an idle connection of the pool failed; the pool opens another when one is needed. ${message}`);
+};
+/** The value of an environment variable, where there is an environment. */
+const readEnv = (key) => typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
+/**
+ * Refuses a connection string that sets its own startup options when a
+ * segment needs that parameter: pg copies a connection string's parameters
+ * over the explicit configuration, so its `options` would replace the
+ * segment's search_path.
+ */
+const refuseOwnStartupOptions = (connectionString) => {
+    if (connectionString && /[?&]options=/i.test(connectionString)) {
+        throw new Error('PostgresAdapter: a segment cannot be used with a connection string that sets its own startup options (options=...): ' +
+            "pg sends those in place of the segment's search_path. Move them out of the connection string, into PGOPTIONS.");
+    }
+};
+/**
+ * Creates a segment's schema when it is missing. The check comes first, so a
+ * role without CREATE on the database can open a segment that exists: CREATE
+ * SCHEMA IF NOT EXISTS checks that privilege before it looks for the schema.
+ */
+const createSchema = async (client, segment) => {
+    const found = await client.query('SELECT 1 FROM pg_namespace WHERE nspname = $1', [segment]);
+    if (found.rows.length > 0) {
+        return;
+    }
+    try {
+        // validateSegment admits lower-case letters, digits and underscores alone.
+        await client.query(`CREATE SCHEMA IF NOT EXISTS "${segment}"`);
+    }
+    catch (error) {
+        // Two processes that open one new segment at once can both find it
+        // missing; the slower CREATE then fails on pg_namespace's unique index.
+        const code = error?.code;
+        if (code !== '23505' && code !== '42P06') {
+            throw error;
+        }
     }
 };
 /**
@@ -116,12 +510,14 @@ const execWithExecutor = async (executor, script) => {
  * adapter's pool, or the held connection the transaction ran on.
  */
 class PostgresTransactionAdapter {
-    constructor(client, capabilities, afterEnd) {
-        this.client = client;
+    constructor(client, capabilities, segment, afterEnd) {
         this.capabilities = capabilities;
         this.afterEnd = afterEnd;
         this.kind = 'postgres';
         this.ended = false;
+        this.query = segment
+            ? (text, values) => segment.inTransaction(client, text, values)
+            : (text, values) => client.query(text, values);
     }
     async open() {
         // The owning PostgresAdapter opens the pool before creating this view.
@@ -129,22 +525,22 @@ class PostgresTransactionAdapter {
     async run(statement, parameters) {
         if (this.ended)
             return this.afterEnd.run(statement, parameters);
-        return runWithExecutor(this.client, statement, parameters);
+        return runWith(this.query, statement, parameters);
     }
     async get(statement, parameters) {
         if (this.ended)
             return this.afterEnd.get(statement, parameters);
-        return getWithExecutor(this.client, statement, parameters);
+        return getWith(this.query, statement, parameters);
     }
     async all(statement, parameters) {
         if (this.ended)
             return this.afterEnd.all(statement, parameters);
-        return allWithExecutor(this.client, statement, parameters);
+        return allWith(this.query, statement, parameters);
     }
     async exec(script) {
         if (this.ended)
             return this.afterEnd.exec(script);
-        await execWithExecutor(this.client, script);
+        await execWith(this.query, script);
     }
     async transaction(fn) {
         // After the transaction has ended, a new one begins where afterEnd runs it.
@@ -162,51 +558,6 @@ class PostgresTransactionAdapter {
         this.ended = true;
     }
 }
-/** An unknown thrown value as an Error. */
-const asError = (value) => (value instanceof Error ? value : new Error(String(value)));
-/**
- * Puts a failed ROLLBACK's error on the transaction's error, as a
- * non-enumerable `rollbackError` property, when that error can take one.
- */
-const keepRollbackError = (error, rollbackError) => {
-    if (typeof error !== 'object' || error === null || !Object.isExtensible(error))
-        return;
-    try {
-        Object.defineProperty(error, 'rollbackError', {
-            value: rollbackError,
-            enumerable: false,
-            configurable: true,
-            writable: true,
-        });
-    }
-    catch {
-        // A non-configurable rollbackError is already there: keep it.
-    }
-};
-/**
- * Listens for a connection error on a checked-out client until `stop()`. pg
- * emits a client's connection error (the server ending the session, a broken
- * socket) on the client when no query is running, and pg-pool listens only on
- * idle clients, so without this an unheard error event would end the process.
- */
-const watchClient = (client) => {
-    let failure;
-    // A pg-compatible pool whose clients are not event emitters emits nothing to hear.
-    if (typeof client.on !== 'function' || typeof client.removeListener !== 'function') {
-        return { failure: () => undefined, stop: () => undefined };
-    }
-    const onError = (error) => {
-        if (!failure)
-            failure = error;
-    };
-    client.on('error', onError);
-    return {
-        failure: () => failure,
-        stop: () => {
-            client.removeListener('error', onError);
-        },
-    };
-};
 /**
  * Runs `fn` in a transaction that `begin` opens on `client`: COMMIT when `fn`
  * resolves, ROLLBACK when `fn` or COMMIT throws, and that error is rethrown.
@@ -215,7 +566,7 @@ const watchClient = (client) => {
  * pool. When ROLLBACK fails, the original error is still the one thrown, with
  * the ROLLBACK error on it as `rollbackError`.
  */
-const runTransaction = async (client, begin, fn, capabilities, afterEnd, onBroken) => {
+const runTransaction = async (client, begin, fn, capabilities, segment, afterEnd, onBroken) => {
     try {
         await client.query(begin);
     }
@@ -223,7 +574,7 @@ const runTransaction = async (client, begin, fn, capabilities, afterEnd, onBroke
         onBroken(asError(error));
         throw error;
     }
-    const handle = new PostgresTransactionAdapter(client, capabilities, afterEnd);
+    const handle = new PostgresTransactionAdapter(client, capabilities, segment, afterEnd);
     try {
         const result = await fn(handle);
         await client.query('COMMIT');
@@ -251,27 +602,37 @@ const runTransaction = async (client, begin, fn, capabilities, afterEnd, onBroke
  * closed.
  */
 class PostgresConnectionAdapter {
-    constructor(client, capabilities) {
+    constructor(client, capabilities, segment) {
         this.client = client;
         this.capabilities = capabilities;
+        this.segment = segment;
         this.kind = 'postgres';
         this.ended = false;
         this.transactionOpen = false;
+        /** Keeps the first reason the connection cannot be trusted any more. */
+        this.onBroken = (error) => {
+            if (!this.brokenBy)
+                this.brokenBy = error;
+        };
+        this.query = (text, values) => {
+            const live = this.live();
+            return segment ? segment.onConnection(live, text, values, this.onBroken) : live.query(text, values);
+        };
     }
     async open() {
         // withConnection() checks the connection out before the callback runs.
     }
     async run(statement, parameters) {
-        return runWithExecutor(this.live(), statement, parameters);
+        return runWith(this.query, statement, parameters);
     }
     async get(statement, parameters) {
-        return getWithExecutor(this.live(), statement, parameters);
+        return getWith(this.query, statement, parameters);
     }
     async all(statement, parameters) {
-        return allWithExecutor(this.live(), statement, parameters);
+        return allWith(this.query, statement, parameters);
     }
     async exec(script) {
-        await execWithExecutor(this.live(), script);
+        await execWith(this.query, script);
     }
     async transaction(fn, options) {
         const begin = beginStatement(options);
@@ -281,10 +642,7 @@ class PostgresConnectionAdapter {
         }
         this.transactionOpen = true;
         try {
-            return await runTransaction(client, begin, fn, this.capabilities, this, (error) => {
-                if (!this.brokenBy)
-                    this.brokenBy = error;
-            });
+            return await runTransaction(client, begin, fn, this.capabilities, this.segment, this, this.onBroken);
         }
         finally {
             this.transactionOpen = false;
@@ -398,6 +756,18 @@ class PostgresConnectionAdapter {
  * });
  * ```
  *
+ * ### A pool the host already holds
+ * ```typescript
+ * const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * // The adapter runs on the host's pool; close() leaves it open.
+ * const db = new PostgresAdapter({ pool, onError: (error) => console.warn('idle connection failed', error) });
+ * ```
+ *
+ * ### A segment: the adapter's tables in a schema of their own
+ * ```typescript
+ * const agentos = createPostgresAdapter({ connectionString: process.env.DATABASE_URL, segment: 'agentos' });
+ * ```
+ *
  * ## Connection failures
  * - The pool drops a connection that fails, and the next query opens a new one.
  * - The adapter never falls back to SQLite. `resolveStorageAdapter()` without
@@ -431,16 +801,60 @@ export class PostgresAdapter {
             'arrays', // Native array data types
             'prepared' // Prepared statements for security/performance
         ]);
+        /**
+         * The pool statements run on, or null while the adapter is closed. Hosts
+         * written against 0.6 hand the adapter a Pool by setting this field before
+         * `open()`; the adapter then runs on that Pool and ends it on `close()`, as
+         * 0.6 did. Keep its name, and keep it a plain field that starts as null.
+         */
         this.pool = null;
         this.pgModule = null;
+        /** The error listener the adapter has on a pool, and that pool. */
+        this.listening = null;
+        this.opening = null;
+        this.closing = null;
+        /** The runner of statements outside a transaction. */
+        this.query = (text, values) => {
+            const pool = this.requirePool();
+            return this.segmentStatements ? this.segmentStatements.onPool(pool, text, values) : pool.query(text, values);
+        };
         // Support both string and object initialization
-        if (typeof options === 'string') {
-            this.options = { connectionString: options };
+        this.options = typeof options === 'string' ? { connectionString: options } : { ...options };
+        const segment = this.options.segment === undefined ? undefined : validateSegment(this.options.segment);
+        this.segmentStatements = segment === undefined ? null : new SegmentStatements(segment);
+        const given = this.options.pool;
+        if (given) {
+            if (segment !== undefined) {
+                throw new Error("PostgresAdapter: a segment cannot run on a pool its caller made: the segment's search_path is set when each " +
+                    'connection of the pool starts, and the adapter does not start the connections of a pool it did not make. ' +
+                    'Give the connection settings and the segment instead of the pool.');
+            }
+            const settings = POOL_SETTINGS.filter((key) => this.options[key] !== undefined);
+            if (settings.length > 0) {
+                throw new Error(`PostgresAdapter: ${settings.join(', ')} cannot be given with pool: they configure a pool when one is made, ` +
+                    'and the pool given was made by its caller. Set them on that pool' +
+                    (settings.includes('typeParsers') ? " (typeParsers through the pool's own types option)." : '.'));
+            }
+            this.givenPool = given;
+            this.ownsPool = this.options.ownsPool === true;
+            this.pool = given;
+            this.listenOn(given);
         }
         else {
-            this.options = options;
+            this.givenPool = null;
+            this.ownsPool = true;
+            if (segment !== undefined) {
+                refuseOwnStartupOptions(this.options.connectionString);
+            }
         }
     }
+    /**
+     * The pool the adapter runs on: the pool it was given, or the pool it made
+     * while it is open. Null while the adapter is closed.
+     */
+    getPool() {
+        return this.pool;
+    }
     /**
      * Lazy loader for pg module to keep the dependency optional and prevent bundling in browser builds.
      */
@@ -460,21 +874,69 @@ export class PostgresAdapter {
             throw new Error(`[StorageAdapter] Failed to load pg module. Install it with: npm install pg. Error: ${error}`);
         }
     }
-    async open(openOptions) {
+    /**
+     * Opens the adapter: makes its pool and checks that a connection can be
+     * made (and with a segment, creates the segment's schema when it is
+     * missing), or takes up the pool it was given. A failure ends the pool it
+     * made, so a later `open()` starts again. Two calls at once open once.
+     */
+    open(openOptions) {
         if (this.pool) {
-            return;
+            return Promise.resolve();
+        }
+        if (!this.opening) {
+            this.opening = this.openNow(openOptions).finally(() => {
+                this.opening = null;
+            });
         }
+        return this.opening;
+    }
+    async openNow(openOptions) {
         if (__isBrowser) {
             throw new Error('[StorageAdapter] PostgreSQL adapter cannot be opened in a browser environment.');
         }
+        if (this.givenPool) {
+            if (hasEnded(this.givenPool)) {
+                throw new Error('PostgresAdapter: the pool it was given has ended, so the adapter cannot open on it again.');
+            }
+            this.pool = this.givenPool;
+            this.listenOn(this.givenPool);
+            return;
+        }
+        const connectionString = openOptions?.connectionString ?? this.options.connectionString;
+        if (this.segmentStatements) {
+            refuseOwnStartupOptions(connectionString);
+        }
         // Load pg module dynamically
         const pg = await this.loadPgModule();
-        const { Pool } = pg;
-        // Build pool configuration
+        const pool = new pg.Pool(this.poolConfig(pg, connectionString));
+        this.listenOn(pool);
+        try {
+            // Test connection
+            const client = await pool.connect();
+            try {
+                if (this.segmentStatements) {
+                    await createSchema(client, this.segmentStatements.segment);
+                }
+            }
+            finally {
+                client.release();
+            }
+        }
+        catch (error) {
+            // The listener stays on the pool through its end; the adapter forgets it.
+            this.listening = null;
+            await pool.end().catch(() => undefined);
+            throw error;
+        }
+        this.pool = pool;
+    }
+    /** The configuration of the pool the adapter makes. */
+    poolConfig(pg, connectionString) {
         const poolConfig = {};
         // Use connection string if provided
-        if (this.options.connectionString || openOptions?.connectionString) {
-            poolConfig.connectionString = openOptions?.connectionString ?? this.options.connectionString;
+        if (connectionString) {
+            poolConfig.connectionString = connectionString;
         }
         else {
             // Build from individual options
@@ -520,26 +982,36 @@ export class PostgresAdapter {
         if (this.options.ssl !== undefined) {
             poolConfig.ssl = this.options.ssl;
         }
-        this.pool = new Pool(poolConfig);
-        // Test connection
-        const client = await this.pool.connect();
-        client.release();
+        if (this.segmentStatements) {
+            // Every connection the pool opens, a replacement included, starts on the
+            // segment. A startup setting is the connection's default, so RESET and
+            // DISCARD ALL return to it. pg reads PGOPTIONS only for a connection
+            // without options of its own, so its options are kept here.
+            const searchPath = `-c search_path=${this.segmentStatements.segment},public`;
+            const inherited = readEnv('PGOPTIONS')?.trim();
+            poolConfig.options = inherited ? `${inherited} ${searchPath}` : searchPath;
+        }
+        return poolConfig;
+    }
+    /** Puts the adapter's error listener on `pool`: `onError`, or the warning on a pool it owns. */
+    listenOn(pool) {
+        const listener = this.options.onError ?? (this.ownsPool ? warnOfIdleError : null);
+        if (!listener || typeof pool.on !== 'function' || this.listening?.pool === pool)
+            return;
+        pool.on('error', listener);
+        this.listening = { pool, listener };
     }
     async run(statement, parameters) {
-        const executor = await this.getExecutor();
-        return runWithExecutor(executor, statement, parameters);
+        return runWith(this.query, statement, parameters);
     }
     async get(statement, parameters) {
-        const executor = await this.getExecutor();
-        return getWithExecutor(executor, statement, parameters);
+        return getWith(this.query, statement, parameters);
     }
     async all(statement, parameters) {
-        const executor = await this.getExecutor();
-        return allWithExecutor(executor, statement, parameters);
+        return allWith(this.query, statement, parameters);
     }
     async exec(script) {
-        const executor = await this.getExecutor();
-        await execWithExecutor(executor, script);
+        await execWith(this.query, script);
     }
     /**
      * Runs `fn` in a transaction on one pooled connection: COMMIT when it
@@ -558,7 +1030,7 @@ export class PostgresAdapter {
         const watch = watchClient(client);
         let brokenBy;
         try {
-            return await runTransaction(client, begin, fn, this.capabilities, this, (error) => {
+            return await runTransaction(client, begin, fn, this.capabilities, this.segmentStatements, this, (error) => {
                 if (!brokenBy)
                     brokenBy = error;
             });
@@ -583,12 +1055,14 @@ export class PostgresAdapter {
      * connection is closed, which rolls the transaction back, and the call
      * rejects (pg 8.21 and later report the transaction status). The connection
      * refuses statements once `fn` has ended. A connection that broke while `fn`
-     * held it (the server ended the session) is closed, not returned.
+     * held it (the server ended the session) is closed, not returned. On a
+     * segmented adapter the connection starts in the segment, as every
+     * connection of its pool does.
      */
     async withConnection(fn) {
         const client = await this.requirePool().connect();
         const watch = watchClient(client);
-        const connection = new PostgresConnectionAdapter(client, this.capabilities);
+        const connection = new PostgresConnectionAdapter(client, this.capabilities, this.segmentStatements);
         let releaseError;
         try {
             const result = await fn(connection);
@@ -613,21 +1087,52 @@ export class PostgresAdapter {
             client.release(releaseError ?? connection.brokenBy ?? watch.failure());
         }
     }
-    /** The pool's counts, or null when the adapter is not open. */
+    /**
+     * The pool's counts, or null when the adapter is not open. A pool of the
+     * caller's that does not count its connections, as pg's Pool does, reads 0.
+     */
     getPoolStats() {
-        if (!this.pool) {
+        const pool = this.pool;
+        if (!pool) {
             return null;
         }
-        return { total: this.pool.totalCount, idle: this.pool.idleCount, waiting: this.pool.waitingCount };
+        return { total: pool.totalCount ?? 0, idle: pool.idleCount ?? 0, waiting: pool.waitingCount ?? 0 };
     }
-    async close() {
-        if (this.pool) {
-            await this.pool.end();
-            this.pool = null;
+    /**
+     * Closes the adapter. A pool the adapter made or owns is ended, once; a pool
+     * of its caller's that it does not own is left open, with the adapter's
+     * listener taken off it. A call made while a close is running waits for it.
+     */
+    close() {
+        if (!this.closing) {
+            this.closing = this.closeNow().finally(() => {
+                this.closing = null;
+            });
         }
+        return this.closing;
     }
-    async getExecutor() {
-        return this.requirePool();
+    async closeNow() {
+        if (this.opening) {
+            await this.opening.catch(() => undefined);
+        }
+        const pool = this.pool;
+        this.pool = null;
+        if (!pool) {
+            return;
+        }
+        const listening = this.listening?.pool === pool ? this.listening : null;
+        this.listening = null;
+        if (this.ownsPool) {
+            // The listener stays on: a connection the pool lets go can still report
+            // its end after end() has resolved.
+            if (!hasEnded(pool)) {
+                await pool.end();
+            }
+            return;
+        }
+        if (listening && typeof pool.removeListener === 'function') {
+            pool.removeListener('error', listening.listener);
+        }
     }
     requirePool() {
         if (!this.pool) {