ts-prorm-orm 1.1.0 → 1.2.1

package/dist/dialects/postgres/index.d.ts

@@ -0,0 +1,1598 @@
+/**
+ * PostgreSQL dialect implementation for the TypeScript ORM
+ */
+import type { Pool, PoolClient } from 'pg';
+import { Dialect, DialectOptions, ColumnDefinition, TableOptions, DropTableOptions, TableDescription, IndexOptions, InsertOptions, UpdateOptions as DUpdateOptions, DeleteOptions, SelectOptions, CTEOption, UpsertQueryOptions, CreateExtensionOptions, DropExtensionOptions, ExtensionInfo, CreateEnumTypeOptions, DropTypeOptions, CreateDomainOptions, DropDomainOptions, FdwForeignServerOptions, FdwAlterForeignServerOptions, FdwUserMappingOptions, FdwForeignTableOptions, FdwImportForeignSchemaOptions, ViewOptions, DropViewOptions, DropSchemaOptions, MaterializedViewOptions, RefreshOptions, DropMaterializedViewOptions } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, StreamOptions, DataType, WhereOptions, Order, PartitionDefinition, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, TriggerOptions, DropTriggerOptions, SequenceOptions, DropSequenceOptions, PolicyOptions, DropPolicyOptions } from '../../types';
+/**
+ * A single `WHEN MATCHED [AND condition] THEN ...` clause for `buildMergeQuery`.
+ */
+export interface MergeWhenMatchedClause {
+    /** Additional `AND` condition appended to `WHEN MATCHED` */
+    condition?: string;
+    /** The action to take: UPDATE the matched row, DELETE it, or DO NOTHING */
+    then: 'UPDATE' | 'DELETE' | 'DO NOTHING';
+    /** Column/value pairs for the `UPDATE SET` clause (required when `then === 'UPDATE'`) */
+    set?: Record<string, unknown>;
+}
+/**
+ * A single `WHEN NOT MATCHED [AND condition] THEN ...` clause for `buildMergeQuery`.
+ */
+export interface MergeWhenNotMatchedClause {
+    /** Additional `AND` condition appended to `WHEN NOT MATCHED` */
+    condition?: string;
+    /** The action to take: INSERT a new row, or DO NOTHING */
+    then: 'INSERT' | 'DO NOTHING';
+    /** Columns to insert into (required when `then === 'INSERT'`) */
+    columns?: string[];
+    /** Values corresponding to `columns` (required when `then === 'INSERT'`) */
+    values?: unknown[];
+}
+/**
+ * Options shared by `PostgresDialect.copyFrom` and `PostgresDialect.copyTo`, mirroring
+ * PostgreSQL's `COPY ... WITH (...)` options: https://www.postgresql.org/docs/current/sql-copy.html
+ */
+export interface CopyOptions {
+    /** `FORMAT` — defaults to `'CSV'` when a `delimiter`/`header`/`quote`/`escape` option is given, otherwise `'TEXT'`. */
+    format?: 'CSV' | 'TEXT' | 'BINARY';
+    /** `DELIMITER 'char'` — single character that separates columns. Defaults to `,` for CSV, tab for TEXT. */
+    delimiter?: string;
+    /**
+     * `HEADER` — for `copyFrom`, whether the source's first line is a header row to skip.
+     * For `copyTo`, whether to emit a header row. Only valid for CSV format (and TEXT since PG 17).
+     */
+    header?: boolean;
+    /** `NULL 'string'` — string that represents a null value. Defaults to `\N` for TEXT, unquoted empty string for CSV. */
+    null?: string;
+    /** `QUOTE 'char'` — quoting character for CSV format. Defaults to double-quote. */
+    quote?: string;
+    /** `ESCAPE 'char'` — escape character for CSV format. Defaults to the QUOTE value. */
+    escape?: string;
+    /** `ENCODING 'name'` — character set encoding of the copy data. */
+    encoding?: string;
+    /** `FREEZE` — (COPY FROM only) performs the copy as though it were run in a newly created table/index. */
+    freeze?: boolean;
+    /** Explicit column list, e.g. `['id', 'name']`. When omitted, all columns are used (in table order). */
+    columns?: string[];
+}
+/**
+ * PostgreSQL dialect class that implements the Dialect interface
+ */
+export declare class PostgresDialect implements Dialect {
+    readonly name: string;
+    readonly library: string;
+    private pool;
+    private _isConnected;
+    private config;
+    private transactionDepth;
+    /**
+     * Dedicated (non-pooled) client used for LISTEN/NOTIFY. Postgres notifications are only
+     * delivered to the specific backend connection that issued LISTEN, so a pooled connection
+     * cannot be used reliably (the pool may hand that connection back out or close it). We lazily
+     * open a single long-lived `pg.Client` the first time `listen()` is called and keep it open
+     * for the lifetime of the dialect (or until `disconnect()`/`unlisten()` closes it out).
+     */
+    private notifyClient;
+    private notifyChannels;
+    private notifyConnectPromise;
+    constructor(config: PostgresDialectOptions);
+    /**
+     * Connect to the PostgreSQL database
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the PostgreSQL database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get the current connection pool
+     */
+    getConnection(): Pool | null;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Lazily creates (or returns the existing) dedicated client used to receive Postgres
+     * notifications. This client is separate from the pool because `LISTEN` registers interest
+     * on the specific backend connection - handing that connection back to a pool would mean
+     * notifications get delivered to whichever caller happens to check the connection out next.
+     */
+    private getNotifyClient;
+    /**
+     * Subscribe to a PostgreSQL notification channel (`LISTEN channel`). The provided callback
+     * is invoked with the notification payload every time `NOTIFY channel, 'payload'` (or
+     * `pg_notify('channel', 'payload')`) is executed by any backend, including this one.
+     *
+     * Returns an unsubscribe function that removes just this callback; use `unlisten()` to
+     * drop the entire channel subscription (issues `UNLISTEN` on the dedicated connection).
+     */
+    listen(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+    /**
+     * Unsubscribe from a PostgreSQL notification channel entirely (`UNLISTEN channel`), removing
+     * all callbacks registered for it via `listen()`.
+     */
+    unlisten(channel: string): Promise<void>;
+    /**
+     * Send a PostgreSQL notification (`NOTIFY channel, 'payload'` / `pg_notify(channel, payload)`).
+     * Uses `pg_notify()` with bound parameters (rather than string-interpolated `NOTIFY`) so the
+     * payload can safely contain arbitrary text without manual escaping.
+     */
+    notify(channel: string, payload?: string): Promise<void>;
+    /**
+     * Execute a raw SQL query with retry support
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and stream results using PostgreSQL cursor
+     * Uses server-side cursors for efficient memory usage with large datasets
+     * @param sql - The SQL query string
+     * @param options - Stream options
+     * @returns Readable stream for streaming results
+     */
+    queryStream(sql: string, options?: StreamOptions): import('stream').Readable;
+    /**
+     * Execute a function with retry logic for query execution
+     */
+    private executeWithRetry;
+    /**
+     * Escape a value for use in a query
+     */
+    escape(value: unknown): string;
+    /**
+     * Escape a string for SQL
+     */
+    private escapeString;
+    /**
+     * Format a date for PostgreSQL
+     */
+    private formatDate;
+    /**
+     * Escape an identifier (table name, column name, etc.)
+     * PostgreSQL uses double quotes for identifiers
+     */
+    escapeId(identifier: unknown): string;
+    /**
+     * Quote an identifier (column name, table name)
+     * PostgreSQL uses double quotes for identifiers
+     */
+    quoteIdentifier(identifier: string): string;
+    /**
+     * Quote a table name
+     * Includes schema prefix if provided
+     */
+    quoteTable(tableName: string, schema?: string): string;
+    /**
+     * Get the database version
+     */
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * Create a database schema
+     * @param schema - The schema name to create
+     */
+    createSchema(schema: string): Promise<void>;
+    /**
+     * Drop a database schema
+     * @param schema - The schema name to drop
+     * @param options - Drop options (e.g., cascade)
+     */
+    dropSchema(schema: string, options?: DropSchemaOptions): Promise<void>;
+    /**
+     * Show all schemas in the database
+     */
+    showAllSchemas(): Promise<string[]>;
+    /**
+     * List all schemas in the database
+     */
+    listSchemas(): Promise<string[]>;
+    /**
+     * Replace placeholders in SQL with actual values
+     * @param sql - SQL string with placeholders
+     * @param replacements - Object or array of replacement values
+     */
+    /**
+     * Format a single JS value as a SQL literal for inlining into a query
+     * (used by replaceReplacements() below, which inlines values into the SQL text
+     * rather than sending them as real driver parameters).
+     *
+     * Without this, plain objects/arrays fell through to the `String(value)` fallback:
+     * `String({a: 1})` produces the bare text `[object Object]` and `String(['a', 'b'])`
+     * produces the unquoted, comma-joined text `a,b` - both invalid or wrong SQL, and the
+     * array case is silently misinterpreted as bare column references (`a`, `b`) rather
+     * than a PostgreSQL array literal.
+     */
+    private formatReplacementValue;
+    replaceReplacements(sql: string, replacements?: Record<string, unknown> | unknown[]): string;
+    /**
+     * Create a new table
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions): Promise<void>;
+    /**
+     * Build constraint SQL for table creation
+     */
+    private buildConstraintSql;
+    /**
+     * Generate column definition SQL for PostgreSQL
+     */
+    private getColumnDefinitionSql;
+    /**
+     * Get default value SQL
+     */
+    private getDefaultValue;
+    /**
+     * Drop a table
+     */
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * List all materialized view names in the database.
+     */
+    listMaterializedViews(schema?: string): Promise<string[]>;
+    /**
+     * Create a partitioned table (PostgreSQL 10+)
+     *
+     * @param tableName - Name of the table to create
+     * @param columns - Column definitions
+     * @param options - Table options including partition configuration
+     */
+    createPartitionedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & {
+        partitionBy: {
+            type: 'range' | 'list' | 'hash';
+            column: string | string[];
+        };
+        partitions?: PartitionDefinition[];
+    }): Promise<void>;
+    /**
+     * Create a partition for an existing partitioned table (PostgreSQL 10+)
+     *
+     * @param options - Partition creation options
+     */
+    createPartition(options: CreatePartitionOptions): Promise<void>;
+    /**
+     * Attach a partition to a partitioned table (PostgreSQL 11+)
+     *
+     * @param options - Partition attachment options
+     */
+    attachPartition(options: AttachPartitionOptions): Promise<void>;
+    /**
+     * Detach a partition from a partitioned table (PostgreSQL 11+)
+     *
+     * @param options - Partition detachment options
+     */
+    detachPartition(options: DetachPartitionOptions): Promise<void>;
+    /**
+     * Drop a partition (PostgreSQL 10+)
+     *
+     * @param partitionName - Name of the partition to drop
+     * @param options - Drop options
+     */
+    dropPartition(partitionName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * Add a partition to an existing partitioned table (PostgreSQL 10+)
+     * @param tableName - Name of the partitioned table
+     * @param partitionName - Name for the new partition
+     * @param partitionSpec - Partition specification
+     */
+    addPartition(tableName: string, partitionName: string, partitionSpec: {
+        values?: string;
+        forValues?: string;
+    }): Promise<void>;
+    /**
+     * Create a database view
+     */
+    createView(viewName: string, query: string, options?: ViewOptions): Promise<void>;
+    /**
+     * Drop a database view
+     */
+    dropView(viewName: string, options?: DropViewOptions): Promise<void>;
+    /**
+     * Show all views in the database
+     */
+    showViews(): Promise<string[]>;
+    /**
+     * Create a materialized view
+     * @param options - Materialized view options
+     */
+    createMaterializedView(options: MaterializedViewOptions): Promise<void>;
+    /**
+     * Refresh a materialized view
+     * @param viewName - Name of the materialized view to refresh
+     * @param options - Refresh options
+     */
+    refreshMaterializedView(viewName: string, options?: RefreshOptions): Promise<void>;
+    /**
+     * Drop a materialized view
+     * @param viewName - Name of the materialized view to drop
+     * @param options - Drop options
+     */
+    dropMaterializedView(viewName: string, options?: DropMaterializedViewOptions): Promise<void>;
+    /**
+     * Check if a materialized view exists
+     * @param viewName - Name of the materialized view
+     * @returns True if the materialized view exists
+     */
+    hasMaterializedView(viewName: string): Promise<boolean>;
+    /**
+     * Show all materialized views in the database
+     */
+    showMaterializedViews(): Promise<string[]>;
+    /**
+     * Create a stored procedure (PostgreSQL 11+)
+     */
+    createStoredProcedure(options: StoredProcedureOptions): Promise<void>;
+    /**
+     * Create a foreign data wrapper (PostgreSQL)
+     * @param fdwName - Foreign data wrapper name
+     * @param options - Options including handler function
+     */
+    createForeignDataWrapper(fdwName: string, options?: {
+        handler?: string;
+    }): Promise<void>;
+    dropForeignDataWrapper(fdwName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    createForeignServer(serverName: string, fdwName: string, options?: {
+        options?: Record<string, string>;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    dropForeignServer(serverName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    createForeignTable(tableName: string, columns: Record<string, {
+        type: string;
+    }>, options?: {
+        serverName?: string;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    changeOwner(newOwner: string, tableName: string): Promise<void>;
+    addConstraint(tableName: string, options: {
+        type: 'UNIQUE' | 'CHECK' | 'PRIMARY KEY' | 'FOREIGN KEY';
+        fields: string[];
+        name?: string;
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        check?: string;
+    }): Promise<void>;
+    removeConstraint(tableName: string, constraintName: string): Promise<void>;
+    /**
+     * Alias for createPolicy() using the generic cross-dialect security-policy shape.
+     * PostgreSQL's row-level security is implemented via createPolicy()/dropPolicy(); this
+     * method exists only to satisfy the abstract Dialect contract and simply forwards to it.
+     */
+    createSecurityPolicy(policyName: string, tableName: string, options?: {
+        predicate?: string;
+    }): Promise<void>;
+    /**
+     * Alias for dropPolicy() - see createSecurityPolicy().
+     */
+    dropSecurityPolicy(policyName: string, tableName: string): Promise<void>;
+    /**
+     * Drop a stored procedure
+     */
+    dropStoredProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    /**
+     * Drop a stored procedure (alias for dropStoredProcedure)
+     */
+    dropProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    /**
+     * Create a stored procedure (alias for createStoredProcedure)
+     */
+    createProcedure(options: StoredProcedureOptions): Promise<void>;
+    /**
+     * Execute a stored procedure
+     */
+    executeStoredProcedure(options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
+    /**
+     * Check if a stored procedure exists
+     */
+    hasStoredProcedure(procedureName: string, schema?: string): Promise<boolean>;
+    /**
+     * Create a trigger
+     */
+    createTrigger(options: TriggerOptions): Promise<void>;
+    /**
+     * Drop a trigger
+     */
+    dropTrigger(triggerName: string, tableName: string, options?: DropTriggerOptions): Promise<void>;
+    /**
+     * Check if a trigger exists
+     */
+    hasTrigger(triggerName: string, tableName: string): Promise<boolean>;
+    /**
+     * Create a sequence
+     */
+    createSequence(options: SequenceOptions): Promise<void>;
+    /**
+     * Drop a sequence
+     */
+    dropSequence(sequenceName: string, options?: DropSequenceOptions): Promise<void>;
+    /**
+     * Get next value from a sequence
+     */
+    nextSequenceValue(sequenceName: string): Promise<number>;
+    /**
+     * Get the current (session-local) value of a sequence.
+     * Requires nextval() to have been called at least once in the current session.
+     */
+    currSequenceValue(sequenceName: string): Promise<number>;
+    /**
+     * Check if a sequence exists
+     */
+    hasSequence(sequenceName: string): Promise<boolean>;
+    /**
+     * List all sequences in the database (PostgreSQL)
+     * @returns Array of sequence names
+     */
+    listSequences(): Promise<string[]>;
+    /**
+     * Create a policy (PostgreSQL RLS)
+     */
+    createPolicy(options: PolicyOptions): Promise<void>;
+    /**
+     * Drop a policy (PostgreSQL RLS)
+     */
+    dropPolicy(policyName: string, tableName: string, options?: DropPolicyOptions): Promise<void>;
+    /**
+     * Enable row-level security on a table (PostgreSQL)
+     */
+    enableRLS(tableName: string, schema?: string): Promise<void>;
+    /**
+     * Enable row-level security on a table (alias for enableRLS)
+     */
+    enableRowLevelSecurity(tableName: string, schema?: string): Promise<void>;
+    /**
+     * Disable row-level security on a table (PostgreSQL)
+     */
+    disableRLS(tableName: string, schema?: string): Promise<void>;
+    /**
+     * Disable row-level security on a table (alias for disableRLS, matching enableRowLevelSecurity)
+     */
+    disableRowLevelSecurity(tableName: string, schema?: string): Promise<void>;
+    /**
+     * Check if a policy exists (PostgreSQL RLS)
+     */
+    hasPolicy(policyName: string, tableName: string): Promise<boolean>;
+    /**
+     * Add comment to a table
+     */
+    commentTable(tableName: string, comment: string): Promise<void>;
+    /**
+     * Add comment to a column
+     */
+    commentColumn(tableName: string, columnName: string, comment: string): Promise<void>;
+    /**
+     * Create a partial index (index with WHERE clause)
+     */
+    createPartialIndex(tableName: string, indexName: string, fields: string[], where: string, options?: IndexOptions): Promise<void>;
+    /**
+     * Create an expression index
+     */
+    createExpressionIndex(tableName: string, indexName: string, expression: string, options?: IndexOptions): Promise<void>;
+    /**
+     * Create a fulltext index (PostgreSQL)
+     * Uses GIN index for fulltext search
+     * @param tableName - Table name
+     * @param indexName - Index name
+     * @param fields - Fields to index
+     * @param options - Fulltext index options
+     */
+    createFulltextIndex(tableName: string, indexName: string, fields: string[], options?: {
+        parser?: string;
+        comment?: string;
+    }): Promise<void>;
+    /**
+     * Create a spatial index (PostgreSQL)
+     * Uses GIST index for spatial data
+     * @param tableName - Table name
+     * @param indexName - Index name
+     * @param fields - Fields to index
+     * @param options - Spatial index options
+     */
+    createSpatialIndex(tableName: string, indexName: string, fields: string[], options?: {
+        storage?: string;
+        srid?: number;
+    }): Promise<void>;
+    /**
+     * Bulk insert records into a table
+     */
+    bulkInsert(tableName: string, records: Record<string, any>[], _options?: any): Promise<QueryResult>;
+    /**
+     * Add a foreign key to a table
+     */
+    addForeignKey(tableName: string, columnName: string, referencedTableName: string, referencedColumnName: string, options?: {
+        name?: string;
+        onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+        onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    }): Promise<void>;
+    /**
+     * Rename a column
+     */
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    /**
+     * Create an identity column
+     */
+    createIdentityColumn(tableName: string, columnName: string, options?: {
+        startWith?: number;
+        incrementBy?: number;
+        minvalue?: number;
+        maxvalue?: number;
+        cycle?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a computed column (generated column)
+     */
+    createComputedColumn(tableName: string, columnName: string, expression: string, options?: {
+        persisted?: boolean;
+        type?: string;
+    }): Promise<void>;
+    /**
+     * Create a PostgreSQL extension
+     * @param extensionName - Name of the extension to create
+     * @param options - Extension options
+     */
+    createExtension(extensionName: string, options?: CreateExtensionOptions): Promise<void>;
+    /**
+     * Drop a PostgreSQL extension
+     * @param extensionName - Name of the extension to drop
+     * @param options - Drop options
+     */
+    dropExtension(extensionName: string, options?: DropExtensionOptions): Promise<void>;
+    /**
+     * Get all installed PostgreSQL extensions
+     * @returns Array of extension information
+     */
+    getExtensions(): Promise<ExtensionInfo[]>;
+    /**
+     * Check if a PostgreSQL extension is installed
+     * @param extensionName - Name of the extension
+     * @returns True if the extension is installed
+     */
+    hasExtension(extensionName: string): Promise<boolean>;
+    /**
+     * Create a PostgreSQL enum type: `CREATE TYPE name AS ENUM ('a', 'b', ...)`.
+     *
+     * Postgres has no native `CREATE TYPE IF NOT EXISTS`; pass `options.ifNotExists`
+     * to have this method check `pg_type` first and skip creation if the type
+     * already exists.
+     *
+     * @param name - Name of the type to create
+     * @param values - Enum label values, in the order they should sort
+     * @param options - Schema and if-not-exists options
+     */
+    createEnumType(name: string, values: string[], options?: CreateEnumTypeOptions): Promise<void>;
+    /**
+     * Drop a PostgreSQL type (e.g. one created with `createEnumType`).
+     * `DROP TYPE [IF EXISTS] name [CASCADE | RESTRICT]`.
+     *
+     * @param name - Name of the type to drop
+     * @param options - If-exists, cascade, and schema options
+     */
+    dropType(name: string, options?: DropTypeOptions): Promise<void>;
+    /**
+     * Create a PostgreSQL domain: `CREATE DOMAIN name AS base_type [DEFAULT ...]
+     * [COLLATE ...] [NOT NULL] [CONSTRAINT name CHECK (...)] ...`.
+     *
+     * @param name - Name of the domain to create
+     * @param baseType - Underlying data type the domain is based on, e.g. `'INTEGER'` or `'VARCHAR(255)'`
+     * @param options - Default value, collation, nullability, and CHECK constraints
+     */
+    createDomain(name: string, baseType: string, options?: CreateDomainOptions): Promise<void>;
+    /**
+     * Drop a PostgreSQL domain. `DROP DOMAIN [IF EXISTS] name [CASCADE | RESTRICT]`.
+     *
+     * @param name - Name of the domain to drop
+     * @param options - If-exists, cascade, and schema options
+     */
+    dropDomain(name: string, options?: DropDomainOptions): Promise<void>;
+    /**
+     * Lazily loads `pg-copy-streams`, throwing a clear error (with install instructions) if it
+     * isn't available. Kept as a single choke point so both `copyFrom` and `copyTo` fail the
+     * same way.
+     */
+    private loadCopyStreams;
+    /**
+     * Build the `WITH (...)` options clause shared by `COPY ... FROM STDIN` and `COPY ... TO STDOUT`.
+     */
+    private buildCopyOptionsSql;
+    /**
+     * Bulk-load data into a table using PostgreSQL's `COPY ... FROM STDIN`.
+     *
+     * Requires the optional `pg-copy-streams` package (see the comment above this section);
+     * throws a descriptive error if it isn't installed.
+     *
+     * @param tableName - Table to load data into
+     * @param source - Where the copy data comes from:
+     *   - A Node `Readable` stream (piped directly into the COPY stream)
+     *   - A `string` of pre-formatted CSV/text COPY data
+     *   - An array of rows, each either an array of column values or a plain object keyed by
+     *     column name - these are serialized to CSV using `options`
+     * @param options - `FORMAT`/`DELIMITER`/`HEADER`/`NULL`/`QUOTE`/`ESCAPE`/column-list options
+     * @returns The number of rows copied
+     */
+    copyFrom(tableName: string, source: NodeJS.ReadableStream | string | Array<unknown[] | Record<string, unknown>>, options?: CopyOptions): Promise<{
+        rowCount: number;
+    }>;
+    /**
+     * Serialize a single value for inclusion in hand-built CSV/TEXT COPY data (used by
+     * `copyFrom` when given an array of rows rather than a pre-formatted stream/string).
+     */
+    private formatCopyValue;
+    /**
+     * Bulk-export data from a table (or query) using PostgreSQL's `COPY ... TO STDOUT`.
+     *
+     * Requires the optional `pg-copy-streams` package (see the comment above this section);
+     * throws a descriptive error if it isn't installed.
+     *
+     * @param tableName - Table (or, if `options.query` is set, ignored in favor of that query) to export from
+     * @param destination - A Node `Writable` to pipe copy data into. When omitted, the copied
+     *   data is buffered in memory and returned as a string instead - convenient for small
+     *   exports, but not recommended for large tables.
+     * @param options - `FORMAT`/`DELIMITER`/`HEADER`/`NULL`/`QUOTE`/`ESCAPE`/column-list options,
+     *   plus an optional `query` to export the result of an arbitrary `SELECT` instead of a whole table
+     * @returns The destination stream (if provided) or the exported data as a string
+     */
+    copyTo(tableName: string, destination?: NodeJS.WritableStream, options?: CopyOptions & {
+        query?: string;
+    }): Promise<NodeJS.WritableStream | string>;
+    /**
+     * Build a vector similarity distance expression using a pgvector operator.
+     *
+     * Requires the `pgvector` extension to be installed (see `createExtension('vector')`
+     * / `hasExtension('vector')`). The returned SQL can be used directly in an
+     * `ORDER BY` clause (nearest-neighbor search) or a `WHERE` clause (thresholding).
+     *
+     * @param column - Column name holding the `vector` value
+     * @param vector - Query vector to compare against
+     * @param metric - Distance metric:
+     *   - 'l2' (default) uses `<->` (Euclidean/L2 distance)
+     *   - 'cosine' uses `<=>` (cosine distance)
+     *   - 'innerProduct' uses `<#>` (negative inner product)
+     * @param paramIndex - Starting placeholder index (defaults to 1) so callers can
+     *   splice this expression into a larger parameterized query
+     * @returns SQL expression and the values to bind to its placeholder
+     */
+    buildVectorDistance(column: string, vector: number[], metric?: 'l2' | 'cosine' | 'innerProduct', paramIndex?: number): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Create a pgvector ANN (approximate nearest neighbor) index using `ivfflat` or `hnsw`.
+     *
+     * Requires the `pgvector` extension (see `createExtension('vector')`). Example output:
+     *   CREATE INDEX idx ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)
+     *   CREATE INDEX idx ON items USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64)
+     *
+     * @param tableName - Table name
+     * @param indexName - Index name
+     * @param column - Vector column name
+     * @param options - Index method and tuning parameters
+     */
+    createVectorIndex(tableName: string, indexName: string, column: string, options?: {
+        method?: 'ivfflat' | 'hnsw';
+        metric?: 'l2' | 'cosine' | 'innerProduct';
+        lists?: number;
+        m?: number;
+        efConstruction?: number;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Build CREATE FOREIGN SERVER SQL.
+     *
+     * CREATE FOREIGN SERVER [IF NOT EXISTS] name
+     *   FOREIGN DATA WRAPPER fdw_name
+     *   [VERSION 'version']
+     *   [OPTIONS (key 'value', ...)];
+     */
+    buildCreateServerQuery(name: string, opts: FdwForeignServerOptions): string;
+    /**
+     * Build ALTER FOREIGN SERVER SQL.
+     *
+     * ALTER FOREIGN SERVER name
+     *   [VERSION 'version']
+     *   [OPTIONS ([ADD|SET|DROP] key ['value'], ...)];
+     */
+    buildAlterServerQuery(name: string, opts: FdwAlterForeignServerOptions): string;
+    /**
+     * Build DROP FOREIGN SERVER SQL.
+     *
+     * DROP FOREIGN SERVER [IF EXISTS] name [CASCADE|RESTRICT];
+     */
+    buildDropServerQuery(name: string, opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    /**
+     * Return the SQL to list all foreign servers from the catalog.
+     */
+    getServersQuery(): string;
+    /**
+     * List all foreign server names. Thin wrapper around getServersQuery().
+     */
+    listServers(): Promise<string[]>;
+    /**
+     * Build CREATE USER MAPPING SQL.
+     *
+     * CREATE USER MAPPING [IF NOT EXISTS] FOR { user | CURRENT_USER | PUBLIC }
+     *   SERVER server_name
+     *   [OPTIONS (key 'value', ...)];
+     */
+    buildCreateUserMappingQuery(opts: FdwUserMappingOptions): string;
+    /**
+     * Build ALTER USER MAPPING SQL.
+     *
+     * ALTER USER MAPPING FOR { user | CURRENT_USER | PUBLIC }
+     *   SERVER server_name
+     *   OPTIONS (...);
+     */
+    buildAlterUserMappingQuery(opts: FdwUserMappingOptions): string;
+    /**
+     * Build DROP USER MAPPING SQL.
+     *
+     * DROP USER MAPPING [IF EXISTS] FOR { user | CURRENT_USER | PUBLIC }
+     *   SERVER server_name;
+     */
+    buildDropUserMappingQuery(serverName: string, user: string, opts?: {
+        ifExists?: boolean;
+    }): string;
+    /**
+     * Create a user mapping for a foreign server
+     */
+    createUserMapping(userName: string, serverName: string, options?: {
+        username?: string;
+        password?: string;
+    }): Promise<void>;
+    /**
+     * Drop a user mapping for a foreign server
+     */
+    dropUserMapping(userName: string, serverName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Build CREATE FOREIGN TABLE SQL.
+     *
+     * CREATE FOREIGN TABLE [IF NOT EXISTS] [schema.]table_name (
+     *   col1 type [OPTIONS (...)],
+     *   ...
+     * ) SERVER server_name [OPTIONS (key 'value', ...)];
+     */
+    buildCreateForeignTableQuery(tableName: string, opts: FdwForeignTableOptions): string;
+    /**
+     * Build DROP FOREIGN TABLE SQL.
+     *
+     * DROP FOREIGN TABLE [IF EXISTS] table_name [CASCADE|RESTRICT];
+     */
+    buildDropForeignTableQuery(tableName: string, opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    /**
+     * Build IMPORT FOREIGN SCHEMA SQL.
+     *
+     * IMPORT FOREIGN SCHEMA remote_schema
+     *   [LIMIT TO (t1, t2) | EXCEPT (t1, t2)]
+     *   FROM SERVER server_name
+     *   INTO local_schema
+     *   [OPTIONS (key 'value', ...)];
+     */
+    buildImportForeignSchemaQuery(remoteSchema: string, serverName: string, opts?: FdwImportForeignSchemaOptions): string;
+    /**
+     * Add a column to a table
+     */
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Remove a column from a table
+     */
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    /**
+     * Change a column definition
+     */
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Show all tables in the database
+     */
+    showTables(): Promise<string[]>;
+    /**
+     * Get table status (PostgreSQL implementation)
+     */
+    getTableStatus(tableName?: string): Promise<Record<string, any>[]>;
+    /**
+     * Get table create statement (PostgreSQL implementation)
+     */
+    getCreateTable(tableName: string): Promise<string>;
+    /**
+     * List the child partitions of a partitioned table (PostgreSQL implementation).
+     * Uses pg_inherits/pg_class, the standard catalog tables for native partitioning.
+     */
+    listPartitions(tableName: string): Promise<Array<{
+        name: string;
+        parentTable: string;
+        bound: string | null;
+    }>>;
+    /**
+     * Check if a table has partitions (PostgreSQL implementation)
+     */
+    hasPartition(tableName: string): Promise<boolean>;
+    /**
+     * Show constraints for a table
+     */
+    showConstraints(tableName: string): Promise<any[]>;
+    /**
+     * Show indexes for a table
+     */
+    showIndexes(tableName: string): Promise<any[]>;
+    /**
+     * Describe a table (get column information)
+     */
+    describeTable(tableName: string): Promise<TableDescription>;
+    /**
+     * Rename a table
+     */
+    renameTable(oldName: string, newName: string): Promise<void>;
+    /**
+     * Add an index to a table
+     */
+    addIndex(tableName: string, indexName: string, fields?: string[], options?: IndexOptions): Promise<void>;
+    /**
+     * Remove an index from a table
+     */
+    removeIndex(tableName: string, indexName: string): Promise<void>;
+    /**
+     * Create an index on a table with full options support
+     */
+    createIndex(tableName: string, indexDef: {
+        name: string;
+        unique?: boolean;
+        type?: string;
+        using?: string;
+        fields: string[];
+        where?: WhereOptions;
+        expression?: string;
+        include?: string[];
+    }): Promise<void>;
+    /**
+     * Create a GIN index for full-text search
+     * PostgreSQL-specific GIN (Generalized Inverted Index) for tsvector
+     */
+    createGINIndex(tableName: string, indexName: string, column: string, options?: {
+        config?: string;
+        storageParameters?: Record<string, string | number>;
+    }): Promise<void>;
+    /**
+     * Build a to_tsvector expression
+     * SQL: to_tsvector([config,] document)
+     */
+    buildTsVector(column: string | string[], config?: string): string;
+    /**
+     * Build a to_tsquery expression
+     * SQL: to_tsquery([config,] query)
+     */
+    buildTsQuery(query: string, config?: string): string;
+    /**
+     * Build a plainto_tsquery expression (for phrase searching)
+     * SQL: plainto_tsquery([config,] query)
+     * Converts a phrase into a tsquery that matches documents containing all the words
+     */
+    buildPlainTsQuery(query: string, config?: string): string;
+    /**
+     * Build a phraseto_tsquery expression (for exact phrase matching)
+     * SQL: phraseto_tsquery([config,] query)
+     * Converts a phrase into a tsquery that matches documents containing the exact phrase
+     */
+    buildPhraseTsQuery(query: string, config?: string): string;
+    /**
+     * Build a websearch_to_tsquery expression (for web search style queries)
+     * SQL: websearch_to_tsquery([config,] query)
+     * Supports web search operators like +, -, "quotes", etc.
+     */
+    buildWebsearchTsQuery(query: string, config?: string): string;
+    /**
+     * Build a ts_rank expression for ranking full-text search results
+     * SQL: ts_rank([weights,] vector, query [, normalization])
+     */
+    buildTsRank(vector: string, query: string, options?: {
+        weights?: number[];
+        normalization?: number;
+    }): string;
+    /**
+     * Create a GIST index for spatial data
+     * PostgreSQL GIST (Generalized Search Tree) index for geometry/geography columns
+     */
+    createGISTIndex(tableName: string, indexName: string, column: string, options?: {
+        /** Use geography instead of geometry */
+        geography?: boolean;
+        /** Geometry type constraint (e.g., 'POINT', 'POLYGON') */
+        geometryType?: string;
+        /** SRID constraint (e.g., 4326 for WGS84) */
+        srid?: number;
+        /** Storage parameters */
+        fillFactor?: number;
+    }): Promise<void>;
+    /**
+     * Create a GIN index for spatial data (PostGIS 2.1+)
+     * GIN indexes are slower to build but faster for very large datasets with many overlapping geometries
+     */
+    createGINSpatialIndex(tableName: string, indexName: string, column: string): Promise<void>;
+    /**
+     * ST_Distance - calculate distance between two geometries
+     * For geography, returns distance in meters
+     */
+    stDistance(geom1: string, geom2: string, useGeography?: boolean): string;
+    /**
+     * ST_DWithin - check if geometries are within a given distance
+     * For geography, distance is in meters
+     */
+    stDWithin(geom1: string, geom2: string, distance: number, useGeography?: boolean): string;
+    /**
+     * ST_Within - check if geometry A is within geometry B
+     */
+    stWithin(geom1: string, geom2: string): string;
+    /**
+     * ST_Contains - check if geometry A contains geometry B
+     */
+    stContains(geom1: string, geom2: string): string;
+    /**
+     * ST_Intersects - check if two geometries intersect
+     */
+    stIntersects(geom1: string, geom2: string): string;
+    /**
+     * ST_Crosses - check if two geometries cross
+     */
+    stCrosses(geom1: string, geom2: string): string;
+    /**
+     * ST_Overlaps - check if two geometries overlap
+     */
+    stOverlaps(geom1: string, geom2: string): string;
+    /**
+     * ST_Touches - check if two geometries touch
+     */
+    stTouches(geom1: string, geom2: string): string;
+    /**
+     * ST_Equals - check if two geometries are equal
+     */
+    stEquals(geom1: string, geom2: string): string;
+    /**
+     * ST_IsValid - check if a geometry is valid
+     */
+    stIsValid(geom: string): string;
+    /**
+     * ST_GeomFromText - create geometry from WKT text
+     */
+    stGeomFromText(wkt: string, srid?: number): string;
+    /**
+     * ST_GeomFromGeoJSON - create geometry from GeoJSON
+     */
+    stGeomFromGeoJSON(geojson: string, srid?: number): string;
+    /**
+     * ST_AsGeoJSON - convert geometry to GeoJSON
+     */
+    stAsGeoJSON(geom: string, options?: {
+        precision?: number;
+        longCRS?: boolean;
+    }): string;
+    /**
+     * ST_AsText - convert geometry to WKT
+     */
+    stAsText(geom: string): string;
+    /**
+     * ST_Centroid - get the centroid of a geometry
+     */
+    stCentroid(geom: string): string;
+    /**
+     * ST_Area - calculate the area of a polygon
+     * For geography, returns area in square meters
+     */
+    stArea(geom: string, useGeography?: boolean): string;
+    /**
+     * ST_Length - calculate the length of a line
+     * For geography, returns length in meters
+     */
+    stLength(geom: string, useGeography?: boolean): string;
+    /**
+     * ST_Point - create a point from coordinates
+     */
+    stPoint(long: string, lat: string): string;
+    /**
+     * ST_SetSRID - set the SRID of a geometry
+     */
+    stSetSRID(geom: string, srid: number): string;
+    /**
+     * ST_SRID - get the SRID of a geometry
+     */
+    stSRID(geom: string): string;
+    /**
+     * ST_X - get the X coordinate of a point
+     */
+    stX(geom: string): string;
+    /**
+     * ST_Y - get the Y coordinate of a point
+     */
+    stY(geom: string): string;
+    /**
+     * ST_Distance_Sphere - calculate distance using sphere (less accurate but faster)
+     * Returns distance in meters
+     */
+    stDistanceSphere(geom1: string, geom2: string): string;
+    /**
+     * ST_Distance_Spheroid - calculate distance using spheroid (accurate)
+     * Returns distance in meters
+     */
+    stDistanceSpheroid(geom1: string, geom2: string): string;
+    /**
+     * Drop an index from a table
+     */
+    dropIndex(tableName: string, indexName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a constraint on a table
+     */
+    createConstraint(tableName: string, constraintDef: {
+        name: string;
+        type: 'PRIMARY KEY' | 'UNIQUE' | 'FOREIGN KEY' | 'CHECK' | 'EXCLUDE';
+        fields?: string[];
+        references?: {
+            table: string;
+            field: string;
+            onDelete?: string;
+            onUpdate?: string;
+        };
+        check?: string;
+        deferrable?: 'INITIALLY DEFERRED' | 'INITIALLY IMMEDIATE';
+        /**
+         * `EXCLUDE` constraint elements, e.g. `[{ column: 'room_id', operator: '=' },
+         * { column: 'during', operator: '&&' }]` produces
+         * `EXCLUDE USING gist (room_id WITH =, during WITH &&)`.
+         */
+        exclude?: {
+            using?: string;
+            elements: Array<{
+                column: string;
+                operator: string;
+            }>;
+            where?: string;
+        };
+    }): Promise<void>;
+    /**
+     * Drop a constraint from a table
+     */
+    dropConstraint(tableName: string, constraintName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * Begin a new transaction
+     */
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    /**
+     * Commit a transaction
+     */
+    commitTransaction(transaction: Transaction): Promise<void>;
+    /**
+     * Rollback a transaction
+     */
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    /**
+     * Get the SQL for a data type
+     */
+    getDataTypeSql(dataType: DataType): string;
+    /**
+     * Get the SQL for an ARRAY type
+     */
+    getArrayTypeSql(elementType: DataType): string;
+    /**
+     * Get the isolation level SQL
+     */
+    private getIsolationLevelSql;
+    /**
+     * Resolve a WHERE-clause field key to SQL, supporting Sequelize-style inline JSON path
+     * keys like `'data->>active'` or `'data->meta->>role'` (translated to
+     * `"data"->>'active'` / `"data"->'meta'->>'role'`) in addition to plain column names.
+     * Without this, a key containing `->`/`->>` was passed straight to escapeId(), which
+     * double-quotes the whole string as one (nonexistent) column name.
+     */
+    private escapeJsonPathKey;
+    /**
+     * Build a WHERE clause from a WhereOptions object
+     */
+    buildWhereClause(where: WhereOptions, options?: {
+        replacements?: Record<string, unknown>;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an ORDER BY clause
+     */
+    buildOrderClause(order: Order, options?: {
+        replacements?: Record<string, unknown>;
+    }): string;
+    /**
+     * Build a LIMIT/OFFSET clause
+     */
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    /**
+     * Build an INSERT query with RETURNING support
+     */
+    buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an UPSERT query for PostgreSQL
+     * Uses ON CONFLICT ... DO UPDATE SET syntax
+     */
+    buildUpsertQuery(tableName: string, values: Record<string, unknown>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a PostgreSQL 15+ `MERGE INTO ... USING ... ON ... WHEN [NOT] MATCHED ...` statement.
+     *
+     * This is an additional builder alongside `buildUpsertQuery` (which uses `INSERT ... ON
+     * CONFLICT` for simple single-condition upserts). `MERGE` is useful when the merge logic
+     * needs multiple conditional branches (e.g. delete on one condition, update on another,
+     * insert otherwise) or when merging from an arbitrary source table/subquery rather than
+     * a single row of values.
+     *
+     * @param targetTable - Table being merged into
+     * @param source - Source table/subquery to merge from, with an alias
+     * @param onCondition - Raw SQL join condition (e.g. `target.id = source.id`)
+     * @param whenMatched - Ordered list of `WHEN MATCHED [AND condition] THEN ...` clauses
+     * @param whenNotMatched - Ordered list of `WHEN NOT MATCHED [AND condition] THEN ...` clauses
+     * @param options - Optional RETURNING clause (PostgreSQL 17+)
+     */
+    buildMergeQuery(targetTable: string, source: {
+        table: string;
+        alias?: string;
+    }, onCondition: string, whenMatched?: MergeWhenMatchedClause[], whenNotMatched?: MergeWhenNotMatchedClause[], options?: {
+        returning?: boolean | string[];
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an increment query
+     * @param tableName - Table name
+     * @param fields - Fields to increment
+     * @param where - Where clause
+     * @param options - Query options (by: number)
+     */
+    buildIncrementQuery(tableName: string, fields: string | string[] | Record<string, number>, where: WhereOptions, options?: {
+        by?: number;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an UPDATE query with RETURNING support
+     */
+    buildUpdateQuery(tableName: string, values: Record<string, unknown>, where: WhereOptions, options?: DUpdateOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a DELETE query with RETURNING support
+     */
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Check if a value is a function expression (fn('COUNT', ...))
+     */
+    private isFnExpression;
+    /**
+     * Check if a value is a column expression (col('name'))
+     */
+    private isColExpression;
+    /**
+     * Check if a value is a literal expression (literal('sql'))
+     */
+    /**
+     * Render a literal expression, substituting any `bindings` into its `?`
+     * placeholders with dialect-correct escaping. `literalExpr(sql)` with no
+     * bindings is unchanged; `literalExpr('x > ?', [v])` no longer requires the
+     * caller to concatenate the value into the string themselves.
+     */
+    private literalSql;
+    private isLiteralExpression;
+    /**
+     * Compile a function expression to SQL
+     */
+    private compileFnExpression;
+    /**
+     * Build SELECT clause with support for function expressions and aliases
+     * Handles: 'field', ['field'], ['field', 'alias'], [fn('COUNT', 'id'), 'count']
+     */
+    private buildSelectClause;
+    /**
+     * Build GROUP BY clause with support for function expressions and aliases
+     * Handles: 'field', ['field1', 'field2'], [[fn('COUNT', 'id'), 'count']]
+     */
+    private buildGroupByClause;
+    /**
+     * Build a WHERE clause condition using standard operators (Op.gt, Op.eq, etc.)
+     * PostgreSQL uses $1, $2, etc. for parameter placeholders
+     */
+    private buildCondition;
+    /**
+     * Build a HAVING clause with support for standard Op operators
+     */
+    private buildHavingClause;
+    /**
+     * Build a SELECT query with PostgreSQL-specific features
+     */
+    /**
+     * Build a `WITH [RECURSIVE] name [(cols)] AS (query), ...` clause from
+     * `SelectOptions.cte`. Nested `SelectOptions` queries are compiled via a
+     * recursive call to `buildSelectQuery`; raw SQL strings are used verbatim.
+     *
+     * Placeholder values contributed by CTE subqueries are returned in the
+     * order they appear in the rendered SQL so callers can prepend them to the
+     * overall query's `values` array before renumbering downstream clauses.
+     */
+    buildWithClause(ctes: CTEOption[]): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Shift all `$n` positional placeholders in a SQL fragment by `offset`.
+     * Used to keep parameter numbering correct when a clause built in
+     * isolation (which always numbers its own placeholders starting at `$1`)
+     * is appended after other clauses that already consumed placeholder slots.
+     */
+    private offsetParamPlaceholders;
+    buildSelectQuery(options: SelectOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Escape a value for use in a PostgreSQL array literal
+     */
+    escapeArray(values: unknown[]): string;
+    /**
+     * Build an array contains operator query (@>)
+     * SELECT * FROM table WHERE column @> ARRAY['elem1', 'elem2']
+     */
+    buildArrayContains(column: string, values: unknown[]): string;
+    /**
+     * Build an array contained by operator query (<@)
+     * SELECT * FROM table WHERE column <@ ARRAY['elem1', 'elem2']
+     */
+    buildArrayContainedBy(column: string, values: unknown[]): string;
+    /**
+     * Build an array overlaps operator query (&&)
+     * SELECT * FROM table WHERE column && ARRAY['elem1', 'elem2']
+     */
+    buildArrayOverlaps(column: string, values: unknown[]): string;
+    /**
+     * Build an array ANY operator query
+     * SELECT * FROM table WHERE 'value' = ANY(column)
+     */
+    buildArrayAny(column: string, value: unknown): string;
+    /**
+     * Build an array ALL operator query
+     * SELECT * FROM table WHERE 'value' = ALL(column)
+     * or with comparison: SELECT * FROM table WHERE value > ALL(column)
+     */
+    buildArrayAll(column: string, value: unknown, operator?: string): string;
+    /**
+     * Build a full-text search query
+     */
+    buildFullTextSearchQuery(tableName: string, searchColumns: string[], searchTerm: string, options?: {
+        language?: string;
+        ranking?: 'ts_rank' | 'ts_rank_cd';
+        orderBy?: Order;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a JSON/JSONB path query
+     */
+    buildJsonPathQuery(column: string, path: string, value: unknown, operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | '~' | '~*' | '@>' | '<@' | '?' | '?|'): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Get PostgreSQL specific lock options
+     */
+    getLockOptions(lock: any): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Acquire a session-level advisory lock (`pg_advisory_lock`), blocking until it is available.
+     * Pass a single 64-bit key, or two 32-bit keys (`key`, `key2`) for the two-argument form.
+     *
+     * Returns a handle whose `release()` calls `pg_advisory_unlock` and returns the underlying
+     * connection back to the pool. Always call `release()` (e.g. in a `finally` block) - until
+     * you do, this holds one connection out of the pool for the lifetime of the lock.
+     */
+    pgAdvisoryLock(key: number | bigint, key2?: number): Promise<{
+        release: () => Promise<void>;
+    }>;
+    /**
+     * Attempt to acquire a session-level advisory lock without blocking
+     * (`pg_try_advisory_lock`). Resolves immediately with `acquired: false` if the lock is
+     * already held elsewhere. When `acquired` is `true`, call `release()` to unlock and return
+     * the underlying connection to the pool; when `false`, the connection has already been
+     * returned to the pool and `release()` is a no-op.
+     */
+    pgTryAdvisoryLock(key: number | bigint, key2?: number): Promise<{
+        acquired: boolean;
+        release: () => Promise<void>;
+    }>;
+    /**
+     * Escape a single-quoted string value (replace ' with '').
+     */
+    private escapeStringValue;
+    /**
+     * Build the shared WITH-clause attribute list used by both CREATE USER and
+     * ALTER USER.  Returns a (possibly empty) array of attribute tokens.
+     */
+    private buildUserAttributes;
+    /**
+     * Build a CREATE USER statement.
+     *
+     * PostgreSQL treats users as roles with LOGIN.  Supported options:
+     *   ifNotExists, password, superuser, createdb, createrole, login,
+     *   replication, bypassrls, maxConnections, accountLocked, expirePassword,
+     *   defaultRole, requireSSL (noted but skipped — not a standard PG attribute).
+     */
+    buildCreateUserQuery(username: string, options?: any): string;
+    /**
+     * Build an ALTER USER statement.
+     *
+     * Supports the same attribute options as buildCreateUserQuery plus
+     * `options.renameTo` to rename the role.
+     */
+    buildAlterUserQuery(username: string, options: any): string;
+    /**
+     * Build a DROP USER statement.
+     *
+     * Options: ifExists, cascade, restrict.
+     */
+    buildDropUserQuery(username: string, options?: any): string;
+    /**
+     * Return a query that lists all PostgreSQL users (roles with LOGIN).
+     */
+    getUsersQuery(): string;
+    /**
+     * Create a database user
+     */
+    createUser(username: string, options?: Record<string, any>): Promise<void>;
+    /**
+     * List all PostgreSQL login users (roles with LOGIN).
+     * Thin wrapper around getUsersQuery() so callers don't need to build/parse SQL themselves.
+     */
+    listUsers(): Promise<string[]>;
+    /**
+     * Drop a database user (PostgreSQL treats users as roles; DROP USER is an alias for DROP ROLE).
+     */
+    dropUser(username: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a role (PostgreSQL role without LOGIN by default, distinguishing it from createUser()).
+     */
+    createRole(roleName: string, options?: Record<string, any>): Promise<void>;
+    /**
+     * Drop a role.
+     */
+    dropRole(roleName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * List all PostgreSQL roles (pg_roles), including non-login roles.
+     */
+    listRoles(): Promise<string[]>;
+    /**
+     * Simple GRANT wrapper: GRANT <privilege> ON <table> TO <grantee>.
+     * For more advanced scopes (database/schema/column-level, WITH GRANT OPTION, etc.)
+     * use buildGrantQuery() directly.
+     */
+    grant(privilege: string, on: string, to: string): Promise<void>;
+    /**
+     * Simple REVOKE wrapper: REVOKE <privilege> ON <table> FROM <grantee>.
+     */
+    revoke(privilege: string, on: string, from: string): Promise<void>;
+    /**
+     * Map a generic privilege name to a PostgreSQL privilege name.
+     * Returns null when the privilege has no PostgreSQL equivalent and
+     * should be silently skipped.
+     */
+    private mapPrivilege;
+    /**
+     * Build the ON <scope> clause for GRANT / REVOKE.
+     *
+     * Scope shapes:
+     *   { level: 'global' }
+     *   { level: 'database', database: 'dbname' }
+     *   { level: 'schema',   schema: 'schemaname' }
+     *   { level: 'table',    table: 'tablename' }
+     *   { level: 'column',   table: 'tablename', columns: ['col1', 'col2'] }
+     *   { level: 'sequence', schema: 'schemaname' }
+     */
+    private buildGrantScope;
+    /**
+     * Build a GRANT statement.
+     *
+     * options.privileges  — string | string[]  (e.g. ['SELECT', 'INSERT'])
+     * options.on          — scope object (see buildGrantScope)
+     * options.to          — string | string[]  (grantees)
+     * options.withGrantOption — boolean
+     * options.asUser      — string (GRANTED BY, PG 14+)
+     *
+     * For column-level grants (options.on.level === 'column') the columns are
+     * embedded in each privilege token: SELECT (col1, col2).
+     */
+    buildGrantQuery(options: any): string;
+    /**
+     * Build a REVOKE statement.
+     *
+     * options.privileges      — string | string[]
+     * options.on              — scope object (same as buildGrantQuery)
+     * options.from            — string | string[]  (revokees)
+     * options.grantOptionFor  — boolean (revoke only the GRANT OPTION)
+     * options.cascade         — boolean
+     * options.restrict        — boolean
+     */
+    buildRevokeQuery(options: any): string;
+    /**
+     * Return a query that shows the privileges granted to a specific user/role.
+     * The optional `host` parameter is ignored — PostgreSQL has no host concept.
+     */
+    buildShowGrantsQuery(username: string, _host?: string): string;
+    /**
+     * PostgreSQL applies privilege changes automatically — FLUSH PRIVILEGES is
+     * a MySQL concept.  Return a no-op with an explanatory comment.
+     */
+    buildFlushPrivilegesQuery(): string;
+    /**
+     * Build a CREATE ROLE statement.
+     *
+     * Unlike CREATE USER, NOLOGIN is the default for roles.  Pass
+     * `options.login = true` to enable login.
+     *
+     * Supported options: ifNotExists, login, password, superuser, createdb,
+     * createrole, inherit, replication, bypassrls, maxConnections,
+     * expirePassword, accountLocked.
+     */
+    buildCreateRoleQuery(roleName: string, options?: any): string;
+    /**
+     * Build a DROP ROLE statement.
+     *
+     * Options: ifExists, cascade.
+     */
+    buildDropRoleQuery(roleName: string, options?: any): string;
+    /**
+     * Build a GRANT <role> TO <members> statement.
+     *
+     * Options: withAdminOption.
+     */
+    buildGrantRoleQuery(role: string, to: string | string[], options?: any): string;
+    /**
+     * Build a REVOKE <role> FROM <members> statement.
+     *
+     * Options: adminOptionFor, cascade.
+     */
+    buildRevokeRoleQuery(role: string, from: string | string[], options?: any): string;
+    /**
+     * Return a query that lists all PostgreSQL roles that cannot log in
+     * (i.e. "group roles" as opposed to user roles).
+     */
+    getRolesQuery(): string;
+    /**
+     * Generate SQL for creating a PostgreSQL database
+     */
+    createDatabaseSQL(options: {
+        name: string;
+        encoding?: string;
+        lcCollate?: string;
+        lcCtype?: string;
+        template?: string;
+        tablespace?: string;
+        isTemplate?: boolean;
+    }): string;
+    /**
+     * Generate SQL for dropping a PostgreSQL database
+     */
+    dropDatabaseSQL(name: string): string;
+    /**
+     * Generate SQL for creating a savepoint
+     */
+    createSavepointSQL(name?: string): string;
+    /**
+     * Generate SQL for releasing a savepoint
+     */
+    releaseSavepointSQL(name: string): string;
+    /**
+     * Generate SQL for rolling back to a savepoint
+     */
+    rollbackToSavepointSQL(name: string): string;
+    /**
+     * Build a jsonb_to_recordset expression to shred a JSON array into relational rows.
+     * Postgres only gained a native `JSON_TABLE` in PG17+; `jsonb_to_recordset(...) AS
+     * alias(col type, ...)` has been available since 9.4 and matches how the rest of this
+     * dialect's JSON handling (jsonb operators, `buildJsonPathQuery`) already works, so it
+     * is used here for broad version compatibility.
+     * Per-column `path` is not used — jsonb_to_recordset matches columns to top-level JSON
+     * object keys by name. `rowPath` (dot-notation, e.g. `$.items`) is used only to narrow
+     * down to the nested array being expanded, via the `#>` path-extraction operator.
+     * Postgres: jsonb_to_recordset(expr #> '{items}') AS alias(name type, ...)
+     */
+    buildJsonTable(jsonExpression: string, rowPath: string, columns: Array<{
+        name: string;
+        type?: string;
+        path?: string;
+        forOrdinality?: boolean;
+    }>, alias: string): string;
+}
+/**
+ * PostgreSQL-specific transaction class with isolation level support and savepoints
+ */
+export declare class PostgresTransaction implements Transaction {
+    id: string;
+    finished: boolean;
+    options: TransactionOptions;
+    parent: Transaction | null;
+    savepoints: string[];
+    client: PoolClient | null;
+    private savepointCount;
+    constructor(client: PoolClient, depth: number, options?: TransactionOptions);
+    /**
+     * Create a savepoint
+     */
+    createSavepoint(name?: string): Promise<string>;
+    /**
+     * Rollback to a savepoint
+     */
+    rollbackToSavepoint(name: string): Promise<void>;
+    /**
+     * Release a savepoint
+     */
+    releaseSavepoint(name: string): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    /**
+     * Acquire a transaction-scoped (`pg_advisory_xact_lock`) exclusive advisory lock. Unlike
+     * session-level advisory locks, xact-scoped locks are automatically released when this
+     * transaction commits or rolls back - there is no explicit unlock call (Postgres does not
+     * provide one; see the "Advisory Locks" section of the docs).
+     *
+     * Pass a single 64-bit key, or two 32-bit keys (`key`, `key2`) to use the two-argument form.
+     */
+    advisoryXactLock(key: number | bigint, key2?: number): Promise<void>;
+    /**
+     * Attempt to acquire a transaction-scoped advisory lock without blocking
+     * (`pg_try_advisory_xact_lock`). Returns `true` if the lock was acquired. The lock, if
+     * acquired, is released automatically when this transaction commits or rolls back.
+     */
+    tryAdvisoryXactLock(key: number | bigint, key2?: number): Promise<boolean>;
+}
+export interface PostgresDialectOptions extends DialectOptions {
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+    ssl?: any;
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+    statementTimeout?: number;
+    queryTimeout?: number;
+    types?: any;
+}
+/**
+ * Create a new PostgreSQL dialect instance
+ */
+export declare function createPostgresDialect(options?: PostgresDialectOptions): PostgresDialect;
+export default PostgresDialect;