PgConnection unstable
Native PostgreSQL sessions built on the PgProtocol wire codec.
Details
Sessions support queries, streaming, LISTEN/NOTIFY, cancellation, and
exclusive ownership for transactions.
Constructors
Connects and authenticates a single PostgreSQL session.
Details
Password resolution, transport, optional SSLRequest, startup, and
authentication run under connectTimeout (5 seconds by default). The effect
resolves when the backend sends ReadyForQuery. Closing the scope sends
Terminate and ends the socket.
Use sslmode=require or explicit ssl: true to require encryption.
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}.
URL modes sslmode=prefer and sslmode=allow try TLS first, falling back
to plaintext only when the server answers SSLRequest with N. Unlike
libpq, allow also tries TLS first. Certificate verification stays enabled
unless explicitly disabled through ssl options.
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 keepAlive?: Input; readonly maxMessageSize?: number; readonly multiplex?: boolean; readonly password?: Redacted<string> | Effect<Redacted<string>, never, never>; readonly path?: string; readonly port?: number; readonly prepare?: boolean; readonly preparedStatementCacheSize?: number; readonly ssl?: boolean | ConnectionOptions; readonly startupOptions?: string; readonly startupParameters?: Readonly<Record<string, string>>; 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;}A NOTIFY message received while listening on a channel.
Signature
interface Notification { readonly channel: string; readonly payload: string; readonly processId: number;}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, SqlError>, 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
unstableThe service tag for PgConnection.
Signature
declare const PgConnection: Service<PgConnection, PgConnection>