@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/adapters/postgresAdapter.d.ts

@@ -0,0 +1,424 @@
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult } from '../core/contracts/index.js';
+/** What the adapter reads from the answer to a query. */
+export interface PostgresQueryResultLike {
+    rows: unknown[];
+    rowCount?: number | null;
+}
+/** A connection checked out of a pool: the part of pg's `PoolClient` the adapter uses. */
+export interface PostgresPoolClientLike {
+    query(text: string, values?: unknown[]): Promise<PostgresQueryResultLike>;
+    release(error?: Error | boolean): void;
+    /**
+     * pg's client is an event emitter: while the adapter holds a client, it
+     * listens for the client's connection error. A client without these emits
+     * nothing for the adapter to hear.
+     */
+    on?(event: 'error', listener: (error: Error) => void): unknown;
+    removeListener?(event: 'error', listener: (error: Error) => void): unknown;
+}
+/**
+ * The part of pg's `Pool` the adapter uses. A `Pool` from `pg` is one; so is
+ * any object with these members.
+ */
+export interface PostgresPoolLike {
+    query(text: string, values?: unknown[]): Promise<PostgresQueryResultLike>;
+    connect(): Promise<PostgresPoolClientLike>;
+    end(): Promise<void>;
+    on?(event: 'error', listener: (error: Error) => void): unknown;
+    removeListener?(event: 'error', listener: (error: Error) => void): unknown;
+    /** True once `end()` has been called; pg's Pool sets it. */
+    readonly ending?: boolean;
+    /** True once the pool has ended; pg's Pool sets it. */
+    readonly ended?: boolean;
+    /** Connections the pool holds, checked out or idle; pg's Pool counts them. */
+    readonly totalCount?: number;
+    /** Connections idle in the pool. */
+    readonly idleCount?: number;
+    /** Callers waiting for a connection. */
+    readonly waitingCount?: number;
+}
+/**
+ * Configuration options for PostgreSQL adapter.
+ * Supports both connection strings and granular configuration.
+ */
+export interface PostgresAdapterOptions {
+    /** PostgreSQL connection string (e.g., 'postgresql://user:pass@host:5432/dbname') */
+    connectionString?: string;
+    /** Host name or IP address (default: localhost) */
+    host?: string;
+    /** Port number (default: 5432) */
+    port?: number;
+    /** Database name */
+    database?: string;
+    /** Username for authentication */
+    user?: string;
+    /** Password for authentication */
+    password?: string;
+    /** Enable SSL/TLS connection (recommended for remote) */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+        cert?: string;
+        key?: string;
+    };
+    /** Connection pool size (default: 10) */
+    max?: number;
+    /** Minimum pool size (default: 0) */
+    min?: number;
+    /** Idle timeout in ms (default: 10000) */
+    idleTimeoutMillis?: number;
+    /** Connection timeout in ms (default: 0 = no timeout) */
+    connectionTimeoutMillis?: number;
+    /** Application name for connection tracking */
+    application_name?: string;
+    /** Statement timeout in ms (0 = no timeout) */
+    statement_timeout?: number;
+    /** Query timeout in ms (0 = no timeout) */
+    query_timeout?: number;
+    /**
+     * Let Node exit while every connection in the pool is idle (pg's
+     * `allowExitOnIdle`). Default: false, so idle connections keep the process
+     * running until `idleTimeoutMillis` closes them or `close()` ends the pool.
+     */
+    allowExitOnIdle?: boolean;
+    /**
+     * How this pool's connections decode the column types whose pg defaults
+     * surprise JavaScript code, through pg's per-client type parsers. Each field
+     * left out keeps pg's default. A value it does not know fails open(). A pool
+     * of the caller's decodes with the `types` it was made with, so this cannot
+     * be given with `pool`.
+     */
+    typeParsers?: PostgresTypeParsers;
+    /**
+     * A schema of its own for the adapter's tables. Every connection of the
+     * adapter's pool starts with `search_path` set to the segment, then
+     * `public`, so the tables it creates without a schema land in the segment,
+     * and the types, functions and operators of extensions in `public`
+     * (pgvector's `vector`, `<->`) still resolve. `open()` creates the schema
+     * when it is missing, and a `CREATE EXTENSION` that names no schema installs
+     * the extension where it would without a segment, in `public`.
+     *
+     * A name the segment does not hold falls through to `public`: create a
+     * segment's tables before reading them (`CREATE TABLE IF NOT EXISTS` creates
+     * one in the segment even when `public` has a table of that name), and name
+     * the segment in a DROP or ALTER that `public` could also answer.
+     *
+     * Lower-case letters, digits and underscores; not `public`,
+     * `information_schema` or a name beginning with `pg_`. A segment cannot be
+     * combined with `pool`, nor with a connection string that sets its own
+     * `options` startup parameter: pg sends those in place of the segment's.
+     */
+    segment?: string;
+    /**
+     * A pool the caller made (a `pg` `Pool`) for the adapter to run on, instead
+     * of making one. The adapter runs on it from the start: no `open()` is
+     * needed, and `open()` after `close()` takes it up again. The connection
+     * settings above apply when a pool is made, so none of them, nor `segment`,
+     * can be given with it.
+     */
+    pool?: PostgresPoolLike;
+    /**
+     * Whether `close()` ends `pool`. False by default: the pool is its caller's,
+     * and `close()` leaves it open. Pass true when the adapter is the pool's one
+     * holder and closing the adapter is how the pool should end; `close()` then
+     * ends it once, however often it is called.
+     */
+    ownsPool?: boolean;
+    /**
+     * Called with the error an idle connection of the pool reports (the server
+     * ended it, the network dropped). pg's Pool raises such an error as an event
+     * that, with no listener, ends the process. On a pool the adapter makes or
+     * owns, the adapter listens even without `onError` and logs one warning per
+     * error; on a pool of its caller's that it does not own, it listens only
+     * when given `onError`, and takes its listener off again on `close()`.
+     */
+    onError?: (error: Error) => void;
+}
+/** Per-pool decoding of int8, numeric, date and json columns. Each field left out keeps pg's default. */
+export interface PostgresTypeParsers {
+    /** int8 / bigint (OID 20). pg's default is 'string'. 'number' refuses a value past `Number.MAX_SAFE_INTEGER`. */
+    int8?: 'string' | 'number' | 'bigint';
+    /** numeric / decimal (OID 1700). pg's default is 'string'. 'number' is a double, so it can round. */
+    numeric?: 'string' | 'number';
+    /** date (OID 1082). pg's default is 'date', a Date at local midnight; 'string' keeps `YYYY-MM-DD`. */
+    date?: 'date' | 'string';
+    /** json (OID 114) and jsonb (OID 3802). pg's default is 'parse'; 'string' keeps the text, as SQLite returns it. */
+    json?: 'parse' | 'string';
+}
+/** The isolation levels of PostgreSQL's `BEGIN`. */
+export type PostgresIsolationLevel = 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable';
+/** How a PostgreSQL transaction begins. Left out, each mode is the server's default. */
+export interface PostgresTransactionOptions {
+    /** `BEGIN ISOLATION LEVEL ...`. The server's default is `read committed` unless configured otherwise. */
+    isolationLevel?: PostgresIsolationLevel;
+    /** `READ ONLY` when true, `READ WRITE` when false. */
+    readOnly?: boolean;
+    /** `DEFERRABLE` when true, `NOT DEFERRABLE` when false. It changes only serializable read-only transactions. */
+    deferrable?: boolean;
+}
+/** The counts of a Postgres adapter's connection pool. */
+export interface PostgresPoolStats {
+    /** Connections the pool holds, checked out or idle. */
+    total: number;
+    /** Connections idle in the pool. */
+    idle: number;
+    /** Callers waiting for a connection. */
+    waiting: number;
+}
+/**
+ * One pooled connection, held for a `withConnection()` callback. Its
+ * statements run outside a transaction unless the callback opens one, and
+ * session state (`SET`, session advisory locks, temporary tables) lasts until
+ * the connection closes.
+ */
+export interface PostgresConnection extends StorageAdapter {
+    /** Runs `fn` in a transaction on this connection. One transaction at a time. */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>, options?: PostgresTransactionOptions): Promise<T>;
+}
+/**
+ * PostgreSQL adapter for production-grade SQL operations.
+ *
+ * ## Performance Characteristics
+ * - Connection pooling for efficient resource usage
+ * - Excellent concurrent access with MVCC
+ * - Optimized for complex queries and large datasets
+ * - ~10,000 queries/second with connection pooling
+ *
+ * ## Advantages
+ * - Full SQL feature set (CTEs, window functions, etc.)
+ * - Native JSON/JSONB support
+ * - Robust replication and backup options
+ * - Battle-tested in production environments
+ * - Secure remote connections with SSL/TLS
+ *
+ * ## Limitations
+ * - Requires separate server process
+ * - Network latency for remote connections
+ * - Higher resource consumption than SQLite
+ * - Configuration complexity for optimal performance
+ *
+ * ## When to Use
+ * - Production web applications
+ * - Multi-user systems
+ * - When you need advanced SQL features
+ * - Cloud deployments (AWS RDS, Heroku, Supabase, etc.)
+ * - Remote database access
+ *
+ * ## Remote Connection Examples
+ *
+ * ### Connection String (Recommended)
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   connectionString: 'postgresql://user:password@db.example.com:5432/mydb?sslmode=require'
+ * });
+ * ```
+ *
+ * ### Granular Configuration
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   host: 'db.example.com',
+ *   port: 5432,
+ *   database: 'mydb',
+ *   user: 'dbuser',
+ *   password: 'secure_password',
+ *   ssl: true,  // Enable SSL for security
+ *   max: 20,    // Connection pool size
+ *   statement_timeout: 30000  // 30 second timeout
+ * });
+ * ```
+ *
+ * ### Cloud Provider Examples
+ *
+ * #### AWS RDS
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   host: 'mydb.abc123.us-east-1.rds.amazonaws.com',
+ *   port: 5432,
+ *   database: 'postgres',
+ *   user: 'admin',
+ *   password: process.env.RDS_PASSWORD,
+ *   ssl: { rejectUnauthorized: true }
+ * });
+ * ```
+ *
+ * #### Heroku Postgres
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   connectionString: process.env.DATABASE_URL,
+ *   ssl: { rejectUnauthorized: false }  // Heroku uses self-signed certs
+ * });
+ * ```
+ *
+ * #### Supabase
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   connectionString: process.env.SUPABASE_DB_URL,
+ *   ssl: true
+ * });
+ * ```
+ *
+ * #### DigitalOcean Managed Database
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   host: 'db-postgresql-nyc3-12345.ondigitalocean.com',
+ *   port: 25060,
+ *   database: 'defaultdb',
+ *   user: 'doadmin',
+ *   password: process.env.DO_DB_PASSWORD,
+ *   ssl: { rejectUnauthorized: true, ca: process.env.DO_CA_CERT }
+ * });
+ * ```
+ *
+ * ### 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
+ *   `strict` tries its next candidate when Postgres fails to open; with
+ *   `strict`, and in `createDatabase()` given a Postgres URL, it throws.
+ *
+ * ## Pool control
+ * - `withConnection(fn)` holds one connection for `fn`: session settings,
+ *   session advisory locks, and statements that must run outside a
+ *   transaction.
+ * - `getPoolStats()` counts the pool's connections and waiting callers.
+ * - `transaction(fn, { isolationLevel, readOnly, deferrable })` sets how the
+ *   transaction begins.
+ * - `allowExitOnIdle` lets Node exit while the pool is idle.
+ */
+/**
+ * Production-grade PostgreSQL adapter backed by pg.Pool.
+ *
+ * Safe to import in browser bundles; will only throw if `open()` is invoked
+ * in a browser environment.
+ */
+export declare class PostgresAdapter implements StorageAdapter {
+    readonly kind = "postgres";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private options;
+    /**
+     * 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.
+     */
+    private pool;
+    private pgModule;
+    /** The pool of the caller's the adapter was given, which `open()` takes up again after `close()`. */
+    private readonly givenPool;
+    /** Whether `close()` ends the pool. */
+    private readonly ownsPool;
+    private readonly segmentStatements;
+    /** The error listener the adapter has on a pool, and that pool. */
+    private listening;
+    private opening;
+    private closing;
+    constructor(options: PostgresAdapterOptions | string);
+    /**
+     * 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(): PostgresPoolLike | null;
+    /**
+     * Lazy loader for pg module to keep the dependency optional and prevent bundling in browser builds.
+     */
+    private loadPgModule;
+    /**
+     * 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?: StorageOpenOptions): Promise<void>;
+    private openNow;
+    /** The configuration of the pool the adapter makes. */
+    private poolConfig;
+    /** Puts the adapter's error listener on `pool`: `onError`, or the warning on a pool it owns. */
+    private listenOn;
+    /** The runner of statements outside a transaction. */
+    private readonly query;
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    get<T>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    exec(script: string): Promise<void>;
+    /**
+     * Runs `fn` in a transaction on one pooled connection: COMMIT when it
+     * resolves, ROLLBACK when it or COMMIT throws, and that error is rethrown.
+     * `options` sets the isolation level and the read-only and deferrable modes;
+     * an unknown isolation level is refused before a connection is checked out.
+     *
+     * When ROLLBACK fails too (the connection broke), the error thrown is still
+     * the transaction's own, with the ROLLBACK error on it as `rollbackError`,
+     * and the connection is closed instead of returned to the pool. The handle
+     * `fn` receives runs on the pool once the transaction has ended.
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>, options?: PostgresTransactionOptions): Promise<T>;
+    /**
+     * Holds one pooled connection for `fn`, for work that needs one session:
+     * `SET` and other session settings, session advisory locks
+     * (`pg_advisory_lock`), temporary tables, or statements that must not run
+     * inside a transaction. Its statements run outside a transaction unless
+     * `fn` opens one with `connection.transaction()` or `BEGIN`.
+     *
+     * When `fn` resolves, the connection goes back to the pool with its session
+     * state, so undo what `fn` set (or use `SET LOCAL` inside a transaction).
+     * When `fn` throws, the connection is closed instead, which ends its session
+     * state and any transaction it left open, and `fn`'s error is rethrown.
+     * When `fn` resolves inside a transaction it began and did not end, the
+     * 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. On a
+     * segmented adapter the connection starts in the segment, as every
+     * connection of its pool does.
+     */
+    withConnection<T>(fn: (connection: PostgresConnection) => Promise<T>): Promise<T>;
+    /**
+     * 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(): PostgresPoolStats | 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(): Promise<void>;
+    private closeNow;
+    private requirePool;
+}
+/**
+ * Create a PostgreSQL adapter with connection string.
+ * @param connectionString - PostgreSQL connection string
+ * @example
+ * ```typescript
+ * const db = createPostgresAdapter('postgresql://user:pass@localhost:5432/mydb');
+ * ```
+ */
+export declare function createPostgresAdapter(connectionString: string): StorageAdapter;
+/**
+ * Create a PostgreSQL adapter with configuration options.
+ * @param options - PostgreSQL adapter configuration
+ * @example
+ * ```typescript
+ * const db = createPostgresAdapter({
+ *   host: 'db.example.com',
+ *   database: 'mydb',
+ *   user: 'dbuser',
+ *   password: 'secure_password',
+ *   ssl: true
+ * });
+ * ```
+ */
+export declare function createPostgresAdapter(options: PostgresAdapterOptions): StorageAdapter;
+//# sourceMappingURL=postgresAdapter.d.ts.map