PgConnection
Native PostgreSQL sessions built on the PgProtocol wire codec.
Sessions support queries, streaming, LISTEN/NOTIFY, cancellation, and
exclusive ownership for transactions.
Constructors
Connects and authenticates a single PostgreSQL session.
Details
The transport, optional SSLRequest, startup, and authentication steps run
under connectTimeout (5 seconds by default). The effect resolves once the
backend sends ReadyForQuery. When the scope closes, the
session sends Terminate and ends the socket.
When ssl is enabled, a server that rejects SSLRequest fails the
connection. Unix sockets and custom streams should set ssl.servername
explicitly.
Signature
declare function make(options: Config): Effect<PgConnection, SqlError, Scope>Models
Connection settings for a PostgreSQL session.
Details
A url is parsed as a libpq URI (postgres:// or postgresql://);
explicit fields win over anything the URL carries. A stream factory wins
over host, port, and path. A path is used verbatim as the unix
socket path, while a host beginning with / is treated as a socket
directory and expands to ${host}/.s.PGSQL.${port}.
Prepared statements are enabled by default and limited by
preparedStatementCacheSize. Disable them for statement-mode poolers or
workloads that generate unique SQL. Streams always use unnamed statements.
With multiplex enabled, unpinned queries from multiple fibers are
pipelined. Transactions, streams, and listeners remain exclusive. An
unpinned multiplexed connection cannot be interrupted because cancellation
could affect another fiber's query.
Signature
interface Config { readonly applicationName?: string; readonly connectTimeout?: Input; readonly database?: string; readonly host?: string; readonly maxMessageSize?: number; readonly multiplex?: boolean; readonly password?: Redacted<string>; readonly path?: string; readonly port?: number; readonly prepare?: boolean; readonly preparedStatementCacheSize?: number; readonly ssl?: boolean | ConnectionOptions; readonly stream?: () => Duplex; readonly types?: Registry; readonly url?: Redacted<string>; readonly username?: string;}Metadata for one result column.
Signature
interface Field { readonly dataTypeId: number; readonly name: string;}Notification interface
A NOTIFY message received while listening on a channel.
Signature
interface Notification { readonly channel: string; readonly payload: string; readonly processId: number;}PgConnection interface
A connected and authenticated PostgreSQL session.
Signature
interface PgConnection { readonly "~@effect/sql-pg/PgConnection": "~@effect/sql-pg/PgConnection"; readonly config: Config; readonly interrupt: Effect<void>; readonly listen: (channel: string) => Effect<Dequeue<Notification, never>, SqlError, Scope>; readonly pin: Effect<PgConnection, never, Scope>; readonly processId: number; readonly query: (sql: string, params?: readonly Array<unknown>, prepare?: boolean) => Effect<Result, SqlError>; readonly queryValues: (sql: string, params?: readonly Array<unknown>, prepare?: boolean) => Effect<readonly Array<readonly Array<unknown>>, SqlError>; readonly stream: (sql: string, params?: readonly Array<unknown>) => Stream<Row, SqlError>;}The result of a query.
Signature
interface Result { readonly command: string; readonly fields: readonly Array<Field>; readonly oid: number | null; readonly rowCount: number; readonly rows: readonly Array<Row>;}An object result row keyed by column name.
Signature
interface Row { [column: string]: unknown;}Services
PgConnection
The service tag for PgConnection.
Signature
declare const PgConnection: Service<PgConnection, PgConnection>